?????????? ????????? - ??????????????? - /home/agenciai/public_html/cd38d8/blib.zip
???????
PK T �[ AQ� � man3/Test::Pod.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Pod 3" .TH Test::Pod 3 "2018-04-19" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Pod \- check for POD errors in files .SH "VERSION" .IX Header "VERSION" Version 1.52 .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\f(CW\*(C`Test::Pod\*(C'\fR lets you check the validity of a \s-1POD\s0 file, and report its results in standard \f(CW\*(C`Test::Simple\*(C'\fR fashion. .PP .Vb 2 \& use Test::Pod tests => $num_tests; \& pod_file_ok( $file, "Valid POD file" ); .Ve .PP Module authors can include the following in a \fIt/pod.t\fR file and have \f(CW\*(C`Test::Pod\*(C'\fR automatically find and check all \s-1POD\s0 files in a module distribution: .PP .Vb 4 \& use Test::More; \& eval "use Test::Pod 1.00"; \& plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; \& all_pod_files_ok(); .Ve .PP You can also specify a list of files to check, using the \&\f(CW\*(C`all_pod_files()\*(C'\fR function supplied: .PP .Vb 6 \& use strict; \& use Test::More; \& eval "use Test::Pod 1.00"; \& plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; \& my @poddirs = qw( blib script ); \& all_pod_files_ok( all_pod_files( @poddirs ) ); .Ve .PP Or even (if you're running under Apache::Test): .PP .Vb 4 \& use strict; \& use Test::More; \& eval "use Test::Pod 1.00"; \& plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; \& \& my @poddirs = qw( blib script ); \& use File::Spec::Functions qw( catdir updir ); \& all_pod_files_ok( \& all_pod_files( map { catdir updir, $_ } @poddirs ) \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Check \s-1POD\s0 files for errors or warnings in a test file, using \&\f(CW\*(C`Pod::Simple\*(C'\fR to do the heavy lifting. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "pod_file_ok( FILENAME[, \s-1TESTNAME\s0 ] )" .IX Subsection "pod_file_ok( FILENAME[, TESTNAME ] )" \&\f(CW\*(C`pod_file_ok()\*(C'\fR will okay the test if the \s-1POD\s0 parses correctly. Certain conditions are not reported yet, such as a file with no pod in it at all. .PP When it fails, \f(CW\*(C`pod_file_ok()\*(C'\fR will show any pod checking errors as diagnostics. .PP The optional second argument \s-1TESTNAME\s0 is the name of the test. If it is omitted, \f(CW\*(C`pod_file_ok()\*(C'\fR chooses a default test name \*(L"\s-1POD\s0 test for \s-1FILENAME\*(R".\s0 .SS "all_pod_files_ok( [@entries] )" .IX Subsection "all_pod_files_ok( [@entries] )" Checks all the files under \f(CW@entries\fR for valid \s-1POD.\s0 It runs \&\fBall_pod_files()\fR on directories and assumes everything else to be a file to be tested. It calls the \f(CW\*(C`plan()\*(C'\fR function for you (one test for each file), so you can't have already called \f(CW\*(C`plan\*(C'\fR. .PP If \f(CW@entries\fR is empty or not passed, the function finds all \s-1POD\s0 files in files in the \fIblib\fR directory if it exists, or the \fIlib\fR directory if not. A \s-1POD\s0 file matches the conditions specified below in \*(L"all_pod_files\*(R". .PP If you're testing a module, just make a \fIt/pod.t\fR: .PP .Vb 4 \& use Test::More; \& eval "use Test::Pod 1.00"; \& plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; \& all_pod_files_ok(); .Ve .PP Returns true if all pod files are ok, or false if any fail. .SS "all_pod_files( [@dirs] )" .IX Xref "all_pod_files" .IX Subsection "all_pod_files( [@dirs] )" Returns a list of all the \s-1POD\s0 files in \fI\f(CI@dirs\fI\fR and in directories below. If no directories are passed, it defaults to \fIblib\fR if \fIblib\fR exists, or else \&\fIlib\fR if not. Skips any files in \fI\s-1CVS\s0\fR, \fI.svn\fR, \fI.git\fR and similar directories. See \f(CW%Test::Pod::ignore_dirs\fR for a list of them. .PP A \s-1POD\s0 file is: .IP "\(bu" 4 Any file that ends in \fI.pl\fR, \fI.PL\fR, \fI.pm\fR, \fI.pod\fR, \fI.psgi\fR or \fI.t\fR. .IP "\(bu" 4 Any file that has a first line with a shebang and \*(L"perl\*(R" on it. .IP "\(bu" 4 Any file that ends in \fI.bat\fR and has a first line with \*(L"\-\-*\-Perl\-*\-\-\*(R" on it. .PP The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself. .SH "SUPPORT" .IX Header "SUPPORT" This module is managed in an open GitHub repository <http://github.com/perl-pod/test-pod/>. Feel free to fork and contribute, or to clone <git://github.com/perl\-pod/test\-pod.git> and send patches! .PP Found a bug? Please post <http://github.com/perl-pod/test-pod/issues> or email <mailto:bug-test-pod@rt.cpan.org> a report! .SH "AUTHORS" .IX Header "AUTHORS" .IP "David E. Wheeler <david@justatheory.com>" 4 .IX Item "David E. Wheeler <david@justatheory.com>" Current maintainer. .ie n .IP "Andy Lester ""<andy at petdance.com>""" 4 .el .IP "Andy Lester \f(CW<andy at petdance.com>\fR" 4 .IX Item "Andy Lester <andy at petdance.com>" Maintainer emeritus. .IP "brian d foy" 4 .IX Item "brian d foy" Original author. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks brian d foy for the original code, and to these folks for contributions: .IP "\(bu" 4 Andy Lester .IP "\(bu" 4 David E. Wheeler .IP "\(bu" 4 Paul Miller .IP "\(bu" 4 Peter Edwards .IP "\(bu" 4 Luca Ferrari .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2006\-2010, Andy Lester; 2010\-2015 David E. Wheeler. Some Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK T �[ man3/.existsnu �[��� PK T �[ man1/.existsnu �[��� PK T �[ arch/.existsnu �[��� PK T �[ arch/auto/Test/Pod/.existsnu �[��� PK T �[ bin/.existsnu �[��� PK T �[ script/.existsnu �[��� PK T �[vB~� � lib/Test/Pod.pmnu ��6�$ package Test::Pod; use strict; use warnings; =head1 NAME Test::Pod - check for POD errors in files =head1 VERSION Version 1.52 =cut our $VERSION = '1.52'; =head1 SYNOPSIS C<Test::Pod> lets you check the validity of a POD file, and report its results in standard C<Test::Simple> fashion. use Test::Pod tests => $num_tests; pod_file_ok( $file, "Valid POD file" ); Module authors can include the following in a F<t/pod.t> file and have C<Test::Pod> automatically find and check all POD files in a module distribution: use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; all_pod_files_ok(); You can also specify a list of files to check, using the C<all_pod_files()> function supplied: use strict; use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; my @poddirs = qw( blib script ); all_pod_files_ok( all_pod_files( @poddirs ) ); Or even (if you're running under L<Apache::Test>): use strict; use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; my @poddirs = qw( blib script ); use File::Spec::Functions qw( catdir updir ); all_pod_files_ok( all_pod_files( map { catdir updir, $_ } @poddirs ) ); =head1 DESCRIPTION Check POD files for errors or warnings in a test file, using C<Pod::Simple> to do the heavy lifting. =cut use Test::Builder; use Pod::Simple; our %ignore_dirs = ( '.bzr' => 'Bazaar', '.git' => 'Git', '.hg' => 'Mercurial', '.pc' => 'quilt', '.svn' => 'Subversion', CVS => 'CVS', RCS => 'RCS', SCCS => 'SCCS', _darcs => 'darcs', _sgbak => 'Vault/Fortress', ); my $Test = Test::Builder->new; sub import { my $self = shift; my $caller = caller; for my $func ( qw( pod_file_ok all_pod_files all_pod_files_ok ) ) { no strict 'refs'; *{$caller."::".$func} = \&$func; } $Test->exported_to($caller); $Test->plan(@_); } sub _additional_test_pod_specific_checks { my ($ok, $errata, $file) = @_; return $ok; } =head1 FUNCTIONS =head2 pod_file_ok( FILENAME[, TESTNAME ] ) C<pod_file_ok()> will okay the test if the POD parses correctly. Certain conditions are not reported yet, such as a file with no pod in it at all. When it fails, C<pod_file_ok()> will show any pod checking errors as diagnostics. The optional second argument TESTNAME is the name of the test. If it is omitted, C<pod_file_ok()> chooses a default test name "POD test for FILENAME". =cut sub pod_file_ok { my $file = shift; my $name = @_ ? shift : "POD test for $file"; if ( !-f $file ) { $Test->ok( 0, $name ); $Test->diag( "$file does not exist" ); return; } my $checker = Pod::Simple->new; $checker->output_string( \my $trash ); # Ignore any output $checker->parse_file( $file ); my $ok = !$checker->any_errata_seen; $ok = _additional_test_pod_specific_checks( $ok, ($checker->{errata}||={}), $file ); $name .= ' (no pod)' if !$checker->content_seen; $Test->ok( $ok, $name ); if ( !$ok ) { my $lines = $checker->{errata}; for my $line ( sort { $a<=>$b } keys %$lines ) { my $errors = $lines->{$line}; $Test->diag( "$file ($line): $_" ) for @$errors; } } return $ok; } # pod_file_ok =head2 all_pod_files_ok( [@entries] ) Checks all the files under C<@entries> for valid POD. It runs L<all_pod_files()> on directories and assumes everything else to be a file to be tested. It calls the C<plan()> function for you (one test for each file), so you can't have already called C<plan>. If C<@entries> is empty or not passed, the function finds all POD files in files in the F<blib> directory if it exists, or the F<lib> directory if not. A POD file matches the conditions specified below in L</all_pod_files>. If you're testing a module, just make a F<t/pod.t>: use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; all_pod_files_ok(); Returns true if all pod files are ok, or false if any fail. =cut sub all_pod_files_ok { my @args = @_ ? @_ : _starting_points(); my @files = map { -d $_ ? all_pod_files($_) : $_ } @args; unless (@files) { $Test->skip_all( "No files found in (@args)\n" ); return 1; } $Test->plan( tests => scalar @files ); my $ok = 1; foreach my $file ( @files ) { pod_file_ok( $file ) or undef $ok; } return $ok; } =head2 all_pod_files( [@dirs] ) X<all_pod_files> Returns a list of all the POD files in I<@dirs> and in directories below. If no directories are passed, it defaults to F<blib> if F<blib> exists, or else F<lib> if not. Skips any files in F<CVS>, F<.svn>, F<.git> and similar directories. See C<%Test::Pod::ignore_dirs> for a list of them. A POD file is: =over 4 =item * Any file that ends in F<.pl>, F<.PL>, F<.pm>, F<.pod>, F<.psgi> or F<.t>. =item * Any file that has a first line with a shebang and "perl" on it. =item * Any file that ends in F<.bat> and has a first line with "--*-Perl-*--" on it. =back The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself. =cut sub all_pod_files { my @pod; require File::Find; File::Find::find({ preprocess => sub { grep { !exists $ignore_dirs{$_} || !-d File::Spec->catfile($File::Find::dir, $_) } @_ }, wanted => sub { -f $_ && _is_perl($_) && push @pod, $File::Find::name }, no_chdir => 1, }, @_ ? @_ : _starting_points()); return @pod; } sub _starting_points { return 'blib' if -e 'blib'; return 'lib'; } sub _is_perl { my $file = shift; # accept as a Perl file everything that ends with a well known Perl suffix ... return 1 if $file =~ /[.](?:PL|p(?:[lm]|od|sgi)|t)$/; open my $fh, '<', $file or return; my $first = <$fh>; close $fh; return unless $first; # ... or that has a she-bang as first line ... return 1 if $first =~ /^#!.*perl/; # ... or that is a .bat ad has a Perl comment line first return 1 if $file =~ /[.]bat$/i && $first =~ /--[*]-Perl-[*]--/; return; } =head1 SUPPORT This module is managed in an open L<GitHub repository|http://github.com/perl-pod/test-pod/>. Feel free to fork and contribute, or to clone L<git://github.com/perl-pod/test-pod.git> and send patches! Found a bug? Please L<post|http://github.com/perl-pod/test-pod/issues> or L<email|mailto:bug-test-pod@rt.cpan.org> a report! =head1 AUTHORS =over =item David E. Wheeler <david@justatheory.com> Current maintainer. =item Andy Lester C<< <andy at petdance.com> >> Maintainer emeritus. =item brian d foy Original author. =back =head1 ACKNOWLEDGEMENTS Thanks brian d foy for the original code, and to these folks for contributions: =over =item * Andy Lester =item * David E. Wheeler =item * Paul Miller =item * Peter Edwards =item * Luca Ferrari =back =head1 COPYRIGHT AND LICENSE Copyright 2006-2010, Andy Lester; 2010-2015 David E. Wheeler. Some Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut 1; PK T �[ lib/Test/.existsnu �[��� PK T �[ lib/auto/Test/Pod/.existsnu �[��� PK W �[�3zd. d. " man3/Template::Toolkit::Simple.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Toolkit::Simple 3" .TH Template::Toolkit::Simple 3 "2014-12-09" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Toolkit::Simple \- A Simple Interface to Template Toolkit .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Toolkit::Simple; \& \& print tt \& \->path([\*(Aq./\*(Aq, \*(Aqtemplate/\*(Aq]) \& \->data(\*(Aqvalues.yaml\*(Aq) \& \->post_chomp \& \->render(\*(Aqfoo.tt\*(Aq); .Ve .PP or from the command line: .PP .Vb 1 \& tt\-render \-\-path=./:template/ \-\-data=values.yaml \-\-post\-chomp foo.tt .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Template Toolkit is the best Perl template framework. The only problem with it is that using it for simple stuff is a little bit cumbersome. Also there is no good utility for using it from the command line. .PP This module is a simple wrapper around Template Toolkit. It exports a function called \f(CW\*(C`tt\*(C'\fR which returns a new Template::Toolkit::Simple object. The object supports method calls for setting all the Template Toolkit options. .PP This module also installs a program called \f(CW\*(C`tt\-render\*(C'\fR which you can use from the command line to render templates with all the power of the Perl object. All of the object methods become command line arguments in the command line version. .SH "COMMAND LINE USAGE" .IX Header "COMMAND LINE USAGE" This command renders the named file and prints the output to \s-1STDOUT.\s0 If an error occurs, it is printed to \s-1STDERR.\s0 .PP .Vb 1 \& tt\-render [template\-options] file\-name .Ve .SH "TEMPLATE PATH" .IX Header "TEMPLATE PATH" When using Template::Toolkit::Simple or \f(CW\*(C`tt\-render\*(C'\fR, the most common parameters you will use are the main template file name and the directory of supporting templates. As a convenience, you can specify these together. .PP This: .PP .Vb 2 \& tt\->render(\*(Aqfoo//bar/baz.tt\*(Aq); \& > tt\-render foo//bar/baz.tt # command line version .Ve .PP is the same as: .PP .Vb 2 \& tt\->include_path(\*(Aqfoo/\*(Aq)\->render(\*(Aqbar/baz.tt\*(Aq); \& > tt\-render \-\-include_path=foo/ bar/baz.tt # command line version .Ve .PP Just use a double slash to separate the path from the template. This is extra handy on the command line, because (at least in Bash) tab completion still works after you specify the '//'. .SH "EXPORTED SUBROUTINES" .IX Header "EXPORTED SUBROUTINES" .IP "tt" 4 .IX Item "tt" Simply returns a new Template::Toolkit::Simple object. This is Simple sugar for: .Sp .Vb 1 \& Template::Toolkit::Simple\->new(); .Ve .Sp It takes no parameters. .SH "METHODS" .IX Header "METHODS" This section describes the methods that are not option setting methods. Those methods are described below. .IP "\fBnew()\fR" 4 .IX Item "new()" Return a new Template::Toolkit::Simple object. Takes no parameters. .ie n .IP "render($template, $data);" 4 .el .IP "render($template, \f(CW$data\fR);" 4 .IX Item "render($template, $data);" This is the method that actually renders the template. It is similar to the Template Toolkit \f(CW\*(C`process\*(C'\fR method, except that it actually returns the template result as a string. It returns undef if an error occurs. .Sp The \f(CW$data\fR field is optional and can be set with the \f(CW\*(C`data\*(C'\fR method. .Sp If you need more control, see the process command below: .ie n .IP "process($template, $data, $output, %options);" 4 .el .IP "process($template, \f(CW$data\fR, \f(CW$output\fR, \f(CW%options\fR);" 4 .IX Item "process($template, $data, $output, %options);" This command is simply a proxy to the Template Toolkit \f(CW\*(C`process\*(C'\fR command. All the parameters you give it are passed to the real \f(CW\*(C`process\*(C'\fR command and the result is returned. See Template for more information. .IP "output($filepath)" 4 .IX Item "output($filepath)" Specify a filepath to print the template result to. .IP "\fBerror()\fR" 4 .IX Item "error()" This method is a proxy to the Template Toolkit \f(CW\*(C`error\*(C'\fR method. It returns the error message if there was an error. .SH "OPTION METHODS" .IX Header "OPTION METHODS" All of the Template Toolkit options are available as methods to Template::Toolkit::Simple objects, and also as command line options to the \f(CW\*(C`tt\- render\*(C'\fR command. .PP For example, the \f(CW\*(C`POST_CHOMP\*(C'\fR options is available in the following ways: .PP .Vb 3 \& tt\->post_chomp # turn POST_CHOMP on \& tt\->post_chomp(1) # turn POST_CHOMP on \& tt\->post_chomp(0) # turn POST_CHOMP off \& \& \-\-post_chomp # turn POST_CHOMP on \& \-\-post\-chomp # same. use \- instead of _ \& \-\-post_chomp=1 # turn POST_CHOMP on \& \-\-post_chomp=0 # turn POST_CHOMP off .Ve .PP If the method functionality is not explained below, please refer to Template. .ie n .IP """config($file_name || $hash)""" 4 .el .IP "\f(CWconfig($file_name || $hash)\fR" 4 .IX Item "config($file_name || $hash)" If you have a common set of Template Toolkit options stored in a file, you can use this method to read and parse the file, and set the appropriate options. .Sp The currently supported file formats are \s-1YAML, JSON\s0 and \s-1XML.\s0 The format is determined by the file extension, so use the appropriate one. Note that XML::Simple is used to parse \s-1XML\s0 files and \s-1JSON::XS\s0 is used to parse \&\s-1JSON\s0 files. .ie n .IP """data($file_name || $hash)""" 4 .el .IP "\f(CWdata($file_name || $hash)\fR" 4 .IX Item "data($file_name || $hash)" Most templates use a hash object of data to access values while rendering. You can specify this data in a file or with a hash reference. .Sp The currently supported file formats are \s-1YAML, JSON\s0 and \s-1XML.\s0 The format is determined by the file extension, so use the appropriate one. Note the XML::Simple is used to parse \s-1XML\s0 files. .ie n .IP """include_path($template_directories)""" 4 .el .IP "\f(CWinclude_path($template_directories)\fR" 4 .IX Item "include_path($template_directories)" Default is undef .Sp This method allows you to specify the directories that are searched to find templates. You can specify this as a string containing a single directory, an array ref of strings containing directory names, or as a string containing multiple directories separated by ':'. .ie n .IP """path()""" 4 .el .IP "\f(CWpath()\fR" 4 .IX Item "path()" Default is undef .Sp This is a shorter name for \f(CW\*(C`include_path\*(C'\fR. It does the exact same thing. .ie n .IP """start_tag()""" 4 .el .IP "\f(CWstart_tag()\fR" 4 .IX Item "start_tag()" Default is '[%' .ie n .IP """end_tag()""" 4 .el .IP "\f(CWend_tag()\fR" 4 .IX Item "end_tag()" Default is '%]' .ie n .IP """tag_style()""" 4 .el .IP "\f(CWtag_style()\fR" 4 .IX Item "tag_style()" Default is 'template' .ie n .IP """pre_chomp()""" 4 .el .IP "\f(CWpre_chomp()\fR" 4 .IX Item "pre_chomp()" Default is 0 .ie n .IP """post_chomp()""" 4 .el .IP "\f(CWpost_chomp()\fR" 4 .IX Item "post_chomp()" Default is 0 .ie n .IP """trim()""" 4 .el .IP "\f(CWtrim()\fR" 4 .IX Item "trim()" Default is 0 .ie n .IP """interpolate()""" 4 .el .IP "\f(CWinterpolate()\fR" 4 .IX Item "interpolate()" Default is 0 .ie n .IP """anycase()""" 4 .el .IP "\f(CWanycase()\fR" 4 .IX Item "anycase()" Default is 0 .ie n .IP """delimiter()""" 4 .el .IP "\f(CWdelimiter()\fR" 4 .IX Item "delimiter()" Default is ':' .ie n .IP """absolute()""" 4 .el .IP "\f(CWabsolute()\fR" 4 .IX Item "absolute()" Default is 0 .ie n .IP """relative()""" 4 .el .IP "\f(CWrelative()\fR" 4 .IX Item "relative()" Default is 0 .ie n .IP """strict()""" 4 .el .IP "\f(CWstrict()\fR" 4 .IX Item "strict()" Default is 0 .ie n .IP """default()""" 4 .el .IP "\f(CWdefault()\fR" 4 .IX Item "default()" Default is undef .ie n .IP """blocks()""" 4 .el .IP "\f(CWblocks()\fR" 4 .IX Item "blocks()" Default is undef .ie n .IP """auto_reset()""" 4 .el .IP "\f(CWauto_reset()\fR" 4 .IX Item "auto_reset()" Default is 1 .ie n .IP """recursion()""" 4 .el .IP "\f(CWrecursion()\fR" 4 .IX Item "recursion()" Default is 0 .ie n .IP """eval_perl()""" 4 .el .IP "\f(CWeval_perl()\fR" 4 .IX Item "eval_perl()" Default is 0 .ie n .IP """pre_process()""" 4 .el .IP "\f(CWpre_process()\fR" 4 .IX Item "pre_process()" Default is undef .ie n .IP """post_process()""" 4 .el .IP "\f(CWpost_process()\fR" 4 .IX Item "post_process()" Default is undef .ie n .IP """process_template()""" 4 .el .IP "\f(CWprocess_template()\fR" 4 .IX Item "process_template()" Default is undef .Sp This is a proxy to the Template Toolkit \s-1PROCESS\s0 option. The \f(CW\*(C`process\*(C'\fR method is used to actually process a template. .ie n .IP """error_template()""" 4 .el .IP "\f(CWerror_template()\fR" 4 .IX Item "error_template()" Default is undef .Sp This is a proxy to the Template Toolkit \s-1ERROR\s0 option. The \f(CW\*(C`error()\*(C'\fR method returns the error message on a failure. .ie n .IP """debug()""" 4 .el .IP "\f(CWdebug()\fR" 4 .IX Item "debug()" Default is 0 .ie n .IP """cache_size()""" 4 .el .IP "\f(CWcache_size()\fR" 4 .IX Item "cache_size()" Default is undef .ie n .IP """compile_ext()""" 4 .el .IP "\f(CWcompile_ext()\fR" 4 .IX Item "compile_ext()" Default is undef .ie n .IP """compile_dir()""" 4 .el .IP "\f(CWcompile_dir()\fR" 4 .IX Item "compile_dir()" Default is undef .ie n .IP """encoding()""" 4 .el .IP "\f(CWencoding()\fR" 4 .IX Item "encoding()" Default is 'utf8' .SH "AUTHOR" .IX Header "AUTHOR" Ingy döt Net <ingy@cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2008\-2014. Ingy döt Net. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See <http://www.perl.com/perl/misc/Artistic.html> PK W �[ ) arch/auto/Template/Toolkit/Simple/.existsnu �[��� PK W �[�fe e script/tt-rendernu ȯ�� #!/usr/bin/env perl use Template::Toolkit::Simple; Template::Toolkit::Simple->_run_command(@ARGV); PK W �[ lib/Template/Toolkit/.existsnu �[��� PK W �[N?�� lib/Template/Toolkit/Simple.podnu ��6�$ =pod =for comment DO NOT EDIT. This Pod was generated by Swim v0.1.31. See http://github.com/ingydotnet/swim-pm#readme =encoding utf8 =head1 NAME Template::Toolkit::Simple - A Simple Interface to Template Toolkit =for html <a href="https://travis-ci.org/ingydotnet/template-toolkit-simple-pm"><img src="https://travis-ci.org/ingydotnet/template-toolkit-simple-pm.png" alt="template-toolkit-simple-pm"></a> <a href="https://coveralls.io/r/ingydotnet/template-toolkit-simple-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/template-toolkit-simple-pm/badge.png" alt="template-toolkit-simple-pm"></a> =head1 SYNOPSIS use Template::Toolkit::Simple; print tt ->path(['./', 'template/']) ->data('values.yaml') ->post_chomp ->render('foo.tt'); or from the command line: tt-render --path=./:template/ --data=values.yaml --post-chomp foo.tt =head1 DESCRIPTION Template Toolkit is the best Perl template framework. The only problem with it is that using it for simple stuff is a little bit cumbersome. Also there is no good utility for using it from the command line. This module is a simple wrapper around Template Toolkit. It exports a function called C<tt> which returns a new Template::Toolkit::Simple object. The object supports method calls for setting all the Template Toolkit options. This module also installs a program called C<tt-render> which you can use from the command line to render templates with all the power of the Perl object. All of the object methods become command line arguments in the command line version. =head1 COMMAND LINE USAGE This command renders the named file and prints the output to STDOUT. If an error occurs, it is printed to STDERR. tt-render [template-options] file-name =head1 TEMPLATE PATH When using Template::Toolkit::Simple or C<tt-render>, the most common parameters you will use are the main template file name and the directory of supporting templates. As a convenience, you can specify these together. This: tt->render('foo//bar/baz.tt'); > tt-render foo//bar/baz.tt # command line version is the same as: tt->include_path('foo/')->render('bar/baz.tt'); > tt-render --include_path=foo/ bar/baz.tt # command line version Just use a double slash to separate the path from the template. This is extra handy on the command line, because (at least in Bash) tab completion still works after you specify the '//'. =head1 EXPORTED SUBROUTINES =over =item tt Simply returns a new Template::Toolkit::Simple object. This is Simple sugar for: Template::Toolkit::Simple->new(); It takes no parameters. =back =head1 METHODS This section describes the methods that are not option setting methods. Those methods are described below. =over =item new() Return a new Template::Toolkit::Simple object. Takes no parameters. =item render($template, $data); This is the method that actually renders the template. It is similar to the Template Toolkit C<process> method, except that it actually returns the template result as a string. It returns undef if an error occurs. The C<$data> field is optional and can be set with the C<data> method. If you need more control, see the process command below: =item process($template, $data, $output, %options); This command is simply a proxy to the Template Toolkit C<process> command. All the parameters you give it are passed to the real C<process> command and the result is returned. See L<Template> for more information. =item output($filepath) Specify a filepath to print the template result to. =item error() This method is a proxy to the Template Toolkit C<error> method. It returns the error message if there was an error. =back =head1 OPTION METHODS All of the Template Toolkit options are available as methods to Template::Toolkit::Simple objects, and also as command line options to the C<tt- render> command. For example, the C<POST_CHOMP> options is available in the following ways: tt->post_chomp # turn POST_CHOMP on tt->post_chomp(1) # turn POST_CHOMP on tt->post_chomp(0) # turn POST_CHOMP off --post_chomp # turn POST_CHOMP on --post-chomp # same. use - instead of _ --post_chomp=1 # turn POST_CHOMP on --post_chomp=0 # turn POST_CHOMP off If the method functionality is not explained below, please refer to L<Template>. =over =item C<config($file_name || $hash)> If you have a common set of Template Toolkit options stored in a file, you can use this method to read and parse the file, and set the appropriate options. The currently supported file formats are YAML, JSON and XML. The format is determined by the file extension, so use the appropriate one. Note that XML::Simple is used to parse XML files and JSON::XS is used to parse JSON files. =item C<data($file_name || $hash)> Most templates use a hash object of data to access values while rendering. You can specify this data in a file or with a hash reference. The currently supported file formats are YAML, JSON and XML. The format is determined by the file extension, so use the appropriate one. Note the XML::Simple is used to parse XML files. =item C<include_path($template_directories)> Default is undef This method allows you to specify the directories that are searched to find templates. You can specify this as a string containing a single directory, an array ref of strings containing directory names, or as a string containing multiple directories separated by ':'. =item C<path()> Default is undef This is a shorter name for C<include_path>. It does the exact same thing. =item C<start_tag()> Default is '[%' =item C<end_tag()> Default is '%]' =item C<tag_style()> Default is 'template' =item C<pre_chomp()> Default is 0 =item C<post_chomp()> Default is 0 =item C<trim()> Default is 0 =item C<interpolate()> Default is 0 =item C<anycase()> Default is 0 =item C<delimiter()> Default is ':' =item C<absolute()> Default is 0 =item C<relative()> Default is 0 =item C<strict()> Default is 0 =item C<default()> Default is undef =item C<blocks()> Default is undef =item C<auto_reset()> Default is 1 =item C<recursion()> Default is 0 =item C<eval_perl()> Default is 0 =item C<pre_process()> Default is undef =item C<post_process()> Default is undef =item C<process_template()> Default is undef This is a proxy to the Template Toolkit PROCESS option. The C<process> method is used to actually process a template. =item C<error_template()> Default is undef This is a proxy to the Template Toolkit ERROR option. The C<error()> method returns the error message on a failure. =item C<debug()> Default is 0 =item C<cache_size()> Default is undef =item C<compile_ext()> Default is undef =item C<compile_dir()> Default is undef =item C<encoding()> Default is 'utf8' =back =head1 AUTHOR Ingy döt Net <ingy@cpan.org> =head1 COPYRIGHT AND LICENSE Copyright 2008-2014. Ingy döt Net. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See L<http://www.perl.com/perl/misc/Artistic.html> =cut PK W �[�w� � � lib/Template/Toolkit/Simple.pmnu ��6�$ use strict; use warnings; package Template::Toolkit::Simple; our $VERSION = '0.31'; use Encode; use Getopt::Long; use Template; use Template::Constants qw( :debug ); use YAML::XS; use base 'Exporter'; our @EXPORT = qw(tt); sub tt { return Template::Toolkit::Simple->new(); } my $default = { data => undef, config => undef, output => undef, encoding => 'utf8', include_path => undef, eval_perl => 0, start_tag => quotemeta('[' . '%'), end_tag => quotemeta('%' . ']'), tag_style => 'template', pre_chomp => 0, post_chomp => 0, trim => 0, interpolate => 0, anycase => 0, delimiter => ':', absolute => 0, relative => 0, strict => 0, default => undef, blocks => undef, auto_reset => 1, recursion => 0, pre_process => undef, post_process => undef, process_template => undef, error_template => undef, output_path => undef, debug => 0, cache_size => undef, compile_ext => undef, compile_dir => undef, }; my $abbreviations = { data => 'd', include_path => 'path|i', output => 'o', config => 'c', }; sub new { my $class = shift; return bless shift || {%$default}, $class; } sub field { my ($name, $value) = @_; return sub { my $self = shift; $self->{$name} = @_ ? shift : $value; return $self; }; } { for my $name (keys %$default) { next if $name =~ /^(data|config)/; my $value = $default->{$name}; if (defined $value) { $value = 1 - $value if $value =~/^[01]$/; $value = [] if $name eq 'include_path'; } no strict 'refs'; *{__PACKAGE__ . '::' . $name} = field($name, $value); } } { no warnings 'once'; *path = \&include_path; } sub render { my $self = shift; my $template = shift or die "render method requires a template name"; if ($template =~ qr{//}) { my $path; ($path, $template) = split '//', $template, 2; $self->include_path($path); } $self->data(shift(@_)) if @_; $self->output(shift(@_)) if @_; if ($self->{output}) { $self->process($template, $self->{data}, $self->{output}) or $self->croak; return ''; } my $output = ''; $self->process($template, $self->{data}, \$output) or $self->croak; return Encode::encode_utf8($output); } sub usage { return <<'...' Usage: tt-render --path=path/to/templates/ --data=data.yaml foo.tt2 ... } sub croak { my $self = shift; require Carp; my $error = $self->{tt}->error; chomp $error; Carp::croak($error . "\n"); }; sub process { my $self = shift; $self->{tt} = Template->new( ENCODING => $self->{encoding}, INCLUDE_PATH => $self->{include_path}, EVAL_PERL => $self->{eval_perl}, START_TAG => $self->{start_tag}, END_TAG => $self->{end_tag}, PRE_CHOMP => $self->{pre_chomp}, POST_CHOMP => $self->{post_chomp}, TRIM => $self->{trim}, INTERPOLATE => $self->{interpolate}, ANYCASE => $self->{anycase}, DELIMITER => $self->{delimiter}, ABSOLUTE => $self->{absolute}, STRICT => $self->{strict}, DEFAULT => $self->{default}, BLOCKS => $self->{blocks}, AUTO_RESET => $self->{auto_reset}, RECURSION => $self->{recursion}, PRE_PROCESS => $self->{pre_process}, POST_PROCESS => $self->{post_process}, PROCESS_TEMPLATE => $self->{process_template}, ERROR_TEMPLATE => $self->{error_template}, OUTPUT_PATH => $self->{output_path}, DEBUG => ($self->{debug} && DEBUG_ALL ^ DEBUG_CALLER ^ DEBUG_CONTEXT), CACHE_SIZE => $self->{cache_size}, COMPILE_EXT => $self->{compile_ext}, COMPILE_DIR => $self->{compile_dir}, ); return $self->{tt}->process(@_); } sub data { my $self = shift; $self->{data} = $self->_file_to_hash(@_); return $self; } sub config { my $self = shift; $self = { %$self, $self->_file_to_hash(@_) }; return $self; } sub _file_to_hash { my $self = shift; my $file_name = shift; return (ref($file_name) eq 'HASH') ? $file_name : ($file_name =~ /\.(?:yaml|yml)$/i) ? $self->_load_yaml($file_name) : ($file_name =~ /\.json$/i) ? $self->_load_json($file_name) : ($file_name =~ /\.xml$/i) ? $self->_load_xml($file_name) : die "Expected '$file_name' to end with .yaml, .json or .xml"; } sub _load_yaml { my $self = shift; YAML::XS::LoadFile(shift); } sub _load_json { my $self = shift; require JSON::XS; my $json = do { local $/; open my $json, '<', shift; <$json> }; JSON::XS::decode_json($json); } sub _load_xml { my $self = shift; require XML::Simple; XML::Simple::XMLin(shift); } sub _run_command { my $class = shift; my $self = $class->new($default); local @ARGV = @_; my $template = pop or do { print STDERR $self->usage(); return; }; my $setter = sub { my ($name, $value) = @_; my $method = lc($name); $method =~ s/-/_/g; $value = quotemeta($value) if $method =~ /_tag$/; $self->$method($value); }; GetOptions( map { my $option = $_; my $option2 = $option; $option .= "|$option2" if $option2 =~ s/_/-/g; $option .= "|$abbreviations->{$_}" if defined $abbreviations->{$_}; $option .= ((not defined $default->{$_} or $option =~/\-tag$/) ? '=s' : ''); ($option, $setter); } keys %$default ); print STDOUT $self->render($template); } 1; PK W �[ ( lib/auto/Template/Toolkit/Simple/.existsnu �[��� PK d �[ -�.�� �� man3/Storable.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Storable 3" .TH Storable 3 "2021-08-30" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Storable \- persistence for Perl data structures .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use Storable; \& store \e%table, \*(Aqfile\*(Aq; \& $hashref = retrieve(\*(Aqfile\*(Aq); \& \& use Storable qw(nstore store_fd nstore_fd freeze thaw dclone); \& \& # Network order \& nstore \e%table, \*(Aqfile\*(Aq; \& $hashref = retrieve(\*(Aqfile\*(Aq); # There is NO nretrieve() \& \& # Storing to and retrieving from an already opened file \& store_fd \e@array, \e*STDOUT; \& nstore_fd \e%table, \e*STDOUT; \& $aryref = fd_retrieve(\e*SOCKET); \& $hashref = fd_retrieve(\e*SOCKET); \& \& # Serializing to memory \& $serialized = freeze \e%table; \& %table_clone = %{ thaw($serialized) }; \& \& # Deep (recursive) cloning \& $cloneref = dclone($ref); \& \& # Advisory locking \& use Storable qw(lock_store lock_nstore lock_retrieve) \& lock_store \e%table, \*(Aqfile\*(Aq; \& lock_nstore \e%table, \*(Aqfile\*(Aq; \& $hashref = lock_retrieve(\*(Aqfile\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Storable package brings persistence to your Perl data structures containing \s-1SCALAR, ARRAY, HASH\s0 or \s-1REF\s0 objects, i.e. anything that can be conveniently stored to disk and retrieved at a later time. .PP It can be used in the regular procedural way by calling \f(CW\*(C`store\*(C'\fR with a reference to the object to be stored, along with the file name where the image should be written. .PP The routine returns \f(CW\*(C`undef\*(C'\fR for I/O problems or other internal error, a true value otherwise. Serious errors are propagated as a \f(CW\*(C`die\*(C'\fR exception. .PP To retrieve data stored to disk, use \f(CW\*(C`retrieve\*(C'\fR with a file name. The objects stored into that file are recreated into memory for you, and a \fIreference\fR to the root object is returned. In case an I/O error occurs while reading, \f(CW\*(C`undef\*(C'\fR is returned instead. Other serious errors are propagated via \f(CW\*(C`die\*(C'\fR. .PP Since storage is performed recursively, you might want to stuff references to objects that share a lot of common data into a single array or hash table, and then store that object. That way, when you retrieve back the whole thing, the objects will continue to share what they originally shared. .PP At the cost of a slight header overhead, you may store to an already opened file descriptor using the \f(CW\*(C`store_fd\*(C'\fR routine, and retrieve from a file via \f(CW\*(C`fd_retrieve\*(C'\fR. Those names aren't imported by default, so you will have to do that explicitly if you need those routines. The file descriptor you supply must be already opened, for read if you're going to retrieve and for write if you wish to store. .PP .Vb 2 \& store_fd(\e%table, *STDOUT) || die "can\*(Aqt store to stdout\en"; \& $hashref = fd_retrieve(*STDIN); .Ve .PP You can also store data in network order to allow easy sharing across multiple platforms, or when storing on a socket known to be remotely connected. The routines to call have an initial \f(CW\*(C`n\*(C'\fR prefix for \fInetwork\fR, as in \f(CW\*(C`nstore\*(C'\fR and \f(CW\*(C`nstore_fd\*(C'\fR. At retrieval time, your data will be correctly restored so you don't have to know whether you're restoring from native or network ordered data. Double values are stored stringified to ensure portability as well, at the slight risk of loosing some precision in the last decimals. .PP When using \f(CW\*(C`fd_retrieve\*(C'\fR, objects are retrieved in sequence, one object (i.e. one recursive tree) per associated \f(CW\*(C`store_fd\*(C'\fR. .PP If you're more from the object-oriented camp, you can inherit from Storable and directly store your objects by invoking \f(CW\*(C`store\*(C'\fR as a method. The fact that the root of the to-be-stored tree is a blessed reference (i.e. an object) is special-cased so that the retrieve does not provide a reference to that object but rather the blessed object reference itself. (Otherwise, you'd get a reference to that blessed object). .SH "MEMORY STORE" .IX Header "MEMORY STORE" The Storable engine can also store data into a Perl scalar instead, to later retrieve them. This is mainly used to freeze a complex structure in some safe compact memory place (where it can possibly be sent to another process via some \s-1IPC,\s0 since freezing the structure also serializes it in effect). Later on, and maybe somewhere else, you can thaw the Perl scalar out and recreate the original complex structure in memory. .PP Surprisingly, the routines to be called are named \f(CW\*(C`freeze\*(C'\fR and \f(CW\*(C`thaw\*(C'\fR. If you wish to send out the frozen scalar to another machine, use \&\f(CW\*(C`nfreeze\*(C'\fR instead to get a portable image. .PP Note that freezing an object structure and immediately thawing it actually achieves a deep cloning of that structure: .PP .Vb 1 \& dclone(.) = thaw(freeze(.)) .Ve .PP Storable provides you with a \f(CW\*(C`dclone\*(C'\fR interface which does not create that intermediary scalar but instead freezes the structure in some internal memory space and then immediately thaws it out. .SH "ADVISORY LOCKING" .IX Header "ADVISORY LOCKING" The \f(CW\*(C`lock_store\*(C'\fR and \f(CW\*(C`lock_nstore\*(C'\fR routine are equivalent to \&\f(CW\*(C`store\*(C'\fR and \f(CW\*(C`nstore\*(C'\fR, except that they get an exclusive lock on the file before writing. Likewise, \f(CW\*(C`lock_retrieve\*(C'\fR does the same as \f(CW\*(C`retrieve\*(C'\fR, but also gets a shared lock on the file before reading. .PP As with any advisory locking scheme, the protection only works if you systematically use \f(CW\*(C`lock_store\*(C'\fR and \f(CW\*(C`lock_retrieve\*(C'\fR. If one side of your application uses \f(CW\*(C`store\*(C'\fR whilst the other uses \f(CW\*(C`lock_retrieve\*(C'\fR, you will get no protection at all. .PP The internal advisory locking is implemented using Perl's \fBflock()\fR routine. If your system does not support any form of \fBflock()\fR, or if you share your files across \s-1NFS,\s0 you might wish to use other forms of locking by using modules such as LockFile::Simple which lock a file using a filesystem entry, instead of locking the file descriptor. .SH "SPEED" .IX Header "SPEED" The heart of Storable is written in C for decent speed. Extra low-level optimizations have been made when manipulating perl internals, to sacrifice encapsulation for the benefit of greater speed. .SH "CANONICAL REPRESENTATION" .IX Header "CANONICAL REPRESENTATION" Normally, Storable stores elements of hashes in the order they are stored internally by Perl, i.e. pseudo-randomly. If you set \&\f(CW$Storable::canonical\fR to some \f(CW\*(C`TRUE\*(C'\fR value, Storable will store hashes with the elements sorted by their key. This allows you to compare data structures by comparing their frozen representations (or even the compressed frozen representations), which can be useful for creating lookup tables for complicated queries. .PP Canonical order does not imply network order; those are two orthogonal settings. .SH "CODE REFERENCES" .IX Header "CODE REFERENCES" Since Storable version 2.05, \s-1CODE\s0 references may be serialized with the help of B::Deparse. To enable this feature, set \&\f(CW$Storable::Deparse\fR to a true value. To enable deserialization, \&\f(CW$Storable::Eval\fR should be set to a true value. Be aware that deserialization is done through \f(CW\*(C`eval\*(C'\fR, which is dangerous if the Storable file contains malicious data. You can set \f(CW$Storable::Eval\fR to a subroutine reference which would be used instead of \f(CW\*(C`eval\*(C'\fR. See below for an example using a Safe compartment for deserialization of \s-1CODE\s0 references. .PP If \f(CW$Storable::Deparse\fR and/or \f(CW$Storable::Eval\fR are set to false values, then the value of \f(CW$Storable::forgive_me\fR (see below) is respected while serializing and deserializing. .SH "FORWARD COMPATIBILITY" .IX Header "FORWARD COMPATIBILITY" This release of Storable can be used on a newer version of Perl to serialize data which is not supported by earlier Perls. By default, Storable will attempt to do the right thing, by \f(CW\*(C`croak()\*(C'\fRing if it encounters data that it cannot deserialize. However, the defaults can be changed as follows: .IP "utf8 data" 4 .IX Item "utf8 data" Perl 5.6 added support for Unicode characters with code points > 255, and Perl 5.8 has full support for Unicode characters in hash keys. Perl internally encodes strings with these characters using utf8, and Storable serializes them as utf8. By default, if an older version of Perl encounters a utf8 value it cannot represent, it will \f(CW\*(C`croak()\*(C'\fR. To change this behaviour so that Storable deserializes utf8 encoded values as the string of bytes (effectively dropping the \fIis_utf8\fR flag) set \f(CW$Storable::drop_utf8\fR to some \f(CW\*(C`TRUE\*(C'\fR value. This is a form of data loss, because with \f(CW$drop_utf8\fR true, it becomes impossible to tell whether the original data was the Unicode string, or a series of bytes that happen to be valid utf8. .IP "restricted hashes" 4 .IX Item "restricted hashes" Perl 5.8 adds support for restricted hashes, which have keys restricted to a given set, and can have values locked to be read only. By default, when Storable encounters a restricted hash on a perl that doesn't support them, it will deserialize it as a normal hash, silently discarding any placeholder keys and leaving the keys and all values unlocked. To make Storable \f(CW\*(C`croak()\*(C'\fR instead, set \&\f(CW$Storable::downgrade_restricted\fR to a \f(CW\*(C`FALSE\*(C'\fR value. To restore the default set it back to some \f(CW\*(C`TRUE\*(C'\fR value. .Sp The cperl \s-1PERL_PERTURB_KEYS_TOP\s0 hash strategy has a known problem with restricted hashes. .IP "huge objects" 4 .IX Item "huge objects" On 64bit systems some data structures may exceed the 2G (i.e. I32_MAX) limit. On 32bit systems also strings between I32 and U32 (2G\-4G). Since Storable 3.00 (not in perl5 core) we are able to store and retrieve these objects, even if perl5 itself is not able to handle them. These are strings longer then 4G, arrays with more then 2G elements and hashes with more then 2G elements. cperl forbids hashes with more than 2G elements, but this fail in cperl then. perl5 itself at least until 5.26 allows it, but cannot iterate over them. Note that creating those objects might cause out of memory exceptions by the operating system before perl has a chance to abort. .IP "files from future versions of Storable" 4 .IX Item "files from future versions of Storable" Earlier versions of Storable would immediately croak if they encountered a file with a higher internal version number than the reading Storable knew about. Internal version numbers are increased each time new data types (such as restricted hashes) are added to the vocabulary of the file format. This meant that a newer Storable module had no way of writing a file readable by an older Storable, even if the writer didn't store newer data types. .Sp This version of Storable will defer croaking until it encounters a data type in the file that it does not recognize. This means that it will continue to read files generated by newer Storable modules which are careful in what they write out, making it easier to upgrade Storable modules in a mixed environment. .Sp The old behaviour of immediate croaking can be re-instated by setting \&\f(CW$Storable::accept_future_minor\fR to some \f(CW\*(C`FALSE\*(C'\fR value. .PP All these variables have no effect on a newer Perl which supports the relevant feature. .SH "ERROR REPORTING" .IX Header "ERROR REPORTING" Storable uses the \*(L"exception\*(R" paradigm, in that it does not try to workaround failures: if something bad happens, an exception is generated from the caller's perspective (see Carp and \f(CW\*(C`croak()\*(C'\fR). Use eval {} to trap those exceptions. .PP When Storable croaks, it tries to report the error via the \f(CW\*(C`logcroak()\*(C'\fR routine from the \f(CW\*(C`Log::Agent\*(C'\fR package, if it is available. .PP Normal errors are reported by having \fBstore()\fR or \fBretrieve()\fR return \f(CW\*(C`undef\*(C'\fR. Such errors are usually I/O errors (or truncated stream errors at retrieval). .PP When Storable throws the \*(L"Max. recursion depth with nested structures exceeded\*(R" error we are already out of stack space. Unfortunately on some earlier perl versions cleaning up a recursive data structure recurses into the free calls, which will lead to stack overflows in the cleanup. This data structure is not properly cleaned up then, it will only be destroyed during global destruction. .SH "WIZARDS ONLY" .IX Header "WIZARDS ONLY" .SS "Hooks" .IX Subsection "Hooks" Any class may define hooks that will be called during the serialization and deserialization process on objects that are instances of that class. Those hooks can redefine the way serialization is performed (and therefore, how the symmetrical deserialization should be conducted). .PP Since we said earlier: .PP .Vb 1 \& dclone(.) = thaw(freeze(.)) .Ve .PP everything we say about hooks should also hold for deep cloning. However, hooks get to know whether the operation is a mere serialization, or a cloning. .PP Therefore, when serializing hooks are involved, .PP .Vb 1 \& dclone(.) <> thaw(freeze(.)) .Ve .PP Well, you could keep them in sync, but there's no guarantee it will always hold on classes somebody else wrote. Besides, there is little to gain in doing so: a serializing hook could keep only one attribute of an object, which is probably not what should happen during a deep cloning of that same object. .PP Here is the hooking interface: .ie n .IP """STORABLE_freeze"" \fIobj\fR, \fIcloning\fR" 4 .el .IP "\f(CWSTORABLE_freeze\fR \fIobj\fR, \fIcloning\fR" 4 .IX Item "STORABLE_freeze obj, cloning" The serializing hook, called on the object during serialization. It can be inherited, or defined in the class itself, like any other method. .Sp Arguments: \fIobj\fR is the object to serialize, \fIcloning\fR is a flag indicating whether we're in a \fBdclone()\fR or a regular serialization via \fBstore()\fR or \fBfreeze()\fR. .Sp Returned value: A \s-1LIST\s0 \f(CW\*(C`($serialized, $ref1, $ref2, ...)\*(C'\fR where \f(CW$serialized\fR is the serialized form to be used, and the optional \f(CW$ref1\fR, \f(CW$ref2\fR, etc... are extra references that you wish to let the Storable engine serialize. .Sp At deserialization time, you will be given back the same \s-1LIST,\s0 but all the extra references will be pointing into the deserialized structure. .Sp The \fBfirst time\fR the hook is hit in a serialization flow, you may have it return an empty list. That will signal the Storable engine to further discard that hook for this class and to therefore revert to the default serialization of the underlying Perl data. The hook will again be normally processed in the next serialization. .Sp Unless you know better, serializing hook should always say: .Sp .Vb 5 \& sub STORABLE_freeze { \& my ($self, $cloning) = @_; \& return if $cloning; # Regular default serialization \& .... \& } .Ve .Sp in order to keep reasonable \fBdclone()\fR semantics. .ie n .IP """STORABLE_thaw"" \fIobj\fR, \fIcloning\fR, \fIserialized\fR, ..." 4 .el .IP "\f(CWSTORABLE_thaw\fR \fIobj\fR, \fIcloning\fR, \fIserialized\fR, ..." 4 .IX Item "STORABLE_thaw obj, cloning, serialized, ..." The deserializing hook called on the object during deserialization. But wait: if we're deserializing, there's no object yet... right? .Sp Wrong: the Storable engine creates an empty one for you. If you know Eiffel, you can view \f(CW\*(C`STORABLE_thaw\*(C'\fR as an alternate creation routine. .Sp This means the hook can be inherited like any other method, and that \&\fIobj\fR is your blessed reference for this particular instance. .Sp The other arguments should look familiar if you know \f(CW\*(C`STORABLE_freeze\*(C'\fR: \&\fIcloning\fR is true when we're part of a deep clone operation, \fIserialized\fR is the serialized string you returned to the engine in \f(CW\*(C`STORABLE_freeze\*(C'\fR, and there may be an optional list of references, in the same order you gave them at serialization time, pointing to the deserialized objects (which have been processed courtesy of the Storable engine). .Sp When the Storable engine does not find any \f(CW\*(C`STORABLE_thaw\*(C'\fR hook routine, it tries to load the class by requiring the package dynamically (using the blessed package name), and then re-attempts the lookup. If at that time the hook cannot be located, the engine croaks. Note that this mechanism will fail if you define several classes in the same file, but perlmod warned you. .Sp It is up to you to use this information to populate \fIobj\fR the way you want. .Sp Returned value: none. .ie n .IP """STORABLE_attach"" \fIclass\fR, \fIcloning\fR, \fIserialized\fR" 4 .el .IP "\f(CWSTORABLE_attach\fR \fIclass\fR, \fIcloning\fR, \fIserialized\fR" 4 .IX Item "STORABLE_attach class, cloning, serialized" While \f(CW\*(C`STORABLE_freeze\*(C'\fR and \f(CW\*(C`STORABLE_thaw\*(C'\fR are useful for classes where each instance is independent, this mechanism has difficulty (or is incompatible) with objects that exist as common process-level or system-level resources, such as singleton objects, database pools, caches or memoized objects. .Sp The alternative \f(CW\*(C`STORABLE_attach\*(C'\fR method provides a solution for these shared objects. Instead of \f(CW\*(C`STORABLE_freeze\*(C'\fR \-\-> \f(CW\*(C`STORABLE_thaw\*(C'\fR, you implement \f(CW\*(C`STORABLE_freeze\*(C'\fR \-\-> \f(CW\*(C`STORABLE_attach\*(C'\fR instead. .Sp Arguments: \fIclass\fR is the class we are attaching to, \fIcloning\fR is a flag indicating whether we're in a \fBdclone()\fR or a regular de-serialization via \&\fBthaw()\fR, and \fIserialized\fR is the stored string for the resource object. .Sp Because these resource objects are considered to be owned by the entire process/system, and not the \*(L"property\*(R" of whatever is being serialized, no references underneath the object should be included in the serialized string. Thus, in any class that implements \f(CW\*(C`STORABLE_attach\*(C'\fR, the \&\f(CW\*(C`STORABLE_freeze\*(C'\fR method cannot return any references, and \f(CW\*(C`Storable\*(C'\fR will throw an error if \f(CW\*(C`STORABLE_freeze\*(C'\fR tries to return references. .Sp All information required to \*(L"attach\*(R" back to the shared resource object \&\fBmust\fR be contained \fBonly\fR in the \f(CW\*(C`STORABLE_freeze\*(C'\fR return string. Otherwise, \f(CW\*(C`STORABLE_freeze\*(C'\fR behaves as normal for \f(CW\*(C`STORABLE_attach\*(C'\fR classes. .Sp Because \f(CW\*(C`STORABLE_attach\*(C'\fR is passed the class (rather than an object), it also returns the object directly, rather than modifying the passed object. .Sp Returned value: object of type \f(CW\*(C`class\*(C'\fR .SS "Predicates" .IX Subsection "Predicates" Predicates are not exportable. They must be called by explicitly prefixing them with the Storable package name. .ie n .IP """Storable::last_op_in_netorder""" 4 .el .IP "\f(CWStorable::last_op_in_netorder\fR" 4 .IX Item "Storable::last_op_in_netorder" The \f(CW\*(C`Storable::last_op_in_netorder()\*(C'\fR predicate will tell you whether network order was used in the last store or retrieve operation. If you don't know how to use this, just forget about it. .ie n .IP """Storable::is_storing""" 4 .el .IP "\f(CWStorable::is_storing\fR" 4 .IX Item "Storable::is_storing" Returns true if within a store operation (via STORABLE_freeze hook). .ie n .IP """Storable::is_retrieving""" 4 .el .IP "\f(CWStorable::is_retrieving\fR" 4 .IX Item "Storable::is_retrieving" Returns true if within a retrieve operation (via STORABLE_thaw hook). .SS "Recursion" .IX Subsection "Recursion" With hooks comes the ability to recurse back to the Storable engine. Indeed, hooks are regular Perl code, and Storable is convenient when it comes to serializing and deserializing things, so why not use it to handle the serialization string? .PP There are a few things you need to know, however: .IP "\(bu" 4 From Storable 3.05 to 3.13 we probed for the stack recursion limit for references, arrays and hashes to a maximal depth of ~1200\-35000, otherwise we might fall into a stack-overflow. On \s-1JSON::XS\s0 this limit is 512 btw. With references not immediately referencing each other there's no such limit yet, so you might fall into such a stack-overflow segfault. .Sp This probing and the checks we performed have some limitations: .RS 4 .IP "\(bu" 4 the stack size at build time might be different at run time, eg. the stack size may have been modified with \fBulimit\fR\|(1). If it's larger at run time Storable may fail the \fBfreeze()\fR or \fBthaw()\fR unnecessarily. If it's larger at build time Storable may segmentation fault when processing a deep structure at run time. .IP "\(bu" 4 the stack size might be different in a thread. .IP "\(bu" 4 array and hash recursion limits are checked separately against the same recursion depth, a frozen structure with a large sequence of nested arrays within many nested hashes may exhaust the processor stack without triggering Storable's recursion protection. .RE .RS 4 .Sp So these now have simple defaults rather than probing at build-time. .Sp You can control the maximum array and hash recursion depths by modifying \f(CW$Storable::recursion_limit\fR and \&\f(CW$Storable::recursion_limit_hash\fR respectively. Either can be set to \&\f(CW\*(C`\-1\*(C'\fR to prevent any depth checks, though this isn't recommended. .Sp If you want to test what the limits are, the \fIstacksize\fR tool is included in the \f(CW\*(C`Storable\*(C'\fR distribution. .RE .IP "\(bu" 4 You can create endless loops if the things you serialize via \fBfreeze()\fR (for instance) point back to the object we're trying to serialize in the hook. .IP "\(bu" 4 Shared references among objects will not stay shared: if we're serializing the list of object [A, C] where both object A and C refer to the \s-1SAME\s0 object B, and if there is a serializing hook in A that says freeze(B), then when deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D, a deep clone of B'. The topology was not preserved. .IP "\(bu" 4 The maximal stack recursion limit for your system is returned by \&\f(CW\*(C`stack_depth()\*(C'\fR and \f(CW\*(C`stack_depth_hash()\*(C'\fR. The hash limit is usually half the size of the array and ref limit, as the Perl hash \s-1API\s0 is not optimal. .PP That's why \f(CW\*(C`STORABLE_freeze\*(C'\fR lets you provide a list of references to serialize. The engine guarantees that those will be serialized in the same context as the other objects, and therefore that shared objects will stay shared. .PP In the above [A, C] example, the \f(CW\*(C`STORABLE_freeze\*(C'\fR hook could return: .PP .Vb 1 \& ("something", $self\->{B}) .Ve .PP and the B part would be serialized by the engine. In \f(CW\*(C`STORABLE_thaw\*(C'\fR, you would get back the reference to the B' object, deserialized for you. .PP Therefore, recursion should normally be avoided, but is nonetheless supported. .SS "Deep Cloning" .IX Subsection "Deep Cloning" There is a Clone module available on \s-1CPAN\s0 which implements deep cloning natively, i.e. without freezing to memory and thawing the result. It is aimed to replace Storable's \fBdclone()\fR some day. However, it does not currently support Storable hooks to redefine the way deep cloning is performed. .SH "Storable magic" .IX Header "Storable magic" Yes, there's a lot of that :\-) But more precisely, in \s-1UNIX\s0 systems there's a utility called \f(CW\*(C`file\*(C'\fR, which recognizes data files based on their contents (usually their first few bytes). For this to work, a certain file called \fImagic\fR needs to taught about the \fIsignature\fR of the data. Where that configuration file lives depends on the \s-1UNIX\s0 flavour; often it's something like \fI/usr/share/misc/magic\fR or \&\fI/etc/magic\fR. Your system administrator needs to do the updating of the \fImagic\fR file. The necessary signature information is output to \&\s-1STDOUT\s0 by invoking \fBStorable::show_file_magic()\fR. Note that the \s-1GNU\s0 implementation of the \f(CW\*(C`file\*(C'\fR utility, version 3.38 or later, is expected to contain support for recognising Storable files out-of-the-box, in addition to other kinds of Perl files. .PP You can also use the following functions to extract the file header information from Storable images: .ie n .IP "$info = Storable::file_magic( $filename )" 4 .el .IP "\f(CW$info\fR = Storable::file_magic( \f(CW$filename\fR )" 4 .IX Item "$info = Storable::file_magic( $filename )" If the given file is a Storable image return a hash describing it. If the file is readable, but not a Storable image return \f(CW\*(C`undef\*(C'\fR. If the file does not exist or is unreadable then croak. .Sp The hash returned has the following elements: .RS 4 .ie n .IP """version""" 4 .el .IP "\f(CWversion\fR" 4 .IX Item "version" This returns the file format version. It is a string like \*(L"2.7\*(R". .Sp Note that this version number is not the same as the version number of the Storable module itself. For instance Storable v0.7 create files in format v2.0 and Storable v2.15 create files in format v2.7. The file format version number only increment when additional features that would confuse older versions of the module are added. .Sp Files older than v2.0 will have the one of the version numbers \*(L"\-1\*(R", \&\*(L"0\*(R" or \*(L"1\*(R". No minor number was used at that time. .ie n .IP """version_nv""" 4 .el .IP "\f(CWversion_nv\fR" 4 .IX Item "version_nv" This returns the file format version as number. It is a string like \&\*(L"2.007\*(R". This value is suitable for numeric comparisons. .Sp The constant function \f(CW\*(C`Storable::BIN_VERSION_NV\*(C'\fR returns a comparable number that represents the highest file version number that this version of Storable fully supports (but see discussion of \&\f(CW$Storable::accept_future_minor\fR above). The constant \&\f(CW\*(C`Storable::BIN_WRITE_VERSION_NV\*(C'\fR function returns what file version is written and might be less than \f(CW\*(C`Storable::BIN_VERSION_NV\*(C'\fR in some configurations. .ie n .IP """major"", ""minor""" 4 .el .IP "\f(CWmajor\fR, \f(CWminor\fR" 4 .IX Item "major, minor" This also returns the file format version. If the version is \*(L"2.7\*(R" then major would be 2 and minor would be 7. The minor element is missing for when major is less than 2. .ie n .IP """hdrsize""" 4 .el .IP "\f(CWhdrsize\fR" 4 .IX Item "hdrsize" The is the number of bytes that the Storable header occupies. .ie n .IP """netorder""" 4 .el .IP "\f(CWnetorder\fR" 4 .IX Item "netorder" This is \s-1TRUE\s0 if the image store data in network order. This means that it was created with \fBnstore()\fR or similar. .ie n .IP """byteorder""" 4 .el .IP "\f(CWbyteorder\fR" 4 .IX Item "byteorder" This is only present when \f(CW\*(C`netorder\*(C'\fR is \s-1FALSE.\s0 It is the \&\f(CW$Config\fR{byteorder} string of the perl that created this image. It is a string like \*(L"1234\*(R" (32 bit little endian) or \*(L"87654321\*(R" (64 bit big endian). This must match the current perl for the image to be readable by Storable. .ie n .IP """intsize"", ""longsize"", ""ptrsize"", ""nvsize""" 4 .el .IP "\f(CWintsize\fR, \f(CWlongsize\fR, \f(CWptrsize\fR, \f(CWnvsize\fR" 4 .IX Item "intsize, longsize, ptrsize, nvsize" These are only present when \f(CW\*(C`netorder\*(C'\fR is \s-1FALSE.\s0 These are the sizes of various C datatypes of the perl that created this image. These must match the current perl for the image to be readable by Storable. .Sp The \f(CW\*(C`nvsize\*(C'\fR element is only present for file format v2.2 and higher. .ie n .IP """file""" 4 .el .IP "\f(CWfile\fR" 4 .IX Item "file" The name of the file. .RE .RS 4 .RE .ie n .IP "$info = Storable::read_magic( $buffer )" 4 .el .IP "\f(CW$info\fR = Storable::read_magic( \f(CW$buffer\fR )" 4 .IX Item "$info = Storable::read_magic( $buffer )" .PD 0 .ie n .IP "$info = Storable::read_magic( $buffer, $must_be_file )" 4 .el .IP "\f(CW$info\fR = Storable::read_magic( \f(CW$buffer\fR, \f(CW$must_be_file\fR )" 4 .IX Item "$info = Storable::read_magic( $buffer, $must_be_file )" .PD The \f(CW$buffer\fR should be a Storable image or the first few bytes of it. If \f(CW$buffer\fR starts with a Storable header, then a hash describing the image is returned, otherwise \f(CW\*(C`undef\*(C'\fR is returned. .Sp The hash has the same structure as the one returned by \&\fBStorable::file_magic()\fR. The \f(CW\*(C`file\*(C'\fR element is true if the image is a file image. .Sp If the \f(CW$must_be_file\fR argument is provided and is \s-1TRUE,\s0 then return \&\f(CW\*(C`undef\*(C'\fR unless the image looks like it belongs to a file dump. .Sp The maximum size of a Storable header is currently 21 bytes. If the provided \f(CW$buffer\fR is only the first part of a Storable image it should at least be this long to ensure that \fBread_magic()\fR will recognize it as such. .SH "EXAMPLES" .IX Header "EXAMPLES" Here are some code samples showing a possible usage of Storable: .PP .Vb 1 \& use Storable qw(store retrieve freeze thaw dclone); \& \& %color = (\*(AqBlue\*(Aq => 0.1, \*(AqRed\*(Aq => 0.8, \*(AqBlack\*(Aq => 0, \*(AqWhite\*(Aq => 1); \& \& store(\e%color, \*(Aqmycolors\*(Aq) or die "Can\*(Aqt store %a in mycolors!\en"; \& \& $colref = retrieve(\*(Aqmycolors\*(Aq); \& die "Unable to retrieve from mycolors!\en" unless defined $colref; \& printf "Blue is still %lf\en", $colref\->{\*(AqBlue\*(Aq}; \& \& $colref2 = dclone(\e%color); \& \& $str = freeze(\e%color); \& printf "Serialization of %%color is %d bytes long.\en", length($str); \& $colref3 = thaw($str); .Ve .PP which prints (on my machine): .PP .Vb 2 \& Blue is still 0.100000 \& Serialization of %color is 102 bytes long. .Ve .PP Serialization of \s-1CODE\s0 references and deserialization in a safe compartment: .PP .Vb 11 \& use Storable qw(freeze thaw); \& use Safe; \& use strict; \& my $safe = new Safe; \& # because of opcodes used in "use strict": \& $safe\->permit(qw(:default require)); \& local $Storable::Deparse = 1; \& local $Storable::Eval = sub { $safe\->reval($_[0]) }; \& my $serialized = freeze(sub { 42 }); \& my $code = thaw($serialized); \& $code\->() == 42; .Ve .SH "SECURITY WARNING" .IX Header "SECURITY WARNING" \&\fBDo not accept Storable documents from untrusted sources!\fR .PP Some features of Storable can lead to security vulnerabilities if you accept Storable documents from untrusted sources with the default flags. Most obviously, the optional (off by default) \s-1CODE\s0 reference serialization feature allows transfer of code to the deserializing process. Furthermore, any serialized object will cause Storable to helpfully load the module corresponding to the class of the object in the deserializing module. For manipulated module names, this can load almost arbitrary code. Finally, the deserialized object's destructors will be invoked when the objects get destroyed in the deserializing process. Maliciously crafted Storable documents may put such objects in the value of a hash key that is overridden by another key/value pair in the same hash, thus causing immediate destructor execution. .PP To disable blessing objects while thawing/retrieving remove the flag \&\f(CW\*(C`BLESS_OK\*(C'\fR = 2 from \f(CW$Storable::flags\fR or set the 2nd argument for thaw/retrieve to 0. .PP To disable tieing data while thawing/retrieving remove the flag \f(CW\*(C`TIE_OK\*(C'\fR = 4 from \f(CW$Storable::flags\fR or set the 2nd argument for thaw/retrieve to 0. .PP With the default setting of \f(CW$Storable::flags\fR = 6, creating or destroying random objects, even renamed objects can be controlled by an attacker. See \s-1CVE\-2015\-1592\s0 and its metasploit module. .PP If your application requires accepting data from untrusted sources, you are best off with a less powerful and more-likely safe serialization format and implementation. If your data is sufficiently simple, Cpanel::JSON::XS, Data::MessagePack or Sereal are the best choices and offer maximum interoperability, but note that Sereal is unsafe by default. .SH "WARNING" .IX Header "WARNING" If you're using references as keys within your hash tables, you're bound to be disappointed when retrieving your data. Indeed, Perl stringifies references used as hash table keys. If you later wish to access the items via another reference stringification (i.e. using the same reference that was used for the key originally to record the value into the hash table), it will work because both references stringify to the same string. .PP It won't work across a sequence of \f(CW\*(C`store\*(C'\fR and \f(CW\*(C`retrieve\*(C'\fR operations, however, because the addresses in the retrieved objects, which are part of the stringified references, will probably differ from the original addresses. The topology of your structure is preserved, but not hidden semantics like those. .PP On platforms where it matters, be sure to call \f(CW\*(C`binmode()\*(C'\fR on the descriptors that you pass to Storable functions. .PP Storing data canonically that contains large hashes can be significantly slower than storing the same data normally, as temporary arrays to hold the keys for each hash have to be allocated, populated, sorted and freed. Some tests have shown a halving of the speed of storing \*(-- the exact penalty will depend on the complexity of your data. There is no slowdown on retrieval. .SH "REGULAR EXPRESSIONS" .IX Header "REGULAR EXPRESSIONS" Storable now has experimental support for storing regular expressions, but there are significant limitations: .IP "\(bu" 4 perl 5.8 or later is required. .IP "\(bu" 4 regular expressions with code blocks, ie \f(CW\*(C`/(?{ ... })/\*(C'\fR or \f(CW\*(C`/(??{ \&... })/\*(C'\fR will throw an exception when thawed. .IP "\(bu" 4 regular expression syntax and flags have changed over the history of perl, so a regular expression that you freeze in one version of perl may fail to thaw or behave differently in another version of perl. .IP "\(bu" 4 depending on the version of perl, regular expressions can change in behaviour depending on the context, but later perls will bake that behaviour into the regexp. .PP Storable will throw an exception if a frozen regular expression cannot be thawed. .SH "BUGS" .IX Header "BUGS" You can't store \s-1GLOB, FORMLINE,\s0 etc.... If you can define semantics for those operations, feel free to enhance Storable so that it can deal with them. .PP The store functions will \f(CW\*(C`croak\*(C'\fR if they run into such references unless you set \f(CW$Storable::forgive_me\fR to some \f(CW\*(C`TRUE\*(C'\fR value. In that case, the fatal message is converted to a warning and some meaningless string is stored instead. .PP Setting \f(CW$Storable::canonical\fR may not yield frozen strings that compare equal due to possible stringification of numbers. When the string version of a scalar exists, it is the form stored; therefore, if you happen to use your numbers as strings between two freezing operations on the same data structures, you will get different results. .PP When storing doubles in network order, their value is stored as text. However, you should also not expect non-numeric floating-point values such as infinity and \*(L"not a number\*(R" to pass successfully through a \&\fBnstore()\fR/\fBretrieve()\fR pair. .PP As Storable neither knows nor cares about character sets (although it does know that characters may be more than eight bits wide), any difference in the interpretation of character codes between a host and a target system is your problem. In particular, if host and target use different code points to represent the characters used in the text representation of floating-point numbers, you will not be able be able to exchange floating-point data, even with \fBnstore()\fR. .PP \&\f(CW\*(C`Storable::drop_utf8\*(C'\fR is a blunt tool. There is no facility either to return \fBall\fR strings as utf8 sequences, or to attempt to convert utf8 data back to 8 bit and \f(CW\*(C`croak()\*(C'\fR if the conversion fails. .PP Prior to Storable 2.01, no distinction was made between signed and unsigned integers on storing. By default Storable prefers to store a scalars string representation (if it has one) so this would only cause problems when storing large unsigned integers that had never been converted to string or floating point. In other words values that had been generated by integer operations such as logic ops and then not used in any string or arithmetic context before storing. .SS "64 bit data in perl 5.6.0 and 5.6.1" .IX Subsection "64 bit data in perl 5.6.0 and 5.6.1" This section only applies to you if you have existing data written out by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which has been configured with 64 bit integer support (not the default) If you got a precompiled perl, rather than running Configure to build your own perl from source, then it almost certainly does not affect you, and you can stop reading now (unless you're curious). If you're using perl on Windows it does not affect you. .PP Storable writes a file header which contains the sizes of various C language types for the C compiler that built Storable (when not writing in network order), and will refuse to load files written by a Storable not on the same (or compatible) architecture. This check and a check on machine byteorder is needed because the size of various fields in the file are given by the sizes of the C language types, and so files written on different architectures are incompatible. This is done for increased speed. (When writing in network order, all fields are written out as standard lengths, which allows full interworking, but takes longer to read and write) .PP Perl 5.6.x introduced the ability to optional configure the perl interpreter to use C's \f(CW\*(C`long long\*(C'\fR type to allow scalars to store 64 bit integers on 32 bit systems. However, due to the way the Perl configuration system generated the C configuration files on non-Windows platforms, and the way Storable generates its header, nothing in the Storable file header reflected whether the perl writing was using 32 or 64 bit integers, despite the fact that Storable was storing some data differently in the file. Hence Storable running on perl with 64 bit integers will read the header from a file written by a 32 bit perl, not realise that the data is actually in a subtly incompatible format, and then go horribly wrong (possibly crashing) if it encountered a stored integer. This is a design failure. .PP Storable has now been changed to write out and read in a file header with information about the size of integers. It's impossible to detect whether an old file being read in was written with 32 or 64 bit integers (they have the same header) so it's impossible to automatically switch to a correct backwards compatibility mode. Hence this Storable defaults to the new, correct behaviour. .PP What this means is that if you have data written by Storable 1.x running on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux then by default this Storable will refuse to read it, giving the error \&\fIByte order is not compatible\fR. If you have such data then you should set \f(CW$Storable::interwork_56_64bit\fR to a true value to make this Storable read and write files with the old header. You should also migrate your data, or any older perl you are communicating with, to this current version of Storable. .PP If you don't have data written with specific configuration of perl described above, then you do not and should not do anything. Don't set the flag \- not only will Storable on an identically configured perl refuse to load them, but Storable a differently configured perl will load them believing them to be correct for it, and then may well fail or crash part way through reading them. .SH "CREDITS" .IX Header "CREDITS" Thank you to (in chronological order): .PP .Vb 10 \& Jarkko Hietaniemi <jhi@iki.fi> \& Ulrich Pfeifer <pfeifer@charly.informatik.uni\-dortmund.de> \& Benjamin A. Holzman <bholzman@earthlink.net> \& Andrew Ford <A.Ford@ford\-mason.co.uk> \& Gisle Aas <gisle@aas.no> \& Jeff Gresham <gresham_jeffrey@jpmorgan.com> \& Murray Nesbitt <murray@activestate.com> \& Marc Lehmann <pcg@opengroup.org> \& Justin Banks <justinb@wamnet.com> \& Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!) \& Salvador Ortiz Garcia <sog@msg.com.mx> \& Dominic Dunlop <domo@computer.org> \& Erik Haugan <erik@solbors.no> \& Benjamin A. Holzman <ben.holzman@grantstreet.com> \& Reini Urban <rurban@cpan.org> \& Todd Rinaldo <toddr@cpanel.net> \& Aaron Crane <arc@cpan.org> .Ve .PP for their bug reports, suggestions and contributions. .PP Benjamin Holzman contributed the tied variable support, Andrew Ford contributed the canonical order for hashes, and Gisle Aas fixed a few misunderstandings of mine regarding the perl internals, and optimized the emission of \*(L"tags\*(R" in the output streams by simply counting the objects instead of tagging them (leading to a binary incompatibility for the Storable image starting at version 0.6\-\-older images are, of course, still properly understood). Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading and references to tied items support. Benjamin Holzman added a performance improvement for overloaded classes; thanks to Grant Street Group for footing the bill. Reini Urban took over maintenance from p5p, and added security fixes and huge object support. .SH "AUTHOR" .IX Header "AUTHOR" Storable was written by Raphael Manfredi \&\fI<Raphael_Manfredi@pobox.com>\fR Maintenance is now done by cperl <http://perl11.org/cperl> .PP Please e\-mail us with problems, bug fixes, comments and complaints, although if you have compliments you should send them to Raphael. Please don't e\-mail Raphael with problems, as he no longer works on Storable, and your message will be delayed while he forwards it to us. .SH "SEE ALSO" .IX Header "SEE ALSO" Clone. PK d �[ arch/auto/Storable/.existsnu �[��� PK d �[�{� - - arch/auto/Storable/Storable.sonu ȯ�� ELF > p< @ `# @ 8 @ ' & h& h& 0 0 0 �: �: p p p P( P( � � � P X �� �� �� � � � � � � � � $ $ S�td � � � P�td �~ �~ �~ � � Q�td R�td � � � GNU � GNU ���Y��r0JT�o?��j�t h h ���p 9 � r z � ] � � � � ^ � k = � � } _ � � � � � / � f � � � { | { � � � � o v � � � � � ( f . � e � U Z � - � l � I n � � H � � � ) � a � < � * S G 9 � � � , X � � E � F " � � Q E � : �V __gmon_start__ _ITM_deregisterTMCloneTable _ITM_registerTMCloneTable __cxa_finalize Perl_hv_iterinit Perl_hv_iternext_flags Perl_ptr_table_free Perl_hv_undef_flags Perl_sv_free Perl_av_undef Perl_sv_free2 Perl_hv_common_key_len Perl_croak_nocontext PerlIO_putc Perl_sv_2iv_flags Perl_sv_2pv_flags Perl_PerlIO_write Perl_mg_find Perl_safesysrealloc Perl_sv_2uv_flags memcpy Perl_sv_2nv_flags __stack_chk_fail Perl_sv_reftype Perl_get_cv Perl_push_scope Perl_savetmps Perl_newRV Perl_sv_2mortal Perl_call_sv Perl_pop_scope Perl_free_tmps Perl_stack_grow Perl_markstack_grow Perl_warn_nocontext __sprintf_chk strlen Perl_get_sv Perl_sv_2bool_flags Perl_mg_get Perl_newSVnv Perl_newSVpvn Perl_load_module_nocontext Perl_newSVpvn_flags Perl_call_method Perl_newSV Perl_newRV_noinc Perl_sv_magicext Perl_sv_setiv Perl_gv_fetchmethod_autoload Perl_newSVsv_flags Perl_newSViv Perl_ptr_table_fetch Perl_ptr_table_store Perl_Gv_AMupdate Perl_av_len Perl_av_fetch Perl_hv_iterval Perl_hv_riter_set Perl_hv_eiter_set Perl_newSV_type Perl_av_extend Perl_hv_iterkeysv Perl_av_store Perl_sv_cmp Perl_sortsv Perl_hv_placeholders_get Perl_av_shift Perl_hv_common Perl_bytes_from_utf8_loc Perl_safesysfree Perl_ptr_table_new Perl_newSVpv Perl_safesysmalloc Perl_gv_stashpv Perl_sv_bless PL_sv_placeholder Perl_PerlIO_read Perl_sv_setpv_bufsize Perl_warn Perl_sv_magic PerlIO_getc Perl_sv_catpv Perl_eval_sv Perl_call_pv __memcpy_chk Perl_gv_stashpvn Perl_sv_upgrade Perl_sv_rvweaken Perl_av_fill Perl_hv_ksplit Perl_croak_xs_usage Perl_sv_2io Perl_sv_newmortal Perl_sv_setiv_mg Perl_sv_derived_from Perl_av_pop boot_Storable Perl_xs_handshake Perl_newXS_flags Perl_newCONSTSUB Perl_gv_fetchpv Perl_xs_boot_epilog Perl_sv_tainted libperl.so.5.32 libc.so.6 GLIBC_2.14 GLIBC_2.3.4 GLIBC_2.4 GLIBC_2.2.5 � ��� � ti � ii � ui � � p= �� 0= � � � � (� �? 0� � 8� Д @� � H� � P� �i X� �\ `� �d �� @� �� 0 �� �1 �� @ �� � �� �� �� � �� p� ȸ �� и � ظ 0 � � � �� �� �� � �� � �� � �� � �� � �� (� �� 0� �� 8� �� @� �� H� �� P� �� X� �� `� �� h� �� p� �� x� �� �� �� �� �� �� �� �� @� �� $ �� �& �� @ ȹ � й �� ع � � p� � �� � � �� 0 � � � �� � � � `� (� � 0� ` 8� �Q @� @ H� @ P� � X� p� `� �� h� �* p� � x� �� � �� ! �� p" �� �� �� �� �� �Q �� �� � @9 п ؿ � + � @ � [ �� b �� ȼ м ؼ � � � �� � � � � � (� 0� 8� @� H� P� X� `� h� p� x� �� �� �� �� �� �� �� ! �� " �� # Ƚ $ н % ؽ & � ' � ( � ) �� * � , � - � . � / � 0 (� 1 0� 2 8� 3 @� 4 H� 5 P� 6 X� 7 `� 8 h� 9 p� : x� ; �� < �� = �� > �� ? �� A �� B �� C �� D �� E Ⱦ F о G ؾ H � I � J � K �� L � M � N � O � P � Q (� R 0� S 8� T @� U H� V P� W X� X `� Y h� Z p� \ x� ] �� ^ �� _ �� ` �� a �� b �� c �� d �� e �� f ȿ g � �H��H�я H��t��H��� �5�� �%�� � �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h! ������� �h" ������ �h# ������ �h$ ������ �h% ������ �h& ������ �h' ��q����� �h( ��a����� �h) ��Q����� �h* ��A����� �h+ ��1����� �h, ��!����� �h- ������� �h. ������� �h/ ����� �h0 ������ �h1 ������� �h2 ������ �h3 ������ �h4 ������ �h5 ������ �h6 ������ �h7 ��q����� �h8 ��a����� �h9 ��Q����� �h: ��A����� �h; ��1����� �h< ��!����� �h= ������� �h> ������� �h? ����� �h@ ������ �hA ������� �hB ������ �hC ������ �hD ������ �hE ������ �hF ������ �hG ��q����� �hH ��a����� �hI ��Q����� �hJ ��A����� �hK ��1����� �hL ��!����� �hM ������� �hN ������� �hO ����� �hP ������ �hQ ������� �hR ������ �hS ������ �hT ������ �hU ������ �hV ������ �hW ��q����� �hX ��a����� �hY ��Q����� �hZ ��A����� �h[ ��1����� �h\ ��!����� �h] ������� �h^ ������� �h_ ����� �h` ������ �ha ������� ��%e� D � ��%]� D � ��%U� D � ��%M� D � ��%E� D � ��%=� D � ��%5� D � ��%-� D � ��%%� D � ��% � D � ��%� D � ��% � D � ��%� D � ��%�� D � ��%�� D � ��%� D � ��%� D � ��%݅ D � ��%Յ D � ��%ͅ D � ��%Ņ D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%}� D � ��%u� D � ��%m� D � ��%e� D � ��%]� D � ��%U� D � ��%M� D � ��%E� D � ��%=� D � ��%5� D � ��%-� D � ��%%� D � ��% � D � ��%� D � ��% � D � ��%� D � ��%�� D � ��%�� D � ��%� D � ��%� D � ��%݄ D � ��%Մ D � ��%̈́ D � ��%ń D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%}� D � ��%u� D � ��%m� D � ��%e� D � ��%]� D � ��%U� D � ��%M� D � ��%E� D � ��%=� D � ��%5� D � ��%-� D � ��%%� D � ��% � D � ��%� D � ��% � D � ��%� D � ��%�� D � ��%�� D � ��%� D � ��%� D � ��%݃ D � ��%Ճ D � ��%̓ D � ��%Ń D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%�� D � ��%}� D � ��%u� D � ��%m� D � ��%e� D � ��%]� D H�%� �%x �%X �% �% H�%� �%x f. � �H�=y� H�r� H9�tH��� H��t �� � � � H�=I� H�5B� H)�H��H��?H��H�H�tH�Ղ H��t��f D � � � ��=� u+UH�=�� H��t H�=�z ����d����݂ ]� � � � ��w��� � ATUH��SH��H�v0H��� �D���L��P � L�`H�s01�H�����H��u�H�sH��tH�C H�����L�c0M��t H�C0 L��H��1����L��H���_���L�c@M��t H�C@ L��H��1����L��H���6���L�cM��t H�C L��H������L��H������H�shH�C`����H��t�V��vX���V�c�H�Ch �Cp����� �Cx Hǃ Hǃ []A\� D H�sH��� ����?���H������� @ AWE1�AVA��AUM��A� ATI��UH��SH��H��L�~0j L������^_H��t �� A�U H��[]A\A]A^A_� H�CPH��D��L��j A�$ L��H��L�HL�KP���ZYH��t�SP1���Cx H�=�0 �.���ff. � � �AWAVI��AUATI��USH��H��X�j dH�%( H�D$H1��� � ubI��P H��� L9��# � H���� ��E1��A��A��H�D$HdH+%( �v H��XD��[]A\A]A^A_� D ��% = �^ �� �� �� � ��% = �� � L��L��� ���H�D$0A����� H�D$0H��� H��� �s H��� �h�H���P � �&�������� H��� @��H������L��� L;�� �� I�D$E1�H��� A�,$��� D �� p �� @ ��% = � I�$M�l$H�@H�D$(�� � �x H��� L�d$(�� L�d$8�� I��� �. H���= � �[�������� �� D H��8 H9��� H��h H9��`���H��� � H��� ���H��� H;�� �� H�EE1�H��� �E ���� � � H������H��� H;�� �^ H�EE1�H��� �E ���� � H�T$(� L��L�����A�l$ I������f D �� �������� �� �� ��� �R % = �� I�$�@(D�kX�D$@E���� H��� H���� � ��������� H��� H���� H�T$@� L���9���H������r D I��� �� H���� � ������tHH��� H���� D��������t+H�|$8 tQH��� H��� L��L��L�����I9�t.A������m���H��� H;�� �� H�EH��� �E E1��B��� D �V L���S���H��H���� L�xI������� H��� I��� � D�|$$H���� � ��������f����{XH��� ��� �D$$H�T$8ȉD$8H���� � L�����H���%���H��� HcL$$H���� H�U(L�����HcT$$H9������A�l$ ��� � I������� D�d$ H���� � �������������KXH��� ��� H���3 H��� H�EH9�� �Q �D$ �E H��� �# I������� H���� �! �������D���H��� H���� � �������!����SXH��� ���� H�D$8��H�� �ȉT$DH�T$@�D$@H���U � L�����H������H��� H�L$8H���9 L��L���n���H9D$8�������f D % = �l��� � I�$H�@ �g��� D�kXE���� E���J � �H�H�� �A H��� ȉD$8H���b � �������$���H��� H��� H�T$8� L����H���&�����f D H��� � H���>���H��� H;�� �� H�EE1�H��� �E �%��� � D�d$ H��� � �����������CXH��� ���� H���l H�T$ � L����H���M���H��� HcL$ H���s L��L�����HcT$ H9��M������� D H���G �! �]��������H��� H���� � �:������������ @ H��� H;�� �� H�EH��� �E �]���H��� H;�� � H�EH��� �E �5��� � H���' � �����Y���H��� H���� A�������7���H��� M���� A�l$ ��� � �� ����% = �� � L�����A�D$ ���� D H��� H���� � � ��������H��� H���5 H�T$0� L��E1��P�H��A��A�����L��� L;�� � I�D$H��� A�$���f D H��� H;�� � H�EH��� D�e ���� � A�l$ ��% �= ��� I�$H�x �������� D H��� L��� L�� L��L)�I�� �L����L��� H��� H�L�H��� ����f D �D$ H�T$$ȉD$$H���)���H��� H�EH9�� �� �D$$�E ��� @ H�T$8H���m���H��� H�EH9�� �t H�D$8H�E H��� �V��� @ � L��L���`�H��� ���A�l$ ��� D H��� J�D% H9�� �� L��L��H���a�L�� ��� D H��� H�D H9�� �G H��L��H���)�HcD$ H�� ��� � H��� H�D H9�� �� H��L��H�����H�D$8H�� �{��� � � L��L������Z��� H��� H��� L�� H��H�T$I�� �L�����H�T$L��� H��� H)�H�(L�H��� H�BH��� D�"��� D H��� H;�� �� H�EH��� �E !��� � H��� H;�� � H�EH��� �E ��� � H��� H;�� �� H�EH��� �E !��� � H��� H;�� �K H�EH��� �E �V��� � H��� H;�� �t H�EH��� �E ��� � H�T$$H�������L��� I�GH9�� �� �D$$A�H��� �v���f D H��� H�EH9�� �V H�D$@H�E H��� ���f�H��� H;�� �- H�EH��� �E � ��� � Mc�H���� H�U(H��L��L�����I9������ ��� @ H��� L��� L�� L��L)�E1�I�� �L����L��� H�(H��� L�H��� H�BH��� ��!� @ L��� L;�� � I�GH��� A� ���� � H��� H;�� �� H�BH��� D�:����f � H��� H;�� �$ H�BH��� � ����f � L��� I�H9�� �� H�u(H��L���y�HcD$$H�� ��� � H��� H;�� �� H�EH��� �E � � � H��� H�EH9�� � H�D$@H�E H��� ���f�H��� H�EH9�� �/ H�D$0H�E H��� ��f�H��� H;�� �T H�EH��� �E �c��� � A�l$ ��� ��� ��� I�$H�z ���������x�H��� H��� L�� H��H�T$I�� �L����H�T$L��� H��� H)�H�(L�H��� H�BH��� ��:� D H��� H��� L�� H��H�T$I�� �L��� �H�T$L��� H��� H)�H�(L�H��� H�BH��� � ��� D H��� L��� M��� L��L)�I�� �L����L��� H�H��� L�H��� H��� ����f D H��� L��� L��� L��L)�I�� �L���]�L��� H�L$8H�H��� L�H��� H��� ����H��� L��� L��� L��L)�I�� �L����L��� HcL$ H�H��� L�H��� H��� �b���H��� L��� L�� L��L)�E1�I�� �L����L��� H�(H��� L�H��� H�BH��� ��*�H��� L��� L�� L��M)�I�� �L���S�L��� J� H��� L�E1�H��� H�BH��� @�*���H��� L��� L�� L��M)�I�� �L����L��� J� H��� L�H��� H�BH��� ��;�H��� H�EH9�� �a �D$ �E �\�H��� L��� L�� L��L)�E1�I�� �L���w�L��� H�(H��� L�H��� H�BH��� ���L��� K�8H9�� �M H�u(L��L�����L�� H��� A�l$ ��L��� I�GH9�� �� �D$8A��r�����% �= ������H��� H�EH9�� �A �D$8�E H��� ��H��� H;�� �j H�EH��� �E ��H��� L��� L�� L��L)�I�� �L���N�L��� H�(H��� L�H��� H�BH��� �!�� L��L����I��H�D$0I��������� ���H��� L��� L�� L��L)�I�� �L�����L��� H�(H��� L�H��� H�BH��� �!���H��� L��� L�� L��L)�I�� �L���r�L��� H�H��� L�H��� H��� � ���H��� L��� L�� L��L)�I�� �L���!�L��� H�(H��� L�H��� H�BH��� ���H��� L��� L�� L��L)�I�� �L�����L��� H�H��� L�H��� H��� �Y���H��� L��� L�� L��L)�I�� �L���w�L��� H�(H��� L�H��� H�BH��� ����H��� L��� L�� L��L)�I�� �L��� �L��� H�(H��� L�H��� H�BH��� ���H��� L��� L�� L��L)�I�� �L�����L��� H�(H��� L�H��� H�BH��� ���H��� L��� L�� L��L)�I�� �L���l�L��� H�H��� L�H��� H��� �;�H��� H��� H�� H��H�T$H�� �H��H�L$��H�T$H�L$H��� I)�H��� J�8H�H��� H�BH��� � ��H��� H��� H�T$H�� H�|$H�� �H��H�L$��H�|$H�T$H�L$H��� H)�H�H�H��� H��� �w���H��� H��� H�T$H�� H�|$H�� �H��H�L$�@�H�|$H�T$H�L$H��� H)�H�H�H��� H��� ���H��� H��� H��� H�� �H��H��H�T$H�L$���H�L$H�T$H��� I)�H��� HcL$$I�H�L��� H��� ����H��� L��� L�� L��L)�I�� �L���y�L��� H�(H��� L�H��� H�BH��� ����H��� L��� L�� L��L)�I�� �L��� �L��� H�H��� L�H��� H��� ���H��� L��� L�� L��L)�I�� �L�����L��� H�H��� L�H��� H��� ���H��� L��� L�� L��L)�I�� �L���~�L��� H�(H��� L�H��� H�BH��� ����H��� L��� L�� L��L)�I�� �L���%�L��� H�H��� L�H��� H��� �N���H��� L��� L�� L��L)�I�� �L������L��� H�H��� L�H��� H��� �^�H��� H��� H�� H��H�L$H�� �H��H�T$�|��H�L$H�T$H��� I)�H��� I�H�L��� H��� ���H��� H��� H�� H��H�L$H�� �H��H�T$���H�L$H�T$H��� I)�H��� I�H�L��� H��� ��H��� H��� L�D$I��� H��H�L$H�� �H��H�T$���H�L$L�D$H�T$H��� I)�I�H�H��� L��� H��� �C���H��� L��� L�� L��L)�I�� �L���I��L��� H�H��� L�H��� H��� �n���H��� L��� L�� L��L)�I�� �L�����L��� H�(H��� L�H��� H�BH��� � ����4���Cx H�= 1�����Fx 1�L�����L��H�=t H��1�����f. � � �AWAVI��1�AUATUH��SH��H�5� H��HL�'dH�%( H�D$81��t��H��I�����H������L��H������H��H������I��H�ExH��H�ExH;�� �� L��H+UH���H�E L)�H���b M�t$I��L��H��L�e � ���H�U ���' L�*M��tA�EL�b�H�B�M��tA�D$H�E H�EXH9EP� H���^��A�D$ % = �� I�$M�d$H�@H�D$0A�E % = �� I�E M�uH�@H�D$(L�l$0H��� I��� A��H���� � �������3 H��� H���� A���v������ H��� I��� �� H���� �t$0�G������� H��� H�L$0H���y L��H���~��H9D$0�� H��� H���� �t$(�������� H��� H�L$(H���� L��H���1��H9D$(������H�T$8dH+%( �� H��H[]A\A]A^A_ÐH�D$0�KX�D$ � ��� �H�T$$�D$$H��� H��� H������H��� ��������� D H�T$(� L��H�����I���q��� L��H�T$0� H���{��I���,��� H��� H;�� � H�BH��� � H��� H���_���H��� H;�� �B H�BH��� D�:�J��� � L��� I�D H9�� �w L��H��L�����H��� H�D$0H�� H���j���L��� L;�� �� I�D$H��� H�D$(A�$�N��� � H��� H�D H9�� �� H��L��H���A��H�D$(H�� 1��:���f D H���������� H��tCH�T$ �c���f � L��� L;�� sxI�EH��� H�D$0A�E �i��� � L��� I�EH9�� � A�U H��� �9��� � L��� I�EH9�� �x �D$$A�E ��f D H��� H��� L�� H��H�T$I�� �L�����H�T$L��� H��� I)�I�L�H��� �4��� @ H��� H��� H�T$H�� H�|$H�� �H��H�L$�-��H�|$H�T$H�L$H��� H)�H�H�H��� H��� ��� H��� H��� H�T$H�� H�|$H�� �H��H�L$����H�|$H�T$H�L$H��� H)�H�H�H��� H��� �Y��� H��� H��� L��� H��H�T$I�� �L���c��H�T$H�L$0L��� H��� I)�I�L�L��� H��� �(��� � H��� L��� L�� L��M)�I�� �L�����L��� H��� I�L�H��� ����f D H��� L��� L��� L��L)�I�� �L�����L��� H�L$(H�H��� L�H��� H��� ���L��L�� H�����I����� D H�������T��� H��� H��� L�� H��H�T$I�� �L���$��H�T$L��� H��� I)�I�L�L��� H��� �-��� D H��� H��� L�� H��H�T$I�� �L������H�T$L��� H��� I)ՋT$ I�L�L��� H��� ����Cx ��H�=� 1��������� D � �AWAVAUATI��UH��SH��H��x�N`dH�%( H�D$h1����1 �d H��1�L�l$L���"��H��H�=� H��1��.��H��1�L�����H��I��L��j I���P � H� � 1�����L���2��H��� H��XZH���� � �C������ H��� H���� ���#������� 1�H��t)H��� H��� H��L��L���U��H9�������H�T$hdH+%( �� H��x[]A\A]A^A_� � L��� L;�� �< I�FH��� A� H��� H���c���L��� L;�� �a I�FH��� A�.�L���f D � H�5J ���I��H���� �@ �� I��$8 L��H)�H��Hw}I9������҉S`���J����p f � L��� I�,H9�� �� ��s{@���i ���� �D$A�$@���� ��A�T�fA�T��zf D A�E ���� ���� I�E H���� H�@H���� �C` ��� H�D$I�|$L��H��I�$��I�T�I�T�I)�L)�A�A��D���H�H�� 1��<���f D H��� L��� L��� L��M)�I�� �L���e��L��� I�H��� L�L��� H��� ���f D ���o 1�L��L���b�����3���f. � �C` �Cx H��L��1����H�=� H��1��D�� @ H��� H��� L�� H��H�T$I�� �L�����H�T$L��� H��� I)�I�L�H��� �p��� @ H��� H��� L�� H��H�T$I�� �L���\��H�T$L��� H��� I)�I�L�H��� �K��� @ �����I�E H�x ���������H��L�������W���H�����I�E�80�������� D �D$A�$��A�T�A�T��#��� � I�E�@����H� H� �@�s������������9������ff. � � �AWAVI��AUATI��UH��SH��8�vddH�%( H�D$(1����� �t �� H��L�=$ ����� L��H��I������L�� H��1����H��L�m �\��H�����H�ExH��H�ExH;�� �s L��H+UH���H�E L)�H���f � � L��H���I��I��� H��I�E H�5� L�m �)��L�m ���D H�ExI�] M�}�H��H�ExH;�� �# L��H+UH���H�E L)�H��� I�_H�E L)�H���� L��H��I������H��H������� H�5 H��I�E L�m ���H�U ���� L�*I�E L�xA�E % L�|$= �� M�uL�����H��M���W A�| �;�K I��$� H��� � �������� I�D$HH�\$I��$� A�E � H��� �` H���� � �������� �7 � 1ҹ L��H�����H���n��H�|$ H���� A�E % = �� � 1�L��H������I���&����� H�5� ���I��H���S �@ � H��8 L��H)�H��H�� I9�������A�T$d���5���f � H�D$(dH+%( � H��8L��L��H��[]A\A]A^A_����H��� �� H���B � ������� I��$� H���V ���������� H�|$ t=I��$� H���e A�E % = �� I�UH��H�����H9��� H�EXH9EP�� H���{��1�H�T$(dH+%( �H H��8[]A\A]A^A_�f D I��$� I;�$� � H�CI��$� �����f D H������3 H���j �! ������� I��$� H��� � ������uT� f�H������K H���J �! �`������� I��$� H���� � �<������� A�T$XI��$� ��� H�D$��H�� �ȉT$$H�T$ �D$ H���� � H���L��H���Z I��$� L�t$H���� A�E % = � I�UL��H��� ��H9D$� H�EXH9EP�]���H���h���P��� A�E ���� ���z I�E H��tqH�@H���� A�D$d �q��� D M��$� M;�$� �� I�FI��$� A� ���f D ���R 1�L��H�������u�f D A�D$d ���f�I��$� M��$� L�� L��L)�I�� �L���$��M��$� I��$� H�L�I��$� �����\$H���� � �y������� A�D$XI��$� ��� H��ulI��$� H�CI9�$� �� �D$�I��$� �Y �\$H���� � �������� A�L$XI��$� ���� H���� H�T$� H���8��H��uJI��$� Lct$H���L A�E % = �� I�UL��H�����HcT$H9��J��� ������U���f D M��$� M;�$� �� I�FI��$� A� ��� D M��$� M;�$� � I�FI��$� A��v��� D L��L�� H�����I���C��� D H��������� L��L�� H������I������ D H��������� L��L��� H�����I��L�h����f � 1�L�� H������I��$� H������f D I��$� I��$� L�� H��H�T$I�� �L�����H�T$M��$� I��$� I)�I�L�I��$� ��� � M��$� I� I9�$� �> A�E % = � I�uI��$� H�����I�$� �x���f � I��$� I;�$� �j H�CI��$� �����f D I��$� I;�$� �z H�CI��$� ��N���f D I��$� I;�$� �j H�CI��$� �!����f D I��$� I;�$� �� H�CI��$� �!���f D ������I�E H�x ���������L�� 1�H��� ��H�����f D I��$� I��$� L��� H��H�T$I�� �L������H�T$M��$� I��$� I)�J�0L�I��$� I��$� �_��� D �D$H�T$ȉD$H���K���I��$� H�CI9�$� �f �D$����� H�T$H������I��$� H�CI9�$� �P H�D$H�I��$� ���f. � 1�L�� H�����I��$� H�����f D 1�L�� H������I��$� H������f D I��$� J�3I9�$� �^ A�E % = �� I�uI��$� L���^��HcD$I�$� ���� @ I��$� J�3I9�$� �n A�E % = �� I�uI��$� L�����H�D$I�$� ��� @ I��$� I;�$� �� H�CI��$� ��c���f D I��$� I;�$� �* H�CI��$� ��3���f D I��$� H�CI9�$� � H�D$ H�I��$� �N���H��H���e�����I��$� I��$� L�� H��H�T$I�� �L���b��H�T$M��$� I��$� I)�I�L�I��$� ��� � I��$� I��$� L�� H��H�T$I�� �L�����H�T$M��$� I��$� I)�I�L�I��$� ���� � L�� 1�H�����H������f D L�� 1�H�����H���@���f D I��$� H�CI9�$� �� �D$����� I��$� M��$� M��� L��L)�I�� �L���;��M��$� H�I��$� L�Lct$I��$� I��$� �D���f. � I��$� M��$� M��� L��L)�I�� �L������M��$� H�I��$� L�L�t$I��$� I��$� �4���f�I��$� M��$� L�� L��L)�I�� �L���t���M��$� H�I��$� L�I��$� H�BI��$� ��a����I��$� M��$� L�� L��L)�I�� �L������M��$� H�I��$� L�I��$� H�BI��$� �!���I��$� M��$� L�� L��L)�I�� �L�����M��$� H�I��$� L�I��$� H�BI��$� �!��I��$� M��$� L�� L��L)�I�� �L���T���M��$� H�I��$� L�I��$� H�BI��$� ��~�I��$� M��$� L�� L��L)�I�� �L����M��$� H�I��$� L�I��$� I��$� �C���f � I��$� M��$� L�� L��L)�I�� �L��蔿��M��$� H�I��$� L�I��$� H�BI��$� ���I��$� M��$� L�� L��L)�I�� �L���4���M��$� H�I��$� L�I��$� H�BI��$� �����I��$� M��$� L�� L��L)�I�� �L���Ծ��M��$� H�I��$� L�I��$� I��$� �Y���f � I��$� M��$� L�� L��L)�I�� �L���t���M��$� H�I��$� L�I��$� I��$� ���f � H�����I�E�80�g����I�E�@�T�H� H� �@����?�I��$� M��$� L�� L��L)�I�� �L���ֽ��M��$� H�I��$� L�I��$� I��$� ��I��$� M��$� L�� L��L)�I�� �L������M��$� H�I��$� L�I��$� I��$� ����A�D$x H�=�� 1�蝼��診��A�D$x H�=`� 1�聼��A�D$x H�=y� 1��j���M�u�V��� �AUE1�A�0 � ATH�� UH��SH��H��� j �l���H��/ L�(XZ���H��H��H��� ���H��H��H��j E1�L�VB 1ҹ~ I���7���H�[1�L��H�{H��H� Hǃ( H��H)���0 ���H�L�� H��Y^L������CX �C`�����Ct����H��[]A\A]�ff. � � �ATUH��SL�f H��M��tH�F L��� ���L��H�����L�c8H�C(����M��t H�C8 L��H���ڻ��L��H���Ϸ��L�c@M��t H�C@ L��H��1���L��H��覷��L�cM��t H�C L��H��1��Ȼ��L��H���}���������c�ǃ � H�CtHǃ Hǃ []A\� D � ��F|��t%�o�� �o�� �F| �� �� �F�u9�u-��� �Fx Hdž Hdž �F� �� ���ff. � � �AUATUH��SH��/ H��買��H��H��I�����H��L��H��j E1�L� @ 1ҹ~ I�����M�d$1�E1�A�0 H�F� I�|$L��I�$ IDŽ$( H��H)���0 ���H�M��$ H�� H�� I��$� H��� �$ �w���ZH��YI��$ H�0�b���H��L��[]A\A]� @ � �AWI��AVI��AUI��ATE1�UH��Bt.H�H�PH�EH�D�L� M��tD�@ E��t M�$$M��tI��L��踶��H��L��L��j L��E1�A� ���ٹ��^_I��H��t L�8A�G � �� ]L��A\A]A^A_Ð�Et(H�E H�PH�EH�D�L� M��t�H ���� I��1�L��H��L������H��t�x tI��P � L���c���I��L������H��L��M��j A�$ ��L��L���)���XZA�G � �[���E1�]A\L��A]A^A_�f � M�$$M���m����l���f D H�@L��H�p���I��� � �AWI��AVAUATA��UH��SL��H��L�/H�$D�L$ �a���H��詶��H�ExH��H�ExH;�� �� L��H+UH���H�E L)�H���� M�}H�E M�uL)�H���K Ic�H��M�n� ���H��H���Q���I�FH���� H�L�sH�XH�E L)�L�{H���e I�M�eI�EI���@ A� � � I��M��H�E L)�H���� K�4�H��M�l$�ٷ��H��H���ζ��I�D$I�GI9�u��T$ H�4$L�m H���,���A��H�E E��tpL� H�P�M��tA�D$H�U H�EXH9EP@H��蘳��H��L��[]A\A]A^A_�f D L��L�� H��� ���I���[��� D H������f D H��E1�� � L��L��� H���ݲ��I����� D H���ȶ���S��� L��L�� H��譲��I���R��� D M������ � L��L�� H���}���I����� D � �AVAUI��ATI��UH��SH�� L�vdH�%( H�D$1�L������H��� I��P I9��� H��H��� H�D$H=����� H���- �! �����tlH��� H���C 1�������tPD�eXH��� E���\ H�D$��H�� �ȉT$�D$H���V H�T$� L�����H���� A����� @ H�D$dH+%( �� H�� D��[]A\A]A^� @ ȉD$H��tE1��>���A�ă��t�H��� H���f H�T$� L��E1��q���H��A��A��� @ L��� L;�� �� I�D$H��� A�$ �f � L��� L;�� �� I�D$H��� A�$!H��� H�������L��� L;�� �� I�D$H��� A�$ D�eXH��� E�������H���I H�T$� L��E1�褴��H��A��A����� @ H�MHL��L��L��H�AH��H�EH���L����� Hc�A�D$�� H�D$dH+%( � H�01 L��H��L��H��H�� []A\A]A^�� D L��� I�D$H9�� �� �D$A�$H��� E1����� � H�EH� A�D$�w���H�D$dH+%( � I�$L��H��L��L� H�� []A\A]A^� & D H��� H��� L�� H��I)�I�� �L���~���L��� H��� I�L�H��� ����f D H��� H��� L�� H��I)�I�� �L���.���L��� H��� I�L�H��� ���f D H��� H��� L�� H��I)�I�� �L���ޱ��L��� H��� I�L�H��� ����f D L��� I�D$H9�� �� H�D$I�$H��� ���f � L��� I�EH9�� �� H�D$I�E H��� �j���f�H��� H��� L�� H��I)�I�� �L���&���L��� I�H��� L�L��� H��� ��� � H��� L��� H�� L��M)�H�� �H���ΰ��H��� I�H��� H�L��� H��� ���� � H��� L��� H�� L��M)�H�� �H���v���H��� I�H��� H�L��� H��� ���躭��f. � � �AWAVAUATUH��SH��H��D�j L�bA�� �A�D$�� I�$L�0M���� A�F � �� I�H�JI�VH�T�H� H��tn�R ��tH�9 ta1�L��H��輮����tHH��� H���� 1�A�� �@�ƍ4� � ������uY�����H��[]A\A]A^A_�f D A�F @ %����A�F H��� H���� A�� �� � E��ư�����t�H�� L�� H���tH�� H��H�� H9��� L��H��H������H�� ��a���H�� H���Q���H��H�� H��[]A\A]A^A_� @ L��� L;�� s(� A�� �� E�I�VH��� A��P����H��� H��� L�� H��H�T$I�� �L���T���H�T$L��� H��� I)�I�L�H��� ��� @ L��� L;�� s$A�� �I�V��H��� �� A�����H��� H��� L�� H��H�T$I�� �L���ȭ��H�T$L��� H��� I)�J�0L�A�� �H��� ��H�J�� H��� ��P����Cx H�={� 1��̬��ff. � �� �AWI��H��AVAUATUH��SH��H��HdH�%( H�D$81����M�� H��H�D$(H=����� I��� H���d �! 臮������) I��� H���v � �d������� A�WXI��� ���� H�D$(��H�� �ȉT$4H�T$0�D$0H���8 � H���v���H���� L9��� I�� H����z I�� H��I�� H9��� H�|$( �� E1�L��P �% � L��H���=�����uYI��L9t$(�m 1�L��H��H���J���H���! H�L9�u�I��� I�GHH���d � �Z������u������H�T$8dH+%( � H��H[]A\A]A^A_�M��� M;�� �# I�D$I��� A�$!I��� H�������M��� M;�� �( I�D$I��� A�$A�WXI��� ���x���H�T$(H�������M��� I�D$I9�� � H�D$(I�$I��� L9��|��� � H�|$( ����� @ 1������I��� I�GHH��tw� �E���������I��L9t$(�����L9�t�I�� �t�I�� H��~�H��I�� 1����I��� I;�� s@H�BI��� � �4��� D I��� I;�� �| H�BI��� ������I��� I��� H�T$H�� H�|$H�� �H��H�L$���H�|$H�T$H�L$I��� H)�H�H�I��� I��� �[��� I��� I��� H�T$H�� H�|$H�� �H��H�L$腩��H�|$H�T$H�L$I��� H)�H�H�I��� I��� � ��� I��� �D$ H���� � �ª������d���A�GXI��� ��t:�D$ H�T$$ȉD$$H���� � H�����H���o����!���f D H�T$ H��u�M��� I�D$I9�� �� �D$ A�$I��� �,���M��� M;�� �� I�D$I��� A�$�U���M��� I�D$I9�� � �D$$A�$�M��� I�D$I9�� �� H�D$0I�$I��� ���I��� I��� L�� H��H�T$I�� �L��� ���H�T$M��� I��� I)�J� L�I��� H�BI��� ����I��� I��� L�� H��H�T$I�� �L��蝧��H�T$M��� I��� I)�J� L�I��� H�BI��� ��=���I��� I��� L�� H��H�T$I�� �L���:���H�T$M��� I��� I)�J� L�I��� H�BI��� �!����I��� I��� L�� H��H�T$I�� �L���צ��H�T$M��� I��� I)�I�L�M��� I��� ���I��� I��� L�� H��H�T$I�� �L���|���H�T$M��� I��� I)�I�L�M��� I��� � ���I��� I��� L�� H��H�T$I�� �L���!���H�T$M��� I��� I)�I�L�M��� I��� ���I��� I��� L�� H��H�T$I�� �L���ƥ��H�T$M��� I��� I)�I�L�M��� I��� ��������A�Gx H�=�� 1��ܤ��ff. � �� �AWAVAUI��ATI��UH��SH�� H�� H��� dH�%( H�D$xH��R H�\$�Ӂ� �\$H�@H�D$`�8 H=���vxA� � H���> �! �z������tII��� E���Q H���� � �R������t!I��� H���� ���5�������4 A������ ��$�D$\H���? � �������t�I��� H���@ �4$������t�A�}X�D$ I��� ���& H�T$\H���0 I��� H�CI9�� �� �D$\�I��� I��( H;l$�! H����8 I�� �# ���� H=����t E1�1�H������I��� I;�� �3 H�AI��� �!I��� E�������H���� � �����������E�EXI��� E���� H�D$`��H�� �ȉT$tH�T$p�D$pH���w � L������H���|���I�� I��( H�D$H9��l H���tI�� H��I�� H9��� H�EE1�H�$H�$N�<�M��u� f D M�?M���� L��H��L��� ���I�O�U A��I��L��L���F� ��t�A��H�D$xdH+%( �) H�Ĉ D��[]A\A]A^A_�f D �D$\H���� � �ɣ�����������D$ �$ A�}XI��� �������D$\H�T$hȉD$hH��� � L���ܢ��H���F���I��( H;l$����H���tI�� H��I�� H9��r �E�� H�E H�PH�EH�D��XH�@�\$HH�D$(H��L������E�}A��uA�Ep���1 ���� �$1�H�|$` A��uK� @ H��H��L��貢��I��H��tDI�N�U E��L��L���� ���� H��H9\$`�> � H��L�����I��H��u�A� �\��� H=����T A� 1����� � I��� I;�� �� H�BI��� �E�EXI��� E���.���H�T$`H���E���M��� I�FI9�� � H�D$`I�I��� �/��� � I��� I;�� � H�CI��� ����f � I��� I;�� �� H�BI��� �I��� H���1���I��� I;�� �V H�BI��� ��P��� � H��� H;�� �1 H�C�D$ H��� �$ ��Y��� D �$ ���I��� I��� H�L$L�� H��H�$I�� �L���?���H�$H�L$M��� I��� H)�H�L�I��� H�BI��� �!� ��� @ H�E I��L;p� ���E1�H;l$�a���I��( ��S���I�� H���C���H��I�� �3���f��D$H����H�D$( ����f. � H��������I�� ���f. � A��I��( �t H;l$tI�� H��~ H��I�� �T$HH��L���v���H�T$(H��L���6�������I��� I;�� �< H�C�D$ I��� �$�����f D I��� H�CI9�� �� �D$h���� D E1��K���M��� I�FI9�� �� H�D$pI�I��� �s���� H�5�� L��跜��I��H���� �@ �� I��$8 L��H)�H��H�D I9�������A�Up������� L������H�T$`L��H��H�D$ I���,���H�T$`H��t<1ۺ H��L��� ���L��H���5���H��L��L��H��H��耚��H�T$`H9�w�H�D$ H� b" L��H�p辘��H�|$` �� I��$P H�$ H�D$0D�|$L� �D$XH�T$\ȉD$\M���� � L��L���H���H�������HcL$X��t)I��� H���� L��L������HcT$XH9���������# H�$H�$H9D$`�/ H�E H�x �� H��L�����H�t$ L����Ƙ��H��E1�E1�j 1�H��H��j L��I��j 蓛��H�� H���V L�pM�������1�L��L��L�����������L$��t��A�F E�A�G �� �� �� I�H�RH�T$hM�w�T$X� �� �T$ M��� ��t$M���: ��L��蟜������j���M��� A�EX���s���H�T$XM���}���M��� I�GI9�� �Y �D$XA�I��� �k���f � H�T$h� L��L��苘��H�T$hI��A�G �T$X� �N���1�H�T$\H�t$hL���D$\跘��I9�� H�T$h���T$XI������f. � H�t$ L���#���H��E1�E1�j 1�H��H��j L��I��j ��H�� H���]���L�t$0� �]��� @ L���ؙ������ I��� I;�� �� H�BI��� ����f. � M��� I�GI9�� �� �D$\A����� @ M��� I�I9�� �b H��L��L���"���HcD$XI�� �5�������E����]��� �����I��� I��� H�T$@H�� H�|$8H�� �H��I������H�|$8H�T$@M��� I��� H)�H�L�I��� ����I��� I��� H�� H�|$8H�� �H��H�L$@謘��H�|$8H�L$@L��I��� H)�I��� L�<H�M��� I��� ����I��� I��� H�� H�|$8H�� �H��H�L$@�F���H�|$8H�L$@L��I��� H)�I��� L�<H�M��� I��� �A���I��� H��� I��� H�� �H��H��H�T$@H�L$8�ܗ��H�L$8H�T$@M��I��� I)�I��� HcL$XN�< H�M��� I��� �/������1 1�L��L���ɓ������ A�Ep ����I��� M��� H�$L�� L��I�� �L���I���H�$M��� I��� L)�H�L�I��� �X���I��� M��� L�� L��L)�I�� �L�����M��� H� I��� L�I��� I��� � ���I��� M��� L�� L��L)�I�� �L��視��H��M��� H�I��� L�I��� H�BI��� �$�D$ ��F�I��� M��� L�� L��L)�I�� �L���@���M��� H� I��� L�I��� I��� ��I��� M��� L�� L��L)�I�� �L�����H��M��� H�I��� L�I��� H�BI��� ��M�I��� M��� H�$L�� L��I�� �L��蒕��H�$M��� I��� L)�H�L�I��� ���H��� L��� H L��L)�H% �H��I���@���M��� H�I��� L�I��� H�BI��� �D$ ��$ ���I��� M��� H�$L�� L��I�� �L���ڔ��H�$M��� I��� L)�H�L�I��� ��I��� M��� H L��M)�H% �H��H�$臔��H�$I�I��� H�I��� M��� I��� ���I��� M��� H L��M)�H% �H��H�$�0���H�$I�I��� H�I��� M��� I��� ��A�F ���w�����tHI�H���f���H�@H��vaA�Ep ���D�|$LH�\$ L��H���ۓ��H��L���Џ���>���������I�H�x �������O���H��L���Q�������H����I�F�80u����I�F�@�z���H� H� �@�j������譐��A�Ex H�=6� 1�臒�� � � �AWAVAUI��ATI��UH��SH���B H��� �� �� �� t\H���� � �i�������R �q L��蓓��H���P H�P H���} H��H��L��[]A\A]A^A_��� @ H���� � � �������� �P L���7���H��u��P H��� �Ex H�=�� 1�衑���H��tc� �������� �P L�����H���X����P H��� � @ H��� H;�� spH�CH��� � � ��� D H��� H;�� �� H�CH��� � � @ H��� H;�� �� H�CH��� � ����f � H��� L��� L�� L��L)�I�� �L���V���L��� H��� H�L�H��� �F���f D 1�L���V���H���q���f D H��� L��� L�� L��L)�I�� �L�����L��� H��� H�L�H��� � ���f D H��� L��� L�� L��L)�I�� �L��螐��L��� H��� H�L�H��� ���H�������[]A\A]A^A_þq H��� ����f � � �AWAVAUI��H��ATUH���p SH��dH�%( H�D$1����H���[ H�x( H��� H���� H��th� �~���A�ă��� H�S H��L������A�ą��� H�D$dH+%( � H�S(H��H��L��[]A\A]A^A_��� � L��� L;�� �� I�D$H��� A�$�f � H�@�$H���� � �������, H�S H��L���N��A�ą�uO�EXH��� ���� �$ȉD$H��� H��� H�CH9�� �� �D$�H��� D H�D$dH+%( �" H��D��[]A\A]A^A_�f�L��� L;�� �� I�D$H��� A�$�I���f D H��� L��� L�� L��M)�I�� �L���V���L��� H��� I�L�H��� ���f D H��tSH�� L��� ���H���9���A������.���f D H�T$� L���ގ��H�������DE����� @ H��� H�CH9�� �� �$�����f D H��� L��� L�� L��M)�I�� �L��膍��L��� H��� I�L�H��� ����f D H��� L��� L�� L��L)�I�� �L���6���L��� H�H��� L�H��� H��� �$��� � H��� L��� L�� L��L)�I�� �L���ތ��L��� H�H��� L�H��� H��� ����Ex H�=� 1������ ���ff. � f�AWI��AVAULc�H� �� ATM��UH��SH�� H�v@H�T$8L��dH�%( H��$� 1����I��H���� A�D$t-I�$H�PI�D$H�D�L�0M��t�H ��tM�6M��tI��L��L�d$|�Z���H��M��L��L����$� �p���I��� ���� H���H � �N�������� �\$|I��� ���� H���� ��� �������� � H�Y H�T$8L��H��B��H��$� dH+%( ��% H�Ĩ []A\A]A^A_ÐH���� � 轌�����th��$� I��� ���� H���x ��萌�����t;I��� Hc�$� H���; L��H���ȋ��Hc�$� H9��G��� � ������L���f D A�G���$A���� *A���� E��ykA�Gx D��H�=!� 1��҉��f�A��u�H�D$8�D$UC�@ �� �� �� �q �D$P ���D �D$V�P ED$W�!f. � �D$U@�D$V �D$W �D$P H�D$@ A�D$t;I�$H�PI�D$H�D�H�H�L$@H��t D�X E��t H�H�D$@H��tH�D$@H�|$@����H�t$8H��D$t�b���H�u H��H�D$H�t$���H���4���H�ExH�t$H��H;�� H�Ex� H��H+UH���H�E H)�H���� H�D$H�^H�FH�E H)�H���� Hc4$H��萊��H��H���Ո��� L��H��H�CH�CH�E �9���� H���H�E H�$���H�D$H���� HcӉ�H� $L�|$L�r�H�\$I��L��L�d$ M��H)�H��H��H� �I��H���f. � I��I� �H��t�AL��H���$���L��L9�u�H�D$H� $L�|$L�d$ H��H��H�$H�$H�E H�EXH9EP�� H������H�D$H��t�P���f ���PH�D$HH� H�@H�D$XH��H�D$�� H�D$HH�HH�1H�L$ �F % = �p H�H�@H��$� H�H�@H�D$h1�H�� L��H���ц��H��t �x �� H�D$� �H9���! �D$ E1�H���� M���$ � E���Jf D A�T$���� ��A�T$I��D��L�I9�� DD$�$�D$Hc$H9D$�L H�\$ H� �I�EL�#H�D$A�D$ � ! M�t$I�uH��L���G���I��H���{���A�GI��� �D$,E���� � �H9�$� r#H���[ �! �!����������I��� H���� � �����������I��� H���� �t$U�ۇ�����������|$P�� � L��L��H���B���������I�uL��H���{���I��H���2 M��tA�FH�t$L��H��L�D$0H�H�PH��腃��A�T$D�|$,L�D$0���{���L��H��L�D$���L�D$�i��� �D$UA�D$V �D$W �D$P �{��� @ I��� I;�� �a H�CI��� ����f � I��� I;�� �� H�CI��� �����f � H��t�t$U衆����������C��� M��� M;�� � I�GI��� �D$UA���� @ M��� M;�� �< I�GI��� A�I��� H���H���M��� M;�� �i I�GI��� �D$UA��|$P�;���I��� H��tO�t$V������� ������ � M��� M;�� �4 I�GI��� A�!��� � M��� M;�� �L I�GI��� �D$VA���� @ I��� I��� H�� H�|$0H�� �H��H�T$`貃��H�|$0H�T$`I��� I)�I��� I�H�I��� ��� D I��� I��� H�� H�|$0H�� �H��H�T$`�R���H�|$0H�T$`I��� I)�I��� I�H�I��� �i��� D I��� I��� H�� H�|$0H�� �H��H�T$`��H�|$0H�T$`I��� I)�I��� I�H�I��� �<��� D E��M��L�d$x�L$tL��H��H�T$@M���.������V �D$x�����|$t� �\$P�� H��$� ��H�L$��I��� H=� GډڃʀH��Oډڃ�H�� �L$Oډڃ���E�E���� H=���v#H��� �! 蜃������C���I��� H���� � �y������� ���I��� H��� ���X������������|$PI��� �6 H���� �t$V�*������� ���� @ H���O �� ������������A�GXI��� ���� ��$� H��$� ȉ�$� H���N � H������H���&����\��� @ H���� �� 蕂������<���A�WXI��� ���� �D$|ȉ�$� H���B H��$� � H��讁��H���4������ � M��� I� I9�� �� H��L��L���B��Hc�$� I�� ���f D H�\$HH��H���x���H��H���m|��H��I�w0E1�j H�T$PA� H�$� �ƀ��AYAZI��H���� M�W@A�D$t/I�$H�PI�D$H�D�L�0M��tD�@ E��tM�6M��tI��H��P � H��L�$�s���L��H���}��H��L��H��j H�t$I��A�$ ���7���^_M��H�T$8D��L��H�������f. � H�������+��� H��$� � H���;}��H�D$h�����D$x���������\$P=� ~���� ��� @ �D$UB�D$V �D$W �D$P ��� @ I��� I��� H�� H�|$0H�� �H��H�T$`��~��H�|$0H�T$`I��� I)�I��� I�H�I��� �q��� D H���M ������������I��� ���� �� ���A E�oXE���� �D$xȉ�$� H��� H��$� � H��H�����H���\� @ L��$� M��� I������� E�_XE��� D��I�� H��$� �Ả�$� D��$� M���% � L��H���~��H�����H��$� H��t+I��� H���� H�T$hH���o~��H;�$� ������ H�|$�} H�\$HH��H���m}��H��H���by��1��|$P���D�d$WH�|$8D����}��H���� H�P L��H���*���� D H���; � L��H����}��H���]��� � H��$� H�������I��� H�CI9�� �� ��$� ��� f � M��� M;�� �% I�D$I��� A� $�l� � I��� I;�� �� H�CI��� ���=���f � I��� I;�� �- H�CI��� �����f � M��� M;�� �� I�D$I��� A� $�W� � H�|$�� �D$ E1���� @ I��� I��� H�� H��H�T$0H�� �H�t$`�{��H�T$0H�t$`I��� I)�I��� J�8H�I��� H�BI��� �D$V�����M��� M;�� �r I�EI��� A�] I��� ���M��� M;�� �� I�EI��� A�E � ���I��� H�CI9�� �� ��$� �I��� ��I��� H�CI9�� �� �D$|�I��� ��I��� H�CI9�� �� ��$� ����D$V�D$WP�D$P �N�I��� I��� H H��H�$H% �H��H�D$�)z��H�$H�L$I��� I)�I��� J� H�I��� H�BI��� ����I��� I��� L�� H��H�$I�� �L����y��H�$M��� I��� H)�H�L�I��� H�BI��� ���"���I��� I��� L�� H��H�$I�� �L���cy��H�$M��� I��� H)�H�L�I��� H�BI��� ���1���I��� I��� L�� H��H�$I�� �L���y��H�$M��� I��� I)�J� L�I��� H�BI��� ��M� D ���x E�gXE���I �D$tH��$� ȉ�$� H���� H��� H���uy��H�����I��� HcL$tH���= H�T$@H���Iy��I��HcD$tI9��0����� ���? E�WXD�d$|D��E���� A�H��$� D��$� M���� � L��H����x��H���C����'� � H�D$HH� H�@ �n��� �D$��I��� D�`�� �D$XD�D$E�OX��E��DE�D�d$|E���p D��H��$� Ή�$� H���� H��� H���Ox��H�����H�|$A� � H��$� ����D�l$L�t$ H� $H�\$�i�A�XH��$� H� ��� H�� ʉ�$� ȉ�$� H���� H��$� � H����w��H��� � A��Ic�H9�����I��I��� E��u�ȉ�$� H��tJH�$� H���yw��H��t���f D H��� H�$� H���Nw��H��t��� I��� H�BI9�� r|��$� �I��� �^���f D I��� H�BI9�� �� H��$� H�I��� �(���I��� H�AI9�� �� H�I��� � ��� � I��� I��� H�T$H�� H�|$H�� �H��H�L$�u��H�|$H�T$H�L$I��� H)�H�H�I��� I��� I��� ���� @ I��� I��� H�T$H�� H�|$H�� �H��H�L$� u��H�|$H�T$H�L$I��� H)�H�H�I��� I��� I��� ���� @ I��� I��� H�L$H�� H�|$H�� �H��H�T$�t��H�|$H�L$H�T$I��� H)�H�H�I��� H��$� I��� I��� ���I��� I��� L�� H��H�$I�� �L���At��H�$M��� I��� H)�H�L�I��� H�BI��� ����I��� I��� L�� H��H�$I�� �L����s��H�$M��� I��� H)�H�L�I��� H�BI��� ���I��� I��� H��� H��H�$H�� �H���~s��H�$I��� I��� Hc�$� I)�I�H�M��� I��� ��D�d$tH���t A���t�����������c� D�d$xH���� A���t���������;� M���� A��L���st������1����� D H��$� M�����M��� I�EI9�� �� M�e I��� ���H��H� H���o��H���O�H�� H���n��H����H����r��H�t$���M��� M;�� �� I�EI��� A�] �j�M��� I� I9�� �U H�t$@H��L���p��HcD$tI�� ���M��� I� I9�� �i H�t$hH��L���p��H��$� I�� �C�H�t$H���r����H���� A��� s������2������f�H���� � L���9�H�T$tH������M��� I�D$I9�� �n �D$tA�$I��� ���H�T$|M������M��� I�T$I9�� �� A�$I��� �M�M��� M;�� �� I�EI��� A�E !I��� ���M��� M;�� � I�EI��� E�e �#���M��� I�D$I9�� �/ H��$� I�$I��� ���M��� M;�� �� I�EI��� E�e �,�M��� M;�� �� I�EI��� E�e �s�H�T$|H�������I��� H�CI9�� �� �D$|�I��� ���I��� I;�� �� H�CI��� D�#�g���I��� I��� L�� H��H�$I�� �L���o��H�$M��� I��� I)�J�(L�I��� H�BI��� �I��� ���I��� I��� L�� H��H�$I�� �L���*o��H�$M��� I��� I)�J�(L�I��� H�BI��� ���M��� M;�� �� I�EI��� �D$VA�E I��� �I�I��� M��� L�� L��L)�I�� �L���n��M��� H�I��� L�I��� I��� ��I��� M��� L��� L��M)�I�� �L���Dn��M��� H��$� I�I��� L�M��� I��� �=���I��� I��� L�� H��H�$I�� �L����m��H�$M��� I��� H)�H�L�I��� I��� ���I��� M��� L��� L��M)�I�� �L���m��M��� HcL$tI�I��� L�M��� I��� �T���I��� I��� L�� H��H�$I�� �L���:m��H�$M��� I��� I)�J�(L�I��� H�BI��� ��F�I��� M��� L�� L��L)�I�� �L����l��M��� H�I��� L�I��� I��� ��I��� I��� L�� H��H�$I�� �L���l��H�$M��� I��� H)�H�L�I��� I��� ��M��� I�D$I9�� � ��$� A�$�/���M��� I�D$I9�� �� ��$� A�$I��� ���M��� I�D$I9�� � ��$� A�$���M��� I�D$I9�� �H �D$xA�$�I��� H�CI9�� � ��$� ����I��� I��� L�� H��H� $I�� �L���dk��H� $M��� H��I��� L��H)�H�L�I��� H�PI��� D� ��I��� I��� L�� H��H� $I�� �L���j��H� $M��� H��I��� L��H)�H�L�I��� H�PI��� � !I��� ��I��� I��� L�� H��H� $I�� �L���j��H� $M��� H��I��� L��H)�H�L�I��� H�PI��� D� �>�I��� M��� L�� L��M)�I�� �L���,j��M��� I�I��� L�M��� I��� ���I��� M��� L�� L��M)�I�� �L����i��M��� I�I��� L�L��$� M��� I��� ����I��� I��� L�� H��H� $I�� �L���i��H� $M��� H��I��� L��H)�H�L�I��� H�PI��� D� ���I��� M��� L�� L��I�� �L��� i��M��� H��I��� H��L)�H�L�I��� H�PI��� D� ��I��� I��� L�� H��H� $I�� �L���h��H� $M��� H��I��� L��H)��L$VH�L�I��� H�PI��� �I��� � �I��� M��� L�� L��M)�I�� �L���Mh��M��� I�I��� L�M��� I��� �g���I��� M��� L�� L��M)�I�� �L���g��M��� I�I��� L�M��� I��� ���I��� M��� L�� L��M)�I�� �L���g��M��� I�I��� L�M��� I��� �A���I��� M��� L�� L��M)�I�� �L���Zg��M��� I�I��� L�I��� �D$|M��� �(���I��� M��� L�� L��M)�I�� �L���g��M��� I�I��� L�M��� I��� ����I��� M��� L�� L��M)�I�� �L���f��M��� I�I��� L�M��� I��� ���I��� M��� L�� L��L)�I�� �L���cf��M��� H�I��� L�I��� I��� ���I��� M��� L�� L��L)�I�� �L���f��M��� H�I��� L�I��� I��� ���A�Ex H�T$@H�=_� 1��4$�-e��A�Ex H�T$@H�=�� 1��4$�e���c�����'�A�Gx H�=� 1���d��A�GH��� H�5�� A�Gx HD�H�T$@H�=9� 1��d��H�D$8H�ۢ �@ A�Gx �� t�� H�k� H�]� HE�D��H�=� 1��wd��A�Gx H�t$@H�= � 1��\d��ff. � �� �AWL�=� AVAUE��A�0 ATI��UH��SH��L��H��0H��� �L$� L�L$E1�j �Ce��AXAYH� H����f���@ ��f��H� H�@ H����f��H�@L�p�D$A�~x���D$��t L��H���3���A����� ��A��C �� H�[M���� �D$E�nXH��M��� L�%�� I�F`����I�Fh A�Fp����I�FH����I�FP����A�FA� �a��I�F � H��I�F�d��� H��I�F0H� H�@� �d��� H��I�F@�td��� L��H��I�F�b��� L��H��@ % = �� �b��� H��H���}_��I�� L�%w� � H��L���ob��� L��H��@ % = �! �Lb��� H��H���,_��A�~XA�vXI��( H��� H�H�k� �� H����I��� HD�I��H��toH���c��I9��� H��L��H�����I��� ��u H�<$ �� L��H���e��I��� H��t A�F�� 1�����H��([]A\A]A^A_ÐL�jI��� L�a�J�"I9�� � A���� A���, E��tA�E �A���F M�� �L���f. � �+a��H� H�@ ��� � �a��H� H�@ �z��� � L��H������I�Ƌ �c��� I��� H���� I��� I��� H�I��� �P��� I�E H�zH��H�D��I�L�H�L�H��L��H)�H)�D����;�����1ɉ�L�2L�79�r�� ���f D I��� I��� H�T$I��� H�|$H�� �H��H�L$��`��H�|$H�T$H�L$I��� H)�H�H�I��� I��� I��� ��� I�� H���х �5��� @ H��� L��E1�j H��� A�0 H���a��ZYH� H����b���@ ��b��H� H�@ H���zb��H�@H��H�@H��� H��� H)��I_��H� $H���� D � �N^��� Idž� I��� �a���f�A�E �D��A�L��L�����f � 1��i���f � D��A�L�f�L����A�Fx H�=� 1��^�� � � �PXH����� ��� �Fx H��� H�5 � H��H�E� HD�t �� tA� A� H�=J� 1��^��H�=|� 1��^�� D � �AVAUI��ATUH��SH��1��4\��I��H��tH�� L����]��H��M��tA�D$H�SHH�s L��L��H�BH�CH�s\��H���� H��t �� u [L��]A\A]A^�L��L���[���� I�ƅ�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L���K]����ug�E %����E H��L��L���[��A�VI�F ��v-��L��A�V[]A\A]A^�f. � E1��L��� � L��L���5_���4���ǃ I�F�@t�H� H� �H �ff. � f�� �AVL��P AUI��ATUH��SH�~(�H��uH�FHH�F(H��tH�� L���P\��H��H�SHH�s L��L��H�BH�CH�[��H���� H��t �� u[L��]A\A]A^� � L��L���Y���� I�ą�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L����[����u_�E %����E H��L��L���Z��A�T$I�D$ ��v#��L��A�T$[]A\A]A^� � E1��E���L��L����]���5���ǃ I�D$�@t�H� H� �H �ff. � �� �AVL��8 AUI��ATUH��SH��H��tH�� ��Z��H��H�SHH�s L��L��H�BH�CH�Y��H���� H��t �� u [L��]A\A]A^ÐL��L���5X���� I�ą�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L���{Z����ug�E %����E H��L��L���.Y��A�T$I�D$ ��v+��L��A�T$[]A\A]A^� � E1��K��� � L��L���e\���3���ǃ I�D$�@t�H� H� �H �ff. � �� �AVL��h AUI��ATUH��SH��H��tH�� �Y��H��H�SHH�s L��L��H�BH�CH�DX��H���� H��t �� u [L��]A\A]A^ÐL��L����V���� I�ą�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L���Y����ug�E %����E H��L��L����W��A�T$I�D$ ��v+��L��A�T$[]A\A]A^� � E1��K��� � L��L���[���3���ǃ I�D$�@t�H� H� �H �ff. � �� �AUL��P ATI��L��UH��SH��H��H�VHH�BH�FHH�v �V��H��tM��t �� uH��� H��[]A\A]� D L��H���U���� I�Ņ�tSA�D$ � t=I�$H�JI�T$H�T�H� H��t#�R ��tH�9 t1�L��H����W����ucA�D$ %����A�D$ L��L��H���wV��A�UI�E ��v ��H�$� A�UH��[]A\A]� D L��H���Y��H��� �1���ǃ I�E�@t�H� H� �H �ff. � AWE1�AVM��AUI��ATUH��SH��H��H���L$�7U��I��M��t� L��L����V��I��M��tA�D$H�SHH�s L��L��H�BH�CH�vU��H���E M��t �� �� H���� H��� H���� I�T$H��L���W��H9��� I�$H�hI�$I�T$H�@� A�D$ %� �_��DA�D$ �S\��tA��� �� M��tH�� uH�CGITempFI9�K �D$��t A�L$ H��L��[]A\A]A^A_� � H��� H�.H9�� �� I�|$H���U��H�� �F��� � L��L��� S���� I����t\A�G � tHI�H�JI�WH�T�H� H��t0�r ��tH�9 t#1�L��L��L�L$�^U��L�L$���! A�G %����A�G L��L��L��L�L$�T��L�L$A�QI�A ���� ��A�QH���e��� � 1�1�L��L���!W����� @ L��L��E1��Q������ D A�~ile �����H�mt-confiI�D$H9������xg.cg�����f�x i�w���H�5� L��1��aS���a��� @ E1��f���A��� �)���E1�E1��t 1�L��L���jV��� ��� D L��L���V�����ǃ I�A�@����H� H� �H ����f D � �ATI��UH��SH��H��H��� dH�%( H�D$1�H��t_H�T$� �@T��H��uB�T$�EX��tʉT$��I��1�H��L���g���H�T$dH+%( u:H��[]A\�f D 1��� @ H��� H�HH;�� w�H��� �T$��Q�� � � �ATI��UH��SH��� H��H��t#�.U�����t9I��H��[L��]Hc�1�A\����f�H��� H;�� sH�PH��� � ��[1�]A\�f � � �ATI��UH��SH��� H��H��t+�T�����tII��H��[L��]Hcй A\�_��� � H��� H;�� sH�PH��� � � � [1�]A\�f � � �ATI��UH��SH��H��H��� dH�%( H�D$1�H��t_H�T$� �R��H��uB�T$�EX��tʉT$��I�ع H��L�����H�T$dH+%( u7H��[]A\� 1��� @ H��� H�HH;�� w�H��� �T$��P�� � � �AVAUI��ATUH��SH��H��H��� dH�%( H�D$1�H���� H�� ��Q��H���� H�4$H���S��I��M��tL�� H���P��I��M��tA�D$H�SHH�s L��H��H�BH�CH�O��H��t6M��t �� u`H�D$dH+%( � H��L��[]A\A]A^� @ E1��� H��� H�BH;�� w�H�H��� H�$�I���f � L��H����M���� I�ƅ�tOA�E � t;I�U H�JI�UH�T�H� H��t"�R ��tH�9 t1�L��H���*P����uNA�E %����A�E L��L��H����N��A�VI�F ��v��A�V����f D L��H���-R�����ǃ I�F�@t�H� H� �H �� N��� �AVAUI��ATUH��SH��H��H��� dH�%( H�D$1�H���� H�T$� ��O��H���� �t$L���Hc��Q��I��H��tH�� L���O��H��M��tA�D$H�SHH�s L��L��H�BH�CH�M��H��t7H��t �� uYH�D$dH+%( � H��L��[]A\A]A^� D E1��� H��� H�PH;�� w�H��� �L$�D���f�L��L���L���� I�ƅ�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L���KN����uG�E %����E H��L��L���L��A�VI�F ��v ��A�V�����L��L���UP������ǃ I�F�@t�H� H� �H ��HL�� � � �AVAUATI��UH��SH��� H��H���� �O���ƃ��to�ƀL��H��� P��I��H��tH�� L���XM��H��M��tA�EH�SHH�s L��L��H�BH�CH� L��H��tH��t �� uE[L��]A\A]A^ÐE1�[]L��A\A]A^ÐH��� H;�� s�H�PH��� �0�^��� D L��L���]J���� I�ƅ�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L���L����uO�E %����E H��L��L���VK��A�VI�F ��v��L��A�V[]A\A]A^�f�L��L���N������ǃ I�F�@t�H� H� �H �ff. � f�� �AVAUI��ATUH��SH��H��H��� dH�%( H�D$1�H���� H�� �ZL��H���� �$H���J��I��M��tL�� H���K��I��M��tA�D$H�SHH�s L��H��H�BH�CH�2J��H��t5M��t �� u_H�D$dH+%( � H��L��[]A\A]A^� E1��� H��� H�BH;�� w�H�H��� H�$�I���f � L��H���uH���� I�ƅ�tOA�E � t;I�U H�JI�UH�T�H� H��t"�R ��tH�9 t1�L��H���J����uNA�E %����A�E L��L��H���kI��A�VI�F ��v��A�V����f D L��H���L�����ǃ I�F�@t�H� H� �H ��H��� �AWI��AVE1�AUATUH��SH��H��H�L�nH1�H�D$�L��I��M��t� L��H����I��I��M��tA�D$H�SHH�s L��H��H�BH�CH�~H��H���� M��t �� �K H��� H���� �K������e ��� �� ���} L��H��H���o���I��M���A � H�5G� H���L��I��A�D$ � t A�O A�D$ % = �c I�T$L��H���K��A�T$���� ��A�T$L�shM��� A�F �� L��8 L��L)�H��H� M9�� H��� K��H���eH��� H�5�� H����H��1�1�H��H��I���J��H�Ch�@ tH�@�x �� � L��H���J��H�E H�H��H�E M���� A�F �� L��L)�H��H�� A�F ���� ���> ���� I�H�x �p � �Cx A�F % = �2 M�fA�G % = � I�wL��H�=Ń 1��H�� � H��� H;�� �l H�PH��� � �������L��H��H����I������ � L��H����D���� I�ą�tRA�F � t>I�H�JI�VH�T�H� H��t&�R ��tH�9 t1�L��H���G�����4 A�F %����A�F L��L��H���E��A�T$I�D$ ���� ��A�T$H��� H��� ���� ��� @ A�F ���� �C`��� yX� H�5� H����F��I��H���� �@ �� H��8 L��H)�H��H�} I9������҉S`���� � L��H����H��I��H��tA�D$H�s L��L��H����D��H��L��[]A\A]A^A_� @ �� �� L��H��H����I���u�������� L��H��H���y�I���U����1ҹ L��H���D��H�����f D M9������H���� �A �w L�aA�|$ �g A�D$M��tA�W���� ��A�WH�EXH9EP�� H��� C��� ���f. � E1����� � ���� I�H���`���H�@H���8���H���I���I�F�80�"����7���f�A�D$ ���B ���� I�$H���, H�@H���� �C` �\���f�H���F���L��� H�ExH��H�ExH;�� �1 H�L$H��H+UH���H�E H)�H���� � L��H���F��H��H���D��H�L$� H��H�AH�AH�E H�sh�XF����������Cx H�=� 1��ZD��f. � � H�5� H��� D��H�ChH���$����@L�shM����������f � ���� 1�L��H����@�������f��C` �Cx H�=[� 1���C�� @ ��uK��� 1�L��H���@������������ � L��H���D���K���L��H���uE���#���I�H�x �M����b��� D ���O���I�$H�x ��������� � I�H���=���H�@H������H���&���I�F�80��������� H��H���mC���$��� � L��H��H�L$�PC��H�L$�2���f D L��H���D��� ���I�F�@�����H� H� �@�}������� D L��H���}D���u��� � ���� 1�L��H��H�L$�E?���������H�L$�\���H���Z���I�D$�80�.����G���ǃ I�D$�@�����H� H� �H ���I�D$�@���H� H� �@�������I�F�@�z���H� H� �@�j����N���H�t$� H��H����>��H�D$��H����B�������Cx ��H�=� 1��A���Cx H�=�| 1��mA���Cx A�G % = uI�wH�=;� 1��DA��L��� 1�H����?��H����L��� 1�H���?��H������ 1�L��H���?��I�����f � � �AWAVAUATI��UH��SH��H��(L�/dH�%( H�D$1��B��H���@��H��� H���� �PB������W H��� �t4H���� H�T$� H���@��H���' �D$� f D H���� H���A���D$����� ��� H��D��=��H��H���{@��H��� I��H���� �L$H�PH���@��I���D$L9��� I�H�BI�I�VH�@� A�F %� �_��DA�F H��� H���z �]A��Hcȃ��teH�ɾ H��H�L$HE��\=��H��H����?��H��� H�L$I��H���� H�PH��H�L$�x?��H�L$H9��� f. � E1�H�D$dH+%( �� H��(L��[]A\A]A^A_� � H��� H;�� s�H�PH��� � t@H��� H�PH;�� w�� H��� �D$�sX�������ȉD$����f � H��� H;�� �\���H�PH��� � �D$�K��� D H��� H�H9�� �(���I�H���=��H�L$H�� I�H�HI�I�WH�@� A�G %� �_��DA�G H�ExH��H�ExH;�� �q L��H+UH���H�E L)�H���� M�uH�E I�uH)�H���� L�~H��� H��H�u H�5�y �l>��H�U ���� H�H��H�U �@ �� L�hM���� A�E��A�EM��tL�� H����<��I��A�E��A�EH�SHH�s L��H��H�BH�CH�;��H�������M���� �� �� L��H���*:���� I�ƅ�tWA�D$ � tAI�$H�JI�T$H�T�H� H��t'�R ��tH�9 t1�L��H���m<�����m A�D$ %����A�D$ L��L��H���;��A�VI�F ���+ ��A�V @ H�EXH9EPnH���9���4����H��� �T$H�H9�� ����I�~�;���D$H�� �S��� H��� H;�� ���H�PH��� ��l����H���=���f D L��L�� H��� 9��I���� D H�� H��� 9��H����� � M��t+L�� H���+;��I���D��� H����<����� H�SHH�s 1�H��H�BH�CH��9��H������(���L��H���M=������ǃ I�F�@�����H� H� �H �x����99���Cx ��H�=�v 1��;���Cx H�=,{ 1��:��ff. � f�AWAVAUI��ATUSH��H�� H��� dH�%( H��$ 1�H���� H�� ��:��H��uc�<$pst0�� H��� H��� H�T$� L���:��H��u.H�perl-stoH9$�� �Cx H�=?v 1��E:�� D 1�H��$ dH+%( � H�� []A\A]A^A_� D H��� H;�� s�H�PH��� �(A��A�tzH�� H��� A��ttH��� H���� �q;��A�ă���u���D��� D��� A���� �Cx D��D��1�A� � H�=�y �w9�� � H�I� H��� ��D��� ǃ� A��kX�� I��P ���f D H��� H;�� ����H�PH��� D� �S���A�� �P �Ct���+ ���M������kXu�A� A� H��� H���� �q:���Ń���v���H��� B�T%H���i Lc�L��H��L���8��I9��G������| H�12345678H9$�h �|$�r �|$ �� �|$ �q E��������|$ ���Cx H�=qt 1�� 8��H��� H��� H9�����H�rH��� �*B�T%Hc�L�$I9������H�� ��6��L��� �F��� D � H�5�s L���7��I��H���� �@ �N I��8 L��H)�H��HwkI9������Ct���f. � H��� H�PH;�� ������L$�@H��� f�D$ ���� D H��� H��� �/��� D A�G ��tG���� I�H��t6H�@H��v �Ct �����l$��f D H��t I�G�80u�f��Ct �'��� @ f�|$re�Y����l$ A�������H�{� A��H��� �����H��� D�cX�8���E1����f���t+I�H�x �������� � H��L���6�������u1�L��L���3�������I�G�@� ���H� H� �@u�� ����4���Cx H�=!r 1���5���Cx H�=ov 1���5���Cx H�=�v 1���5���Cx H�=ev 1��5�����kX�`���A��A��A��E�����E1���� D AWAVI��AUATUH��SH��H��(L�fH��� dH�%( H�D$1�M���E D�cXE��� H���� H�T$ � �@5��H���~ HcD$ H��� H�D$H���� �6��Lc�A����R E���� H�T$H��H�sE1�j A� � H���5��AZA[H���? H�0�F % = �) H�Lc` H�s 1�L��H���q5��H���� L� M��tA�D$f. � H�D$dH+%( �� H��(L��[]A\A]A^A_�f. � H���� H�T$� �84��H���v H��� ���f�H��� H���5��Lc�A����J E���� H��� H��� H�T$� H����3��H���M����T$H�s 1�H��ʉT$���4��H�������Cx Hct$H�=�t �r3��f�H��� H��� H�AH9��� H� H��� H�L$H9��� H�PH��� D�(E���D���H�sHH���)5��H�T$H��H�sj I��A�$ � H���44��AXAYH���O A��!�- H��� J��L��H��H���I��H���# ��� L�l$�I���H��� H���� �D4����X�+�����B�� H��� H���Z � L��H���2��H���� �sX�D$���� ȉD$�� f D H��� H�PH;�� �� Hc H��� �D$ H�D$H��� H��� ���f. � H��� H;�� sHH�PH��� D�(E���� H��� H�PH;�� �P���� H��� �D$��f D E1��0�����bu�H��� H���# �&3���D$���t�Hc�H;�� r5=����� H��� H�q��1��HcL$H��� H�QH��H��� ��t-H��� H���0 H��� H���)1��HcL$H9��c���H��� H��� H��� � �T$�/��I��� � ���L��H����-���� I�Dž�tRA�F � t>I�H�JI�VH�T�H� H��t&�R ��tH�9 t1�L��H���0�����S A�F %����A�F L��L��H���.��A�WI�G ���� ��A�W��� � A��!�A������ ~e�Ct���Z ��uUW��� A� D��j!��� A� 1��Cx H�=/q ��/��H��tI�D$�80�� �Ct � H�������� @ H��� H;�� ��H�PH��� � ���f � � H���3,��Lc����� H��� H;�� �����H�PH��� � �D$H��H;�� ������ D H��� H�PH;�� �h����H��� �L$���f D H��� H�H9�� �8���H��� H���!.��HcL$H�� ���� H�5�j H���|.��I��H�������@ �� H��8 L��H)�H��Hw!I9������Ct�X���L��H���G0�����A�D$ ���������tQI�$H���s���H�@H���R����Ct ����ǃ I�G�@�����H� H� �H �����t$I�$H�x �����k���H��H���:.���?�����u1�L��H���*�����A����+��I�D$�@�s���H� H� �@u��b����Cx L��H�=�n �p-���Cx H�t$H�=Un �X-���Cx H�=�i 1��C-�� � �ATI��UH��H��H��� dH�%( H�D$1�H���� �.���D$����� ��t9H��� H���� H�T$� L���,��H��uY�UX�D$��tȉD$H�u81�Hc�L���-��H���� H� H��L��H�P����H�T$dH+%( ulH��]A\� @ 1��� @ H��� H��� H9�s�H�PH��� � �D$��y�H�BH9�wƋ H��� �L$�[��� @ H��� H��� ���#*���Ex Hct$H�=�m �+��ff. � � �AWAVAUATI��UH��SH�� L��� dH�%( H��$� 1�M���� L���Z-���D$ A�Ń��tFH��� ���? H���� H�T$ � L���+��H��u�D$ � D L����+��E1�H��$� dH+%( �� H�Ĩ L��[]A\A]A^A_�f � H��� H��� H9�s�H�PH��� D�(D�l$ E���0 H�rH9�w��H��� �D$ �UX��tȉD$ ���D AƄ$* �x�)��AƄ$* I��H��� D�l$ H��� M��D��Hc�H��uEH��� H� H;�� � ���H��L����)��H��� �5f � E1�L�|$Hc�H��t�L��L���U*��HcT$ I��H9�����D��L��L��A� �q,��H�UPH�u8L��H��H�BH�EP�F(��I��H��tL��H��L���`�I��M������L���\*���r��� � A��L�|$�-���H��� H��� ����'���Ex �t$ H�= f 1��)���Ex ��H�=qk 1��j)��f. � � �AWAVI��1�AUE1�ATUH��SH��H��� '��I��H��t� H��H���(��I��M��tA�D$I�VHI�v L��H��H�BI�FH�J'��H���� M��t A�� uB1�L��H���U�H���� H���� A�L$ I�D$H��L��[]A\A]A^A_� L��H���%��A�� I�Dž�tOA�E � t;I�U H�JI�UH�T�H� H��t"�R ��tH�9 t1�L��H����'����uuA�E %����A�E L��L��H���&��A�WI�G ��v9��A�W�+��� D E1��K���� L��H��H�D$� &��H�D$� ����L��H����)�����Adž I�G�@����H� H� �H �m��� D � �ATUH��H���-���I��H��t H��H���(��H��L��]A\�ff. � @ � �AWAVAUI��ATUH��SH��1�H���%��I��M��tL�� H���&��I��M��tA�D$H�SHH�s L��H��H�BH�CH�M%��H���� M��t �� �� ǃ 1�H��H���K�ǃ I��H���U A�D$ ���( ��M�t$A�D$ A�~ �� I�L�(M���� A�E � �� %����A�E E1�1�L��H���&��1ҿ H��1���%��A�E�' I�E H�PI�EH�D�H�H��� �@ ��t H�: �� 1�L��H���%������ I�D$�@t H� H� �H H��L��[]A\A]A^A_�I�M I�UH�qH�t�H�>H��t�v ���� H�? �� %����A�E H�AH�D�L�8M�������P ��t M�?M������I������ � L��H���e"��D�� I��E��tSA�E � t?I�U H�JI�UH�T�H� H��t&�z ��tH�9 t1�L��H���$������ A�E %����A�E L��L��H���U#��A�VI�F ���� ��A�V��� @ 1�L��H���S$���������A�E ����A�U � �'���I�UI�M ��� � L��H���"��A�D$ ���f D E1��v��� � L��H���5&���^���ǃ I�F�@�5���H� H� �H �#���A�e ����1�L��H���Cx �!��M��L��L��H��H�=Gf 1���#���Cx 1�L��H���l!��L��H�=�e H��1��#�� � � �ATUH��H���=���I��H��t H��H���$��H��L��]A\�ff. � @ � �AWAVAUATUH���� �� 1�I��I���!��I��M��tL��� L���"��I��M��tA�D$H�UHH�u L��L��H�BH�EH�U!��H��� M��t �� ufH��1�L���a�H��H���� � L��L���� ��H��E1�E1��P L��L���l$���U���� ���U]L��A\A]A^A_� D L��L��� ���� I�Dž�tNA�F � t:I�H�JI�VH�T�H� H��t"�R ��tH�9 t1�L��L����!����uoA�F %����A�F L��L��L��� ��A�WI�G ��v3��A�W� ��� � E1�]L��A\A]A^A_�H��L����#���6���L��L���#������Dž I�G�@t�H� H� �H �x����Fx H�=(^ 1��!�� D � �AWAVAUATUH���� �� 1�I��I���& ��I��M��tL��� L��� ��I��M��tA�D$H�UHH�u L��L��H�BH�EH�e ��H��� M��t �� ufH��1�L���q�H��H���� � L��L��� ��H��E1�E1��P L��L���|"���U���� ���U]L��A\A]A^A_� D L��L��� ���� I�Dž�tNA�F � t:I�H�JI�VH�T�H� H��t"�R ��tH�9 t1�L��L���� ����uoA�F %����A�F L��L��L��� ��A�WI�G ��v3��A�W� ��� � E1�]L��A\A]A^A_�H��L����!���6���L��L����!������Dž I�G�@t�H� H� �H �x����Fx H�=8\ 1�� �� D � �AWAVAUATUH���� �� 1�I��I���6 ��I��M��tL�� L���� ��I��M��tA�D$H�UHH�u L��L��H�BH�EH�u ��H���L M��t �� �� H��1�L���}�H��H���! �x tK� L��L��� ��H��E1�E1��q L��L��� ���U���� ���U]L��A\A]A^A_� L��L��� � ��L��L��E1�E1��q 1��8 ��]L��A\A]A^A_� L��L���m���� I�Dž�tOA�E � t;I�U H�JI�UH�T�H� H��t"�R ��tH�9 t1�L��L��� ����unA�E %����A�E L��L��L���c ��A�WI�G ��v2��A�W����f D E1�]L��A\A]A^A_�H��L��� ��� ���L��L��� �����Dž I�G�@t�H� H� �H �y����Fx H�=Z 1��e �� D � �AWAVAUATUH���� � 1�I��I�����I��M��tL��� L��� ��I��M��tA�D$H�UHH�u L��L��H�BH�EH�E��H���D M��t �� �� 1�H��L���M�I��H��� H��1�L���4�H��H��� � L��L�����L��I��p A�����L��L���< ���U���� ���UA�V���� ��A�V]L��A\A]A^A_�f � L��L���E���� I�Dž�tRA�F � t>I�H�JI�VH�T�H� H��t&�R ��tH�9 t1�L��L��������� A�F %����A�F L��L��L���8��A�WI�G ��vG��A�W���� E1�]L��A\A]A^A_� � H��L���u ������L��L���e ������L��L���U �����Dž I�G�@�r���H� H� �H �`����Fx H�=�W 1��!���� �AVAUATUSH��H��dH�%( H�D$1��� �F 1�H��I�����I��M��tL�� H���K��I��M��tA�D$H�SHH�s L��H��H�BH�CH����H���� M��t �� �� 1�H��H����I��H���n H��� H���� H�T$� H���l��H���B �CX��t �D$ȉD$� L��H���A��D�L$L��E1��p L��H������A�U��� ��A�UH�D$dH+%( �G H��L��[]A\A]A^�f D H��� H�PH;�� �� �H��� �L$�\���f D L��H������� I�ƅ�tOA�E � t;I�U H�JI�UH�T�H� H��t"�R ��tH�9 t1�L��H��������unA�E %����A�E L��L��H�����A�VI�F ��v2��A�V����f D E1����� � L��H���������L��H�������I���ǃ I�F�@t�H� H� �H �y����Fx H�=8U ������f�� �AWAVAUI��ATI��UH��SH��( H��� dH�%( H��$ 1�H���� ����Ã���� H��� Lc�H���� L�|$L��L��L���9��I9�udL��H��L����I��H��t!A��M���V 1�H��L�����A�L$ � H��$ dH+%( �� H��( L��[]A\A]A^A_ÐE1��� H��� H��� H9�s�H�pH��� D�0L��N�6I9�L�D$w�L�|$� L��L���p��L�D$L��� �;��� � H��� H��� ��C�� � �AWI��AVAUI��ATUH��SH��H��� dH�%( H�D$1�H���� H�T$� ���H���� �D$�UX��tȉD$=���� �x���L��� I��M���� HcL$H��L��L�����HcT$H9�uhL��H��L����I��H��t#D�L$M��V 1�H��L�����A�L$ � L������H�D$dH+%( �� H��L��[]A\A]A^A_ÐL�����E1��� H��� H�JH;�� w�H��� �D$����f. � H��� HcT$H��H� H;�� �t������H��� �'�������Ex H�=KR 1���� D � �AWI��AVAUATUH��SH��H��H��� dH�%( H�D$1�H���u H�T$� �f��H���� �sX��t �D$ȉD$� L�����I��H��tH�� L�����H��M��tA�D$H�SHH�s L��L��H�BH�CH�-��H��tHH��t �� � HcT$��u5H�D$dH+%( �� H��L��[]A\A]A^A_� � E1��� L��L���=���D$��~�E1�1�M��P �0 � H;�� Hc�L��L��ID����H��t��D$��9�~/1�H��L�����H��H��t�I9�u��D$��A� 9�� @ E���B�����L��L��Hc�� ���,���f � H��� H�PH;�� �8�����sXH��� �L$��������v��� L��L������� I�Ņ�tL�E � t:H�U H�JH�UH�T�H� H��t!�R ��tH�9 t1�H��L��������uS�E %����E H��L��L�����A�UI�E ��v��A�UHcT$���T������L��L�������6���ǃ I�E�@t�H� H� �H ����� @ � �AWAVAUI��ATUH��SH��H��H��� dH�%( H�D$1�H���e H�T$� ���H���� D�SXE��t �D$ȉD$� H������I��M��tL�� H������I��M��tA�D$H�SHH�s L��H��H�BH�CH�k��H��tFM��t �� � �T$��u4H�D$dH+%( �� H��L��[]A\A]A^A_�f D E1��� ��H��L��Hc������|$��~�E1�I���� @ � L��H�����H��u��sX�$��tȉ$Hc�H;�� r4=����I H��� H�q����Hc $H��� H�QH��H��� ��t,H��� H���� H��� H���8��Hc $H9��;���H��� M��L��H��H��A�$ � H��� j �L$���ZYH��� ���A��D9l$����1�H��H���4��I��H������H��� H�������H��� H�PH;�� ������H��� � $��� � H��� H�H9�� �����H��� H�����Hc $H�� �&����H��� H�PH;�� �H����D�SXH��� �L$E����������f � L��H��� ��D�� I��E��tQA�E � t=I�U H�JI�UH�T�H� H��t$D�B E��tH�9 t1�L��H���6����uTA�E %����A�E L��L��H���� ��A�VI�F ��v��A�V�T$���W������L��H���3���:���ǃ I�F�@t�H� H� �H ��Cx H�=uK 1����� ���� �AWAVAUI��ATUH��SH��H��(H��� dH�%( H�D$1�H���� �p��A�ǃ���| H��� H���� H�T$� H�����H���P D�CXE��t �D$ȉD$� H������I��M��tL�� H���� ��I��M��tA�D$H�SHH�s L��H��H�BH�CH�w ��H���� M��t �� � �T$���� ��L��H��Hc�� ���L$���� A��E1�D�|$�M f��{������� �L$�L$��t �tA�N ��� A��A���% D��H��� ���DE�D�����DE�H���� H�T$� H���{ ��H��� �SX�D$��tȉD$Hc�H;�� r5=����k H��� H�q� ��HcL$H��� H�QH��H��� ��t-H��� H���; H��� H��� ��HcL$H9��� H��� H��E��1�� H��� j AVj$LcD$0L��H��� ��H�� H��t\A��D9l$�5 1�H��H�����I��H��t8H��� H�������H��� H;�� sH�PH��� � �{��� D E1�H�D$dH+%( �x H��(L��[]A\A]A^A_� � 1�H��H���{��H��H��t�H��E1�E1�1�j AVj�4��� @ H��� H�PH;�� w��H��� �L$�a���f�H��� H�H9�� �`���H��� H���� ��HcL$H�� ��� � A�V���3 ��A� A�VL�5�� ���f. � H��� H��� H9���H�BH��� D�:H�PH9������H��� �L$�s��� H��L������� I�ƅ�tSA�E � t?I�U H�JI�UH�T�H� H��t&�r ��tH�9 t1�L��H���B ������ A�E %����A�E L��L��H������A�VI�F ��vv��A�V�V���A��D�|$f � �D$������A�L$ ����f D L��H��D$ A� � ��L�5L� �D$ �v���H��� H��� ����L��H���� ������ǃ I�F�@�C���H� H� �H �1����Cx H�=F 1�� ����� @ � �AUATI��UH��SH��H��� dH�%( H�D$1�H���< H�T$� �} ��H��uo�UX��up� L���� ��I��H��t�@H�UHH�u L��L��H�BH�EH�l��H��t/HcT$��u>H�D$dH+%( � H��L��[]A\A]� @ E1��� �D$ȉD$� @ L��L��� ���D$��~�1��Vf � �[ �����t���It11�H��L��i�� � ��H��H��t�Hc�L��L������H��t���9\$�U���H��� H��u�H��� H;�� �[���H�PH��� � � H��� H�PH;�� �0����H��� �UX�L$�������������������� �AWI��AVAUATUH��SH��(H��� dH�%( H�D$1�H��� H�T$� ����H��usE�GXE��ur� H��� ��I��H��t�@I�WHI�w L��H��H�BI�GH���H��t1�T$��uAH�D$dH+%( �. H��(L��[]A\A]A^A_� E1��� �D$ȉD$� @ ��H��L��Hc��'���|$��~�H��P E1�E1�H�D$�^ � ������t���V�~ ��v�� 1�L��H���7��H��H���{���I��� H���m �F������]�����k�J I��� H���b H�T$� H�����H���(���A�wX�D$��tȉD$Hc�I;�� r5=���� I��� H�q���HcL$I��� H�QH��I��� ��t-I��� H��� I��� H�����HcL$H9������I��� I��L��H��H��A�$ � I��� j �L$ ����ZYH���i���A��D9l$�1���I��� H�������I��� I;�� �6���H�PI��� � ��V�����M���� A�FI��� L��H�������I��� I��� H9����H�BI��� �:k�� H�PH9������I��� �L$��� @ I��� H�I9�� �����I��� H�����HcL$I�� ���� � I��� H�PI;�� �X����E�GXI��� �L$E�������A���f � H�t$� H�����H��H�������I����1�L��H���=���A�Gx H�=�@ 1�����"��I��� I��� ���ff. � @ AWAVI��AUATI��UH��SH�� H��(dH�%( H�D$1��<��I��M��tL�� H���$��I��M��tA�EH�SHH�s L��H��H�BH�CH����H���� M��t �� �� M��u,H�D$dH+%( �� H��(L��[]A\A]A^A_�f D I�VL��H��E1��>��H�D$H�D$�� � H�T$� H�����H���$ H�L$�sX��t �Hc�H�L$H9�� w4H������: H��� H�q�P��H�L$H��� H�AH��� H��t-H��� H���t H��� H�����H�L$H9��� H��� M��L��H��H��A�$ � H��� j �L$ �w��ZYH���d I��M9�����1�H��H�����I��H���> H��� H�����H��� H�PH;�� � Hc��� �L$H�L$H��� ����f D L��H�����D�� I��E��tWA�D$ � tAI�$H�JI�T$H�T�H� H��t'�z ��tH�9 t1�L��H��� ������ A�D$ %����A�D$ L��L��H�����A�WI�G ��vh��A�WM���������� H��� H�H9�� r4H��� H���M ��H�L$H�� �u��� @ H�L$����f D E1��d���L��H������O���ǃ I�G�@�Q���H� H� �H �?����Cx H�=�< 1��q ���|���ff. � �� �SH�^H�sH��t�9���H��� H��t�� ���S|��tH��� H��t� ��1�[� @ H��� H��t�� ���C|��u�1�[�ff. � �� �USH��H��H�GxH�P�H�WxH�WHc H�hH�H)�H����u�VC��H�CHc�H�D�H�H��[]�H��H�5%; ����� �ATUSH�GxH��H�P�H�WxH�Hc D�b(H�W�hH��H�H)�H������ H��� E���� H��A�0 E1ɹ j H��9 �b ��_AXH� H�������@ ����H� H�@ H������H�@H�@�0���� D#`�| H��8 H�SHc�H� �H�SH��H�[]A\� H��� H�V9 E1�j A�0 ����ZYH� H���m���@ �c��H� H�@ H���S��H�@H�@�@X��u�H��h ����H��H�5�9 �v���f D � �AUATUSH��H��dH�%( H�D$H�GxH�P�H�WxH�WHc H��hD�A(H� �H�H)�H����utHc�L��P 1�1�H��I��L�$$L�,� �{�����t?L�$$L��H������H�SH��H�CL�H�H�D$dH+%( uH��[]A\A]� L�$$����H��H�5@: ���ff. � � �AVAUATUSH�GxH��H�P�H�Wx�(H�H�WD�p(Hc�H� �H�H)�H����umD�e��Mc�Hc�J�4�N�,� ����H�SE��E1�H� 1�H��H��H�p(蕘��H��8 A��H��P E��HE�H�SJ��LkL�+[]A\A]A^�H��H�5u9 ����f D � �AUATUSH��H��H�GxH�P�H�WxH�WHc H�hH�H)�H������ H�G�@#�� H�PH�GL�$�L�-X7 � H��L������� L��H�ߋ@ % = th��� H��H������H��H�CA�L$ Hc�H��L�l(���%�����uO��� tF��I�T$A�L$ M�eHkH�+H��[]A\A]� ���H� H�P �f�����I���J��� L��H������H��H�57 ��� @ � �AUATUSH��H��H�GxH�P�H�WxH�WHc H�hH�H)�H������ H�G�@#�� H�PH�GL�$�L�-�4 � H��L������ L��H�ߋ@ % = th����� H��H�����H��H�CA�L$ Hc�H��L�l(���%�����uO��� tF��I�T$A�L$ M�eHkH�+H��[]A\A]� �[���H� H�P �f����I���J��� L��H������H��H�5�5 �t��� @ AWAVI��AUATUH��S��H�� H��� dH�%( H��$� 1��F�D$P �$H���� ���A�ǃ���M ������ ���@ ���� 1�H��E1�����D$ I��M��tA�D$I�VHI�v L��H��H�BI�FH����H���� A��@u�r �#�������� �@tZ1�L��H������H���� �P���� ���PI��� H��u�I��� I;�� �� H�PI��� � �@u�A��D��D��I��� ���� �L$$� ���� H���� H�T$`� H�����H��u+E�NX�D$`E���� ȉD$`� H�|$�-��� D E1�H��$� dH+%( �? H�� L��[]A\A]A^A_�f � H��H���E�������H��� H;�� s�H�PH��� D�8D����<t7<�� <�P���� H��E1�����D$ I���H���f. � � ��f � ��� H���9 H�T$L� H������H�������L$LE�FXE��tɉL$L��� f � I��� H��tT�/���A�Ń������A���d A��u� H�������D$PI�����A���# 1�L��H���B���f�I��� I;�� �����H�PI��� D�(�H���A H������D$`����U���I�v81�Hc�H������H���H H� H�@H�D$� H���M H���a����D$L������ ������( H�D$ H�t$pH�t$��� I��� �L$(Hc�H���t H��H�T$H���w���I��HcD$LH��I9������H�D$��H��� H�����I�VPI�v8H��H��H�BI�FP�b�H���b���I��� ���� A�~X���^ H��� H�T$h� H����H���1����T$h�D$l��H�� ��H�H�T$XH�Ҹ H��HE�H���h�H�L$XH��H��t*I��� H���Q H�PH�����H�L$XH9��A H�H�HH�H�SH�@� �C %� �_��D�C A�N\��t ��� �{ A�ǀtXA��I��� � H��� H�T$P� H������H���T���A�VX�D$P��tȉD$P���� ���D H�D$ A�� � ����$H�t$� H����$��1�H��/ H��H��I���Q�H��t �x �� A�� �� L� H1 I�v@L��H��L���;;��I��H���t H�|$ �C H�D$L��H��H�@�CH��x���� $L�D$L��H��A� H��H�$�h<��H�4$H��t�V���` ���V�S���[ ���SH�\$H��H���{�H��H���p�H�|$H�D$pH9�t �D$$��u�$�E�������L��1�H�����I��A���� A���� � L��H���w��L$E1�E1�L��L��H����M�������A�V���� ��A�V���1�H������D$qI���S���� H���x��D$PI���9���I��� H�PI;�� �;�����L$`I��� ���I��� I;�� ����H�PI��� � �D$`���I��� H�PI;�� �����L$LI��� ���I��� I;�� �����H�PI��� ��L$L����� � A��t{H���� H�T$`� H���7�H���u����T$`A�vX��tʉ�H�T$X�D���I��� L�M;�� L�D$0�/���H�|$�,�L�D$0�L$(M��� �t���H���0 H���V�Hc�H�T$X���������H���5 H�T$X� H����H������H�T$X���ƅ* �y�2�ƅ* H�D$H��H��� �L$LH�t$�����I��� H�I9�� �� H�{H���f�H�L$XI�� ���H���� H����D$P��������:���f�I��� H�BI;�� � ���H�I��� H�T$h����I��� H�BI;�� ���I��� �u���I��� I;�� ����H�PI��� �H�T$X���I��� H�BI;�� �����H�I��� H�T$X�w���I��� I;�� �z���H�PI��� � �D$P�)���I��� H�PI;�� �K�����L$PI��� ���L��H�����E�� I��E��t^A�G � tJI�H�JI�WH�L�H�H��t2D�I E��tH�: t#1�L��H��L�D$(��L�D$(���- A�G %����A�G L��L��H��L�D$(��L�D$(A�PI�@ ���� ��A�P���H��H��E1�����x������D$( �D$P� H���r�L$PH��H��I��H�D$�QHc���HcL$PI�H��H�JI�O�������A� H�\$8H�D$TH��L��D�l$0E��D�l$(I��L�d$(I��� � A�GX���� H���1 H�T$h� H���y�H��������T$h�D$l��H�� ��H�H�T$`I�w 1�H����H��tjH� Ic�H��H��t�@H�A��D;t$P� I��� E���m���H���� � L��H�����H���2����T$Tʉ�H�T$`� H�t$`I9w(� Ic�H��P H���f � H��t}H�T$`� H����H�����H�T$`�0��� D I��� H�BI;�� ���I��� �t���I��� H�BI;�� ���H�I��� H�T$h���I��� H�BI;�� �^�H�I��� H�T$`���D�l$0H�\$8M��L�d$(� ���H�t$1�H���|�1ҿ H��1��;�I�$I�v@H� �@t+H�H�@H�RH�D�L�8M��t�x ��tM�?M��tI��L��H�t$(�b�H��L��E1�j H�t$8A�D ��H����I�$ZH��L� ) I�v@YH�L���3��I��H������H�t$A�Fx H�="/ 1�H���� � � H���c�� H��H��H�D$��H�D$H� H�@ ���� L��H������M���� L��H����A�d$ �����/����D$( �z���H�@H��H�p���H�|$ H�D$�� � H������ H��I��H����I�E H�t$1�H��H�@ I�E�CH����� $H�T$M��H��A� H��H�$�b3��H�4$I��H��t�V���� ���V�S���� ���SL��H���w�L��H���l�H�D$H��t�P���� ���PM���- A�G �" H�T$L��H�������� I�v H���H�I�nHM��t'A�T$���t ��A�T$���S ��A�T$M�gM��tA�D$I�VHI�v L��H��H�BI�FH�M�H���\�A�WI�G ���� ��A�WH�|$H�D$pH9��0�D�\$$E���"��B����� �x�E1�E1��t 1�H��H���H��[�H���k����H��H���[����L��H���K���L��H���;����H���.��e���Adž I�@�@����H� H� �H ���L��H������&���H��H������,���H�t$H������L���L��H�������L��H����A�T$����A�Fx H�=`+ 1���A�Gx H�=�) 1���A�Fx Hct$`H�=G* �r�A�Fx ��H�=a* 1��Z�A�Fx H�t$H�=6+ 1��?��J��D$LA�Fx H�=�$ �p1�� �ff. � f�� �1���� D � �AWAVI��AUI��ATUH��SH��8H��� dH�%( H�D$(1�H���� �p�A�ă���� ���# A���Y �uXH��� ��tcH���* H��H�T$ � L����H��ug�D$ �T$$��H�� ��H�H�D$A���� H�|+ D��Hc�H�>�� � H���O H��H�T$� L���2�H��t� @ E1�H�D$(dH+%( �� H��8L��[]A\A]A^A_� � H��� H;�� s�H�PH��� D� A������H��� H��� H9�s��}XH��A� H��� ���� H�HH9��k���H� H��� H�D$ �� � H�T$L��H��L���U�I���8��� D � L��L�d$��I��M��tL�� L����I��M��tA�GH�UHH�u L��L��H�BH�EH�6�H������M��t �� �� L��L��L���}�M��������D$ E1�I��P �2 H;�k L��L��L��HD����H���v���I��M9��� 1�H��L�����H��H���P���H9�u��D$�� @ M�� H�T$H��L��蠍��I���#��� � M��1���f � H�u H�T$1�L�����H���� L�8M�����A�G����f D H��� H�BH;�� �����H�H��� H�T$A���\����Ex D��H�=6( 1��� � H��� H�������#���������]��� D H��� H��� ���� D H�D$(dH+%( � H��8H��L��� []A\A]A^A_���f D L��L������ H�Å�tOA�E � t;I�U H�JI�UH�T�H� H��t"�R ��tH�9 t1�L��L���Z���ufA�E %����A�E L��H��L��� ��SH�C ��v+���S����|$ �p���I�T$�L��L�����[���H��L���E����Dž H�C�@t�H� H� �H ��8��Ex H�t$H�=�& ��� �AVH��L�� 1�AUH� � L�5��ATL�%� UL��H�����H����E1�L��H��L�O H���A��H�5� ��E1�L��L��H��L�� H�5� ���E1�L��L��H� H��L�� H�5� L�5'��@( ��E1�L��L��H� H��L�p H�5� �@( ��E1�L��L��H� H��L�G H�5y L�5~��@( �R�E1�L��H��H� L�h H�� H�5^ �@( �%�E1�L��H��L�> H�� H�5H ��E1�L��H��L�� H�K H�59 ���E1�L��L��H��L� H�5+ ��E1�L��L��H� H��L�� H�5! �@( ��E1�L��L��H� H��L�� H�5 �@( �n�E1�L��H��H� L�� H�d�H�5� �@( �A�E1�L��H��L�p H�j�H�5� � �� H�� H�5� ���H�� I����H�� L��H��H���@��H�� ��H�� L��H��H��� ��H�� �q�L��H��H�� H�����H��8 L��H��H�� ����H����#��H�� H�5� � ���H��D��H��]A\A]A^���ff. � �� ��G < �9 H� z$ ��H��Hc�H�>��f � �� � �� � �� �� ����H���f D � H���f D � H���f D � � tY�P ���H��tJ� � � � t�P ��H��u� � � H���f D � �{���f D � �k���f D �p H�|$�i�I��� M���E���H�|$�G �� � �� � � ����q �2�H�|$H���R����G � ��� @ � �f�� �AW��L��AVI��AUA��ATA�� I��UH��SD��H��8dH� %( H�L$(1ɩ � DE��tA�@ ���H;vd � A�FH��L��D$ ��(��A�Dž��� �|$ �M�F�� IcF�ڃ�A�D �Eډڃ��E�E1�E��t+H��� H���� ��L�D$���L�D$����� ���� �EXH��� ��� �D$ ȉD$$H���< L�D$H�T$$�oE���� L��H��L���)(����DE�H�D$(dH+%( � H��8D��[]A\A]A^A_� D ��I��$P �� � H��tkL�D$H�T$ � L�����L�D$H��toA�����뎐L��� L;�� �� I�EH��� A�] ���� � M�ƃ�E1�����f�H��� H�CH9�� � �D$ �H��� HcL$ ������H��� H��tQL��L�����I��HcD$ I9��\������H��� H�CH9�� �@ �D$$��M����� � L��� I� H9�� �� H��L��L���Z��HcD$ H�� ���f � H��� H��� L�D$H�� H��H�L$H�� �H��H�T$�J��H�L$H�T$H��� L�D$I)�H��� I�H�H��� I�EH��� A�] ���f � H��� L��� L�D$H��� L��M)�H�� �H������HcL$ L�D$H��� I�H��� H�L��� H��� ��� � H��� L��� L�D$L�� L��L)�I�� �L���i��L��� L�D$H�H��� L�H��� H��� �e��� D H��� L��� L�D$L�� L��L)�I�� �L��� ��L��� L�D$H�H��� L�H��� H��� ����H�� � � �UH��SH��H��H��H��tH�CH�XH��t�V��vK���VH��H��E1�A�0 j H��� � H�� ���H�� H��H�0H��[]��� H������ff. � AWE1�A�Ϲ AVE��A�0 AUI��H�* ATI��USH��H��@H��� dH�%( H�D$01�j ���^_H� H���7���@ �-��H� H�@ H��� ��H�@A��H�h�MxD�� ��t H��L��� ���E ��� ��H��� �E � H��A��M����A ��f A�E � �� % = �� I�E I�}H�@H�D$ H��1�H�T$H�|$H�t$H�D$�D$�j���|$ H�|$H���1 H9�t:L������I�ŋ@ <�� ��DI�U I�]A�E H�D$H�BI�U H��H�B�o�� �o�� �E| �� �� A�E ��@�� % = �F I�E H�PH��� I�EH��� H��L��H��� H�H��� HDž� 赜��H���� H��� H� H�5� �Ex HD�H�=| 1��m�� D H��� H��L���f���H��t�H���� � � L�����H�E H�V H�E@1�H9�� �< H�E� L��L�- �|��H�E(����� L��H�E �c��D�}L��L��H�E8� H�EH H�EP �]\�E �Et����Dž ���� L��L��@ % = �b �]��� L��H���=��H�� L�-7 � L��L���/��� L��L��@ % = �) � ��� L��H������H��( 1�H��L��舠��I��E��t%�o�� �o�� �E| �� �� H��L��H�]�\��H��� H��tH�� L�����M��t\H��t L�������uI�EH��t �@uD @ A�E� H�D$(dH+%( � H��8L��L��[]A\A]A^A_�`��M��$P H�D$(dH+%( �� H��8L��[]A\A]A^A_�f����H� H�@ ��� � ����H� H�@ ���� � H��L������D�� H�ŋ ��H��� �E ����� ���HDž� � H��� ��� @ H��� � L��L�����H��� ��� D I�E L��L��H��v��I��H�������C � t=H�H�JH�SH�T�H� H��t%�R ��tH�9 t1�H��L��������� �C %����C ���f D 1�A�E � �����L��L���u������� D � L���K�����f D L��H�T$ � L���;��H��H�D$ � ���f D �]\�M���� L��L�����A�E �+��� � I�E�@����H� H� �H �����[���Ex H�=� 1��6���Ex H�=� 1��!���� �AWAVAUATUSH��H��H�GxH�/H�P�H�WxHcH�GI��D�bH��H)�H���U����� Mc�J�4�N�,� ���A� L�x��~$H�SA�FH�H�4F % = uGH�D�@ 1�L��H��1����H��H������H�SJ��LkL�+H��[]A\A]A^A_� � � H�����A���H��H�5� �_��ff. � @ � �AUATUSH��H��H�GxL�OH�P�H�WxHc H�H���hI��H)�H���B���wHc�A� M�,�L�$� ��~ ��Hc�I�4ɋF % = u=H�D�@ L��H��1�1����H��H������H�SH��LcL�#H��[]A\A]�f�� �6��A���H��H�5� ���f�� �AWAVAUATUSH��H��H�GxH�P�H�WxH�WHc H� hH�H)�H������ H��Hc�E1�A�0 L�,�H��� j L�5� � L��L�$� ���AXAYH� H�������@ ����H� H�@ H������H�@H�p�~x��tH�����A�E %� � = � �0 E1�E1�1�� L��H���l����u4H��P H�����H�SH��LcL�#H��[]A\A]A^A_� � H��� L��E1�j H��� A�0 H���J��ZYH� H�������@ ����H� H�@ H������H�@L�pI��� M��� I)�H��u � ���Idž� I��� I��� M��t<L�I��� 1�A�E � ufA�F\1�A� 1ҹ H������H������ I�� � � �p L�����H�������L��H��������f. � L��H��������H��H�5� �1�� � �H��H��� Unable to record new classname Can't determine type of %s(0x%lx) re::regexp_pattern returned only %d results Unexpected return value from B::Deparse::new Unexpected return value from B::Deparse::coderef2text The result of B::Deparse::coderef2text was empty - maybe you're trying to serialize an XS function? Max. recursion depth with nested structures exceeded No magic '%c' found while storing tied %s No magic 'p' found while storing reference to tied item Unexpected object type (%d) in store_hook() Too late to ignore hooks for %s class "%s" Freeze cannot return references if %s class is using STORABLE_attach Too many references returned by STORABLE_freeze() Item #%d returned by STORABLE_freeze for %s is not a reference Could not serialize item #%d from hook in %s No magic '%c' found while storing ref to tied %s with hook Storable::recursion_limit_hash vstring too large to freeze re::regexp_pattern Storable::forgive_me Can't store %s items Can't store item %s(0x%lx) You lost %s(0x%lx)%c Storable::Deparse B::Deparse new coderef2text Storable(3.25) Storable::canonical scalar array cloning STORABLE_freeze STORABLE_attach Not a reference Storable::recursion_limit pst0 12345678pst0 ��Q� ��?file CGITempFile mt-config.cgi Unable to retrieve code sub Storable::Eval @ code %s caused an error: %s Storable::_make_re Bad count %d calling _make_re File is not a perl storable Storable::accept_future_minor Byte order is not compatible Double size is not compatible Too large size > I32_MAX Out of memory with len %ld Tying is disabled. vstring too large to fetch f, obj Out of memory with len %u STORABLE_thaw 3.25 v5.32.0 Storable.c Storable::init_perinterp $$ Storable::net_pstore Storable::pstore Storable::mstore Storable::net_mstore $;$ Storable::pretrieve Storable::mretrieve Storable::dclone Storable::is_retrieving Storable::is_storing Storable::last_op_in_netorder Storable::stack_depth Storable::stack_depth_hash Storable BIN_MAJOR BIN_MINOR BIN_WRITE_MINOR CAN_FLOCK Storable::drop_utf8 Not a scalar string f, flag = 6 sv, flag = 6 sv Corrupted storable %s (binary v%d.%d), current is v%d.%d Corrupted storable %s (binary v%d.%d) SECURITY: Movable-Type CVE-2015-1592 Storable metasploit attack Unexpected type %d in retrieve_code Can't eval, please set $Storable::Eval to a true value Unexpected return value from $Storable::Eval callback code %s did not evaluate to a subroutine reference _make_re didn't return a reference Storable binary image v%d.%d more recent than I am (v%d.%d) Integer size is not compatible Long integer size is not compatible Pointer size is not compatible Old tag 0x%lx should have been mapped already Object #%ld should have been retrieved already Storable binary image v%d.%d contains data of type %d. This Storable is v%d.%d and can only handle data types up to %d Class name #%ld should have been seen already Corrupted classname length %lu Cannot restore overloading on %s(0x%lx) (package <unknown>) Cannot restore overloading on %s(0x%lx) (package %s) (even after a "require %s;") STORABLE_attach called with unexpected references STORABLE_attach did not return a %s object No STORABLE_thaw defined for objects of class %s (even after a "require %s;") Object #%lu should have been retrieved already Unexpected type %d in retrieve_lobject Frozen string corrupt - contains characters outside 0-255 Magic number checking on storable %s failed ���������p��!��!��!��!��!��!��!��!��!��!��!��!��!��!��!��!��!��!��!��!�����p��������������(��������������(����������8��perl-store ;� R ����� ̷��� ��� ����T ���� ���� ����� L���$ ����� <��� L� <�� ����� ����8 � ��d ��x ��� ���$ ���p | ��� \��D L��� �(�� l+��x ,/��� �V��L ,\��� �\��� ^��@ |_��� �`��� <b��0 �c��� �f��� |g�� �g��8 lh��p ,i��� k��� �l��, �n��� |p��� ,z�� ,���l ����� ܍��, ,���X ����� |���� ���� l���d ����� ����� ����, ����� ����� ����$ ��p ����� L��� ���` |���� ,��� ,���h ����� ,���� ���� ܼ��p ����� |���� ����( ���d ��� ��� ��@ ,��| |��� ��� |�, ��� �� ��D zR x � $ ��0 FJ w� ?:*3$" D �� , \ ���L B�A�D � ABF \ � ���� B�E�E �K(�D0�D8�GHFPIHA@T 8A0A(B BBBD HHHPZHA@ H � p���6 F�B�E �B(�D0�A8�G�j 8D0A(B BBBF L 8 d�� F�B�G �B(�A0�D8�N�@ 8A0A(B BBBB \ � $�� F�B�B �B(�D0�D8�G�X�H�n�A�� 8A0A(B BBBH d � �� F�B�E �B(�D0�D8�Dp 8J0A(B BBBE � 8A0A(B BBBG L P ���� F�P�H �D(�D8I@Q8A0W8H@Y8A0a(A ABB ( � l���� F�A�D ��AB � 0���u @ � ����� F�B�A �D(�L0W8H@�8D0T(D ABBd $ H���} F�E�E �E(�D0�C8H@T8A0Z (E BBBB l8H@T8A0R (B EBBJ H � `���K F�E�B �B(�D0�D8�GP^ 8D0A(B BBBG l � d���� F�B�E �D(�D0�DP� 0D(A BBBE � 0A(A BBBG v 0A(A BBBJ ` H ���� F�B�B �B(�A0�D8�GP� 8A0A(B BBBG � 8A0A(B BBBE L � ��� F�H�B �B(�A0�D8�G�� 8A0A(B BBBA x � ���I F�B�B �E(�D0�D8�G�� 8D0A(B BBBG ~�H�J�H�I���H�J�H�I� d x � ��� F�B�B �E(�D0�D8�D@\ 8G0A(B BBBI 8F0A(B BBBA ` � �"��� F�B�B �H(�A0�I8�DP� 8G0A(B BBBL � 8D0A(B BBBC l D H&���' B�E�B �L(�D0�D8�G� 8A0A(B BBBB � �I�\�B�n�H�V�A�` � xM��Y F�I�B �K(�D0�D8�JhZpGhB`C 8A0A(B BBBB �hMpVhA` 4��� `������ < PR��k EAD L X �R��c F�B�E �A(�D0�c (D BBBA � (A BBBK L � �S��d F�I�E �A(�D0�] (D BBBH � (A BBBH L � �T��T F�I�E �A(�D0�K (D BBBB � (A BBBH L H �U��T F�I�E �A(�D0�K (D BBBB � (A BBBH L � W��B F�I�G �D(�G0s (A ABBF � (A ABBF H � X��* B�E�E �E(�A0�D8�JP 8D0A(B BBBI 0 4 �Z��� F�D�D �G0h AABG 4 h t[��g F�D�D �` DGG aCB 4 � �[��w F�D�D �` DJL iCB 0 � �[��� F�D�D �G0k AABD @ �\��� F�B�E �A(�D0�G@� 0D(A BBBE @ P ^��� F�B�E �A(�D0�G@� 0D(A BBBF ` � �_��� F�B�B �D(�D0�� (D BBBB D (A EBBB � (A BBBC @ � a��� F�B�E �A(�D0�G@� 0D(A BBBD H < �b��� F�E�E �B(�A0�D8�GP 8D0A(B BBBE H � l��� F�B�B �B(�D0�D8�G`� 8D0A(B BBBH H � �q��k B�B�B �E(�A0�A8�J�� 8A0A(B BBBF p �v��= B�B�E �B(�A0�D8�G`�hIpUhB`p 8D0A(B BBBK hFpXhB`� hQpa ( � �~��E F�D�G0� ABE H � ���� F�B�B �B(�D0�D8�G�� 8D0A(B BBBJ H ���� F�B�G �E(�A0�D8�GP� 8D0A(B BBBD $ X ����1 F�A�G \DB H � ����� F�B�B �E(�A0�D8�I@e 8D0A(B BBBA $ � ���1 F�A�G \DB L � ���� F�B�B �B(�A0�� (E BBBF � (E BBBA L D ����� F�B�B �B(�A0�� (E BBBF � (E BBBA ` � X���+ F�B�B �B(�A0�� (E BBBD i (E BBBD � (E BBBA L � $���? F�B�B �B(�A0�� (E BBBJ � (E BBBI @ H ���� F�B�B �A(�A0�G@3 0D(A BBBG H � `���] F�B�B �E(�D0�D8�G�� 8D0A(B BBBB H � t���� F�E�B �E(�A0�D8�DP� 8D0A(B BBBB H $ Ȓ��� F�E�B �B(�A0�D8�GP� 8D0A(B BBBH T p <���� F�B�B �E(�A0�D8�GP� 8D0A(B BBBG �XS`JXAPl � ����\ F�B�B �E(�A0�D8�G`"hRpBxB�T`| 8D0A(B BBBH Y hJpBxB�I 8 8 ����� F�B�D �D(�D@� (D ABBE X t ���� F�E�B �B(�A0�D8�D`� 8D0A(B BBBD phSpJhA` T � ����� B�B�E �B(�D0�D8�L`� 8D0A(B BBBG �hSpJhA` ( �d E�~ E [ ( H D���_ E�A�G @ AAA D t x���J F�A�A �J(P0M(B ` ABD D(Q0L(A � ���� ��� 8 � d���� F�B�A �A(�G@� (A ABBD < ���� F�B�B �A(�A0�� (A BBBA 8 T ����, F�B�A �A(�G0� (A ABBD 8 � |���, F�B�A �A(�G0� (A ABBD \ � p���# B�B�E �B(�A0�D8�I�� 8D0A(B BBBJ �H�Z�O� , @��� d @ <���� F�B�E �E(�A0�D8�Dp� 8D0A(B BBBH � 8L0A(B BBBK 8 � ��� F�N�P �H(�O0�(G BBB 0 � ���N ] t G I G I G I G � H ���h F�G�E �E(�H0�D8�Gp+ 8D0A(B BBBF , d ���� E�D�J d(N0iAAH l � H�� B�M�K �L(�D0�A8�GxY�FxAp� 8G0A(B BBBE ` 8D0A(B BBBC m��� p������ H $ 8��� F�B�B �B(�A0�A8�G@� 8A0A(B BBBI 8 p ���� F�B�A �A(�G0� (A ABBC ` � ���O F�B�B �B(�A0�A8�G@qHYP^HB@� 8A0A(B BBBH DHMPVHA@ n��� @������ p= 0= � � �? � Д � � �i �\ �d @� 0 �1 @ � �� � p� �� � 0 �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� @� $ �& @ � �� � p� �� � 0 �� � `� � ` �Q @ @ � p� �� �* � � ! p" �� �� �Q �� � � 0 �j � �� ���o � � � �� 0 8 ( ���o ���o � ���o �o � ���o Q �� 00 @0 P0 `0 p0 �0 �0 �0 �0 �0 �0 �0 �0 1 1 1 01 @1 P1 `1 p1 �1 �1 �1 �1 �1 �1 �1 �1 2 2 2 02 @2 P2 `2 p2 �2 �2 �2 �2 �2 �2 �2 �2 3 3 3 03 @3 P3 `3 p3 �3 �3 �3 �3 �3 �3 �3 �3 4 4 4 04 @4 P4 `4 p4 �4 �4 �4 �4 �4 �4 �4 �4 5 5 5 05 @5 P5 `5 p5 �5 �5 �5 �5 �5 �5 �5 �5 6 6 6 06 @6 @9 GCC: (GNU) 11.4.1 20231218 (Red Hat 11.4.1-3) AV:4g1231 RV:running gcc 11.4.1 20231218 BV:annobin gcc 11.4.1 20231218 GW:0x3d1056a lto SP:3 SC:-1 lto CF:8 lto FL:-2 lto GA:1 PI:2 SE:0 GA$3a1 �< �< GA$3a1 0 0 GA$3a1 �j �j GA$3a1 �< y= GA$3a1 �j �j GA$3a1 �j �j GA$3a1 0 0 GA$3a1 �j �j < �= )� p< < �� �� � �< 2 � � � � �= L �� *� 7� K C D� u q P� �= � U� � � �= � Uv c� �= h� � � �= � � Uv T| Q0 > � Uv T| v� > v {� � � > � [ Uv T| Q0 *> � Uv T| �� 3> � �� � � F> � � Uv T| Q> � Uv T| �� b> � 5 �� � � �� � � �� �� � � �> � Uv *� �> �] 7� �= � u Uv �= � Uv Q0 (� � � D� `� w� ԑ �� �> � �� �� , $ �� V N �� � x �� � � �� � � �� � � �� ? � ] Uv T Q| R~ X Y0 Q? � � Uv T Q| R~ X$ r? � U p � 4� �? 6 �� D� � & Q� a Y ^� � j� ��v� E % �� ���� � �� ,A �� A �� d@ 4� , � 9� f� P � g� 7 3 t� �Q � U~ T} �@ � T8 F� R F � K� O M X� IR � U~ T} `� ` / a� � \ m� ��P� � T U� b� 7 1 uA � TG o� �O P � t� V T �� g c �O � U��~T � � � � � � )� � � �� �J �J . 9 �� � � �� � � �� � � �J ځ Uv T} Q| (C � P T: EC � h T| pC � U~ Q} R| V� HK P � [� � � h� tK � U��~T 6� �O P ) ;� 1 / H� B > $P � U��~T v� `P X o w� d b �� �P � U T~ z� � � � q �� 6 1 �� � � �� � � �� S S % �� $ " �� ; 9 �� K I S ځ Q �� f X �� ^ Z �� x t �W � U��~T�� �� v � �� � � �� � � X � U��~T�� �� � � �� � � �� � � �[ � U��~T�� H � � TM 5H � T � ^M � U~ R �� � � �� ���� � � �� ���� !D � % �� " �� �Z e � �� 5 1 � O K )[ � U��~T�� �� xN xN % 6 �� q o �� � � �� � � �N ځ U 2� � | 3� � � @� � � dX � U��~T�� D � � TN FD � � U~ R4 qD � U~ �� �V Z �� � � �� ,W � U��~T�� � �Z e i � * & $� D @ �Z � U��~T�� �\ � U �s {� � �� ���� �D � �� �� �D � TH �� �U F �� f d �� �U � U T| �� BZ Q ^ �� u s �� lZ � U T| B� � C� ��p� R � u� ���� �I i . �� � � �� �T Q � �� � � �� �T � U T| �� �J �J . ] �� � � �� � � �� � � �J ځ Uv T} �� y � �� � � �� ;Q � U~ T| �F � � T1 G � � U~ R4 HG � U~ Q} P� �T F , U� � � b� U � U T| �� �Y Q r �� � � �� Z � U T| �� � �� �� �� kE � . � �� �� yE � . � �� �� �L �L . �� # ! �� 3 1 �� E C �� NU Q a �� V T �� xU � U T| �� 6J 6J . � �� e c �� u s �� � � �� K K . �� � � �� � � �� � � K ځ Uv T} "� � Q '� � � 4� �P � U~ T| EB � { U~ T| Q��R2 �C � � U| TV (E � � T! KE � � T1 �E � � U~ R8 �E � U~ Q} sG � T! �G � TH �� �S F u �� � � �� �S � U T| �� KT F � �� � � �� uT � U T| �� �U F �� � � �� "V � U T| �� QV F G �� �� {V � U T| � �V Q � � � �V � U T| � � i � �� �� �N �N � �� # ! �� 3 1 �� E C �B � T7 �B � , U~ Q��R8 �H � I T| Q2 @K � U~ T| Q2 #� �X F � (� V T 5� �X � U T| C� �X Q � D� e c Q� Y � U~ T| �� � �� �� �� (F % � 3 �� t r HF � J T9 sF � n U~ Q��R4 1T � U~ T| Q2 �� �[ Q � �� � � �� �[ � U} T| �� \ F �� � � �� H\ � U} T| �� �I P ` �� � � �� �I � U} T| �� 5 � �� � � �� �M � T| �� O O � � �� � � �� � � �� � � � E � � � &� �Q � T| �� U J �� � � �R � T| �� GY Q � �� � qY � U~ T| �� �Y F � �� �� �Y � U T| �? � d@ � U~ T| Q2 �H � T6 �H � A U~ Q��R8 `J � d U~ T| Q2 |\ � �\ � � T| Q0 �\ � U p Q| l� f� �� �� ݒ ΐ 0� � *� 0� �\ � @� > , M� � � Z� � � f� � � r� / # � o e �� � � �� �� �� ���� � � �� �\ e � � w o � � � � � � �� 9 1 �� h ^ e (� � � 4� @� W O L� � z Y� � 5 ^� � � �c C Uv �� �] � ^ �� � � �� �] � �� � � �\ � Uv T �s Q0 ] � Uv ] � Uv ] % � Uv T~ %] * Uv {] / : Uv T} Q3 �] 4 R Uv �` 9 j Uv �c > � Uv T| Q| R1 �d � U Hp � � � � ��� � � ���� F_ F_ �� � � "� �c ` ] #� � � 0� � d � U��T ?� � � @� " M� 3 / |d � U��T j_ � Uv R4 �� 9` 9` $ # �� U S �� f d �� u s G` ځ U} T| �� �` �` & � �� � � �� � � �� � � �` ځ Uv T~ \� �a X � a� � � n� � � �a � U��T �� � ! �� � � �� b � U��T�� �� � g �� . * �� H D {b � U��T�� |� � �� n l �� { �b � U��T �� c P � �� � � �� Bc � U T} �� + �� � � �� �c � U} T| 8^ � C T Z^ � ^ T � �^ � �^ � � Uv Q| �^ � �^ � � Uv Q~ �_ � � Uv T} Q��R2 �_ � Uv T| Q��R2 �d � �� �� t� X� �� �� ֎ � � A� �� �d � �I# �� � � » P H ϻ � v ۻ � ��~ <� ?e * , W� ^ \ K� v t fe � U} T1QPR t Yv �� = � �� � � � � � �� �f s 1 p �� �� ; 5 �� ] W �e � � T: �e � � Tv �e � U| Q} Rv T� �g X ! U� � b� �g � U T~ � `h X V! � � � &� � � �h � U��~T 4� �h X �! 9� � � F� � � �h � U��~T �� �f � R" � � � L B �� h h 7" � y w � � � h X# U| T} Q0 ;i ]# U| T} e � u" U| Tv Q0 2e I# �" U �s Qv ?e � �" U| Tv Q0 ne N# �" U} �f S# �" T �s Q1 Kh � # U| Tv Q0 \h � ;# U �s �i � � � �� ߏ �� �� �i �O2 �� � � �� � �� m ? �� Y 3 �� ���� � �� N F �� � r � � � � � $ � �q C Uv #� � L$ (� ) % r C Uv V� � �$ [� E ? h� h b l � TG u� �v ` �$ z� � � �� � � �v � U��T �� �l � � �% � � � � �� �o �o h% � F D � U S �o X# Uv T} Q0 �v ]# Uv T} � , �& "� h b /� � � �� �r �r � & �� �� � � �� � � s ځ Qs m � & T: Am � 3& Ts �m � Q& Uv Rs Rr � y& Uv T} Q0R2 t � Uv T} Q0R2 \� hr ` �& a� � � n� � � �r � U��T |� t h >' }� ! ! �� ! ! Ot � U��T <� w ` �' A� <! :! N� M! I! >w � U��T �� S 7( �� �� �� �n m � �' �� q! m! �� �n } � �' �� �� �v �v � �� �! �! �� �! �! �� �! �! �� �{ ` }( �� �! �! �� �{ � U T~ 6� �o P �( ;� �! �! H� p � U T~ H� � �* I� ��v� � ) {� ���� �t � � �� �! �! �� z ` Z) �� �! �! �� Lz � U T~ �� �u �u � �) �� �� �! �! �� " " �u ځ Q~ �� � �) �� " " �� x � U T~ Wp � * T1 �p � "* Uv R4 7q � @* Uv R~ "u � h* Uv T} Q0R2 �w � Uv T} Q0R2 V� �x K �* [� 2" 0" h� �x � U T~ �� >| W + �� A" ?" �� j| � U T~ �� f+ �� ���� �p R+ �� �� �p � TH �� �z K �+ �� P" N" �� { � U T~ �� �| W �+ �� _" ]" �� �| � U T~ �� �t �t � @, �� n" l" �� ~" |" �� �" �" �� �u �u � �, �� �� �" �" �� �" �" �u ځ Q~ (� $ �, -� �" �" :� mx � U T~ �� y K - �� �" �" �� ,y � U T~ �� `y K `- �� �" �" �� �y � U T~ �� �y K �- �� �" �" � �y � U T~ �� �z K �- �� # # �� �z � U T~ � @{ ` 2. � # # � l{ � U T~ j O2 Y. Uv a �*��Q� ��? &j T2 |. Uv T Q: 8j Y2 �. U2Q} Dj �. Uv Lj �. Uv �j ^2 �. Uv T Q:R@?$ �j c2 / Uv T =t Q2 %k % ;/ Uv T~ 0k * S/ Uv Lk c2 }/ Uv T At Q2 �k N# �/ U~ �k � �/ TJ *l � �/ Uv T} Q0R2 2l N# gl � 0 Uv T} Q0R2 �l S# -0 T t Q1 m H T0 U�UT�TQ�Q �m 4 l0 Uv n � �0 T! Dn � �0 T1 pn � �0 T! �n � �0 TH �n � �0 Uv R8 'o � 1 Uv R~ Ho 9 1 Uv �q > F1 Uv T} Q} R1 �q > o1 Uv T} Q} R1 +r > �1 Uv T Q R1 Ju � �1 Uv T} Q0R2 �w � �1 Uv T} Q0R2 } � 2 U �p } � } � 32 U xp 6} � U �p �� �� |� V� 5� E� @} � ��3 R� *# $# _� K# I# l� [# Y# y� 4 �3 z� l# h# �� �# �# e� �} H �3 �� �# �# �� �# �# t� �# �# �} �3 23 Uv T / �} �3 P3 Uv Ts �} �3 Uv Ts Q0R~X � Y0 t} � �3 Uv Q Nt R>X0Y0 ~ �3 Uv T} Q| �� �� K� /� '� 0~ � ��5 4� �# �# A� �# �# N� G~ �4 S� $ $ W~ � k4 Uv T| b~ � Uv T| a� s~ �4 f� $$ "$ �~ � �4 Uv T| �~ � Uv T| t� �~ I5 y� 3$ 1$ �~ � .5 Uv T| Q0 �~ � Uv T| �� �~ �5 �� B$ @$ �~ � �5 Uv T| Q0 �~ � Uv T| *� �~ X >7� Q$ O$ �� u �V6 � f$ ^$ � �$ �$ *� [ [ ) V ;6 7� �$ �$ � 1 � �3 �� � � ��7 �� �$ �$ �� �$ �$ �� % % �� k v7 �� .% *% �� F% B% e� � � h7 �� ]% [% �� o% m% t� % }% � �3 7 Uv T / � �3 >7 Uv T| � �3 Uv T| Q0R~X � Y0 �� � �� �% �% i� � �7 Uv Q Nt R>X0Y0 ~� �3 Uv �� �� } ��9 �� �% �% �� �% �% �� .& "& �� s& e& �� �& �& �� �& �& �� �& �& �� 0� � 3 r9 �� �& �& �� &' "' �� A' =' �� \' X' � �� w' s' �� �' �' �� �' �' n� �9 �8 U} Tv Q R0 �� �9 9 U} T}�QB �� N# ,9 U| �� � \9 U} T~ Q| X$Y � % U} � N# �9 U| � � U} T~ Q| X Y0 ɋ �� �� � K �z< �� �' �' �� �' �' �� 2( .( �� U( I( �� �( �( � �( �( � ) �( #� �) �) 0� �) �) <� � : A� * * � C Uv O� � 2; T� ,* &* a� Q* I* n� �* w* '� % �: Uv 2� * �: Uv �� > ; Uv T| Q| R1 S� > Uv T} Q} R1 �� g� g� g f; �� �* �* ?� ~; Uv G� �; Uv �� z< �; Uv T| $ & �� * �; Uv T� / �; Uv T��Q��� �� 4 < Uv ȃ 9 +< Uv � > T< Uv T~ Q~ R1 #� > Uv T} Q} R1 B� � `� � �jA � �* �* )� �+ �+ 6� , �+ B� �, �, O� \� #- - i� Q- A- v� �� ~� � �? �� ��к �= պ �@ �� � �M= �� �- �- �� %� / �m= �� �� �� �� ��= �� �- �- �� �- �- �� �- �- D� � U} Q�@R8 � H� X !> � �- �- � r� � U} Ts � ? �> � �� �� �� �� �k> �� �- �- �� � �> T0 �� � U} Q��R4 -� �� P �> 2� �- �- ?� � Us T~ M� � X /? N� . . [� � � Us T} �� ؈ ؈ �}? �� . . �� ). '. �� ;. 9. ݄ � �? T! �� � �? T0 �� � U} Q��R8 �� � P @ �� L. J. �� � � Us T~ �� 8� P Y@ �� [. Y. º b� � Us T~ �� �� Q �@ � j. h. � ʉ � U~ Ts k� \ �@ l� {. w. �� tA U�UT�TQ�Q �� jA A U} T~ Q| �� oA %A U} T~ Q| Ɔ 9A U| � \A U�UT�TQ�Q �� � �� K� ɽ �� �' ��a ٽ �. �. � �. �. � ?0 �/ �� �1 �1 � 2 �1 � �2 �2 &� �2 �2 3� �� @� ��m� � .B r� a3 [3 �� � Ts � � � N ~B �� �3 ~3 �� �3 �3 >� � U��~T~ 8� � �B =� �3 �3 @� � Ts � J� � V C K� �3 �3 X� �3 �3 � � U��~T��~ g� � �C l� 4 4 �� � WC �� ���� � � �� i4 g4 �� +� Y �C �� z4 x4 �� �4 �4 V� � U��~T| ˸ � �C T� � � Uv R4 y� Q� N )D ~� �4 �4 �� �4 �4 |� � U��~T| ƿ �� Y yD ǿ �4 �4 Կ �4 �4 �� � U��~T| � �� $ ��] P� 5 5 C� r5 N5 6� 36 6 *� �6 �6 � 7 �6 � �7 �7 $ ]� ��j� D8 68 w� ���� �8 �8 �� �8 �8 �� M9 ?9 �� �9 �9 �� %: �9 � !; ; � e; M; � < �; � = = �� ��� w= s= � �= �= � > �= )� �> p> 6� :? �> C� �� K� � �� d 9 /H ;� �@ �@ .� �@ �@ !� �@ �@ � �@ �@ d H� BA A T� OB GB a� �B wB m� �B �B x� �F }� C C �� C Uv �� � �F �� KC ;C ^� 7w Uv T; �� � )G �� �C �C �� �� �� � G �� �C �C ̱ Fw Uv T �� AG Uv �� YG Uv � z< �G Uv T ��~� $ & +� * �G Uv G� / �G Uv T~ Q3 � 4 �G Uv غ 9 �G Uv �� > H Uv Ts Qs R1 �� > Uv R1 �� � � :�H �� �C �C �� �C �C �� � �� �C �C �� � Uv T��~ e� � I j� D D �� �9 �H Uv T| Q �t R0 D� � U Hr T��~ w� � �L |� `D <D �� �D �D �� /E #E �� dE `E �� �E zE �� � � �I �� �E �E �� �E �E �� �� F F �� � Uv T| �� A� . � �I �� 7F 5F =� `� ` 3J B� HF DF O� bF ^F �� � U��~T�� � �� ` �J � �F �F � �F �F � � U��~T�� �� � f �J � �F �F � �F �F N� � U��~T�� �� H� ` )K � G �F � G G v� � U��~T�� � �� W {K "� @G <G /� ZG VG �� � U��~T�� i� jA �K Uv Q~ �� � �K T! ҳ � �K TC �� � �K T ��~�8$8& � < L Uv T} Q~ 5� jA +L Uv Q~ k� Fw QL Uv T��~R~ /� � rL T ��~�8$8& � � �L T��~�� s� � �L U �r T��~�Q��~ �� � U s T��~�Q��~ Q� .� .� { V �M �� |G zG x� �G �G k� �G �G ^� �G �G �� �G �G }� �9 xM Uv Tv�QB �� N# �M U~ �� � Uv T��~Q~ X$Ys � > LN #� �� �� � � : N �� �G �G .� � Q /� �G �G <� ;� � U~ T} 6� U ;O ;� �� �� Q� o L �N �� �G �G �� l� L �N �� �� �� �� L �N �� H H �� "H H �� 4H 2H H� �� Q I� EH CH V� � � U~ T} �� � �O �� XH RH �� �� S �O �� wH uH � �H �H �� � U��~T~ ]� � T| � W� � NP X� �H �H d� � P e� �H �H )� � U 8s T| � � 3P U��~T| 6� < Uv T �� � �P �� �� �� �� � A �P �� �H �H �� b� Q �� �H �H �� �� � U~ T} �� � QQ �� �H �H �� �� S 9Q �� I I � 'I #I �� � U��~T~ � � T| � �� HR �� ���� 3 �Q �� �� �� � � R �Q �� II GI �� � Q �� XI VI �� D� � U~ T} �� J .R �� gI eI �� �� � U~ T} J� � Uv R4 0� Z sV 5� �I tI B� � YS G� ��T� � �R Y� �� �� �� � `�R �� �I �I d� �� Q e� �I �I r� �� � U} T| �� � Q ?S �� �I �I �� .� � U} T| �� � Uv R4 +� � T ,� �� �� �� �� { �S �� J J 9� � �S :� J J G� 8J 4J �� � U��~T��~ �� � Uv Q��~R4 �� � �U �� ���� @U �� �� �� 7� / u_T �� `J \J �� D� D� u�T �� �� 8� 8� u�T �� vJ tJ �� �J �J �� �J �J �� ? U �� �J �J �� �J �J #� � U��~T��~ k� � Uv Q��R8 �� h� h� u�U �� �J �J �� �J �J �� K K � O �U � K K � :K 6K �� � U��~T��~ �� � Uv Q��~R8 �� _ �� dK ^K �� �� K ZV �� �K �K �� �K �K !� � U~ T} �� � T| � k� v �V p� �K �K }� �� S �V ~� �K �K �� �K �K �� � U��~T~ 7� � T| � �� �� �� L CW �� L L �� -L +L �� ?L =L �� /� /� F �W �� PL NL �� jL hL �� {L yL ?� ځ U| T��~ �� h� h� X X �� �L �L �� �L �L �� �L �L x� ځ U| T�� �� �� N gX � �L �L � �L �L �� � U��~T~ �� �� N �X �� �L �L �� M �L � � U��~T~ � � �X � %M #M "� �� � U~ T} � � +Y � 4M 2M (� �� � U~ T} �� �� N {Y �� CM AM �� TM PM � � U��~T~ ~� � S �Y �� vM tM �� �M �M B� � U��~T~ e� ;� Y Z j� �M �M w� e� � U~ T| �� � UZ �� �M �M �� �M �M �� � U��~T~ K� �� Q �Z P� �M �M ]� �� � U~ T} �� k� Q �Z �� N N �� �� � U~ T} ί � [ U �q T} �� N# [ U��~ �� % @[ Uv T��~ �� � l[ Uv T Q��~X| 4� � �[ T! W� � �[ TC x� � �[ Ts � �� � �[ T��~�� � � �[ Uv Ts � � \ Uv Ts � � ;\ Uv Q��~X Y0 �� tA m\ Uv T Q��~R} X| �� � �\ Uv Q��R2 �� � �\ Ts � � � �\ Uv �� � �\ Uv R8 �� � ] Uv Q�� � � ] Uv Ts �� � =] Uv Ts �� � Z] Uv R4 � � z] Uv Q��~ �� � �] U �r �� � U r Q��~ �� � �^ �� N N ξ � C^ Ӿ �� �� W� W� � "^ �� iN gN �� � Uv Q��R4 �� Q �^ ߾ yN wN � �� � U~ T| ;� � �^ T� Y� � Uv Q| R4 �� �� N _ �� �N �N �� �N �N � � U��~T~ �� ;� Q W_ �� �N �N � e� � U~ T| �� �� �� � �_ �� �N �N �� �N �N �� �N �N �� ځ U| T~ � �� N ` � O O *� O O �� � U��~T| M� 5� N _` R� 7O 5O _� HO DO `� � U��~T~ � �` � jO hO � {O wO �� � U��~Ts �� �7 �` Uv Q| R �t F� N# �` U~ `� � a Uv T Q~ X| �� � 'a TB ֮ Ia Uv T Q��~ � � `a TA h� � ~a Uv Q~ �� � �� � � �Lc �� �O �O �� �O �O � )P !P � NP LP � cP [P ,� l �b 1� �P �P >� � Fb C� �P �P P� �P �P x� � U��T �� Lc ib Uv T~ Q0 �� � T} ���� �)�3$# {� �� X �b |� Q Q �� #Q Q � � U��T � � c TK4} ���� �)( L� < 0c Uv Ts Q| Ԍ � U Hq � y� � � � i �� KQ CQ �� yQ qQ �� �Q �Q �� �Q �Q �� ���� R R �� JR HR �� [R WR .� � yd 3� �� �� �� � S d �� vR rR �� �� � S .d �� �� �� �� S �� �R �R �� �R �R �� �R �R @� �� [ �d A� �R �R N� �R �R ē � U��T~ }� � �e �� ���� � e �� ���� &� ] �� �R �R �� � [ je �� S S �� S S � � U��T~ � � �e T2 K� � Us R4 �� w� P �e �� 6S 4S �� GS CS �� � U��T~ �� N� [ ;f �� iS gS �� zS vS z� � U��T~ �� 7� 7� S �f �� �S �S �� �S �S �� �S �S � �f � �S �S %� �S �S S� � U��T�� �� ) g �� T T � -T )T �� � U��T�� � � P eg � ST QT � dT `T @� � U��T~ �� ڒ P �g �� �T �T � �T �T � � U��T~ ]� =� [ h b� �T �T o� �T �T i� � U��T~ � i #h Us Tv I� � ;h T! l� � Rh T2 �� � oh Us R8 #� < �h Us T F� i �h Us Tv Q~ R0 v� � �h TO �� � �h T> �� � Ĕ � U Hq v� Q� �� Д I �(w �� �T �T �� >U U �� �U �U �� ��� V �U � �V �V � W W +� 9W -W 8� �W xW E� X �W R� XX DX _� ӛ 7� 9 �j <� ���� � j �� ���� /� � � �� �X �X �� � R aj �� �X �X �� H� � U T~ ˕ � xj TI � � �j T��~�� � � �j T3 T� � U| R4 g� p� H k l� �X �X y� �� � U T~ �� ֣ R Sk �� �X �X �� � � U T~ G� (� H �k L� �X �X Y� R� � U T~ �� դ G �k �� Y Y �� � � U~ T �� � q �� "Y Y &� � �o '� AY 7Y 4� Y mY A� �Y �Y N� �� [� ��h� )Z Z u� gZ aZ �� �Z �Z �� � �l �� ���� �� � �� �Z �Z �� f� f �l �� �Z �Z �� �Z �Z �� � U��~T�� �� >m �� �Z �Z �� ��ٟ _w U~ T��Q��R0 �� Р Р � �m �� [ [ �� ,[ *[ �� ;[ 9[ ޠ ځ U T~ �� . �m �� N[ J[ �� f[ b[ 9� � U��~T � > 0n � �[ �[ )� �[ �[ d� � U��~T�� � � Mn U| R4 � � kn U| Q~ [� Pw �n U| Tv j� Uw �n U| T��~ �� Zw �n U| Tv Q R0X0Y0 �� < o U| T} Q~ 1� � o Ts � �� � Eo U| T Q��R2 � Uw eo U| T��~ 0� Zw �o U| Tv Q R0X0Y0 X� dw U~ �� ̡ f �o � �[ �[ � �[ �[ �� � U��~T�� � N 3p � \ \ � 7w U| T; � a �p � !\ \ P� � pp U| Tv Q1 [� Aw �p U| p� Fw U| T~ Qs 4� <w �p U| T~ �� Kw �p U| �� � �p U| Ts �� � U| Ts �� q �q �� �� �� � � � Vq �� 2\ .\ �� �� � � vq �� �� �� �� � �� H\ F\ �� X\ V\ �� j\ h\ �� �� W r �� }\ y\ � �� � U T��~ �� (� � � 0s � � �\ �\ �� �\ �\ �� �\ �\ � $� ] �\ 1� D] >] <� d] `] H� �] |] U� �] �] b� p� Q s c� �] �] p� � q� �] �] �� (w �r U| Tv Q !�� U| T} Ys � � U Hq 9� � �s >� ^ ^ J� %^ #^ � (w {s U| Tv Q~ +� �s U| T} Y R� � U| Tv Q1 �� � � � t �� 4^ 2^ �� D^ B^ �� V^ T^ h� � Mt m� g^ e^ z� x^ t^ � � U��~T �� ̜ * �t � �^ �^ � �^ �^ �� �� �� �t � _ _ � _ _ �� X# U| T~ Q0 �� ]# U| T~ �� * ;u �� -_ +_ �� >_ :_ �� � U T~ �� : }u �� b_ `_ �� s_ o_ �� � U T~ �� J �u �� �_ �_ �� �_ �_ f� � U T~ � � W v � �_ �_ )� � � U T��~ V� � v T! ~� � 6v TI �� � Qv Ts � ϖ � hv T3 � � �v U| R8 ǘ � �v U| Tv � -w �v U| Tv Q��� � 2w �v U| Tv Q��~ ɜ S# w U| T ]t Q1 � � ʌ �� �� � � �� ٍ �� v� Z� � � � ]� � � ��y m� �_ �_ z� \` 0` �� +a a �� �a �a �� b �a "�� �� :b "b �� �b �b � �� P +x � �b �b !� � � U T~ �� (� P qx �� c c �� R� � U T~ �� x� J �x �� c c � �� � U T~ g� � �x T= }� � �x U| Tq �� < y U�UT�T ç � #y T; ٧ � Ay U| TP �� � `y U �q � � wy T< %� � �y U| TP � �3 U} T0 u� � � ��| �� :c c �� �c �c �� d d �� 3d d �� �d �d �� Z ({ �� ��� r �z � �� �� +� +� � kz �� �d �d R� � U} Q��R4 "� � X �z #� �d �d 0� � � U~ T} �� � �z TF � < { U} Tv %� � U} Q��R4 �� �� P n{ �� �d �d � �� � U T~ ?� 8� Q �{ @� e e M� b� � U~ T} �� �� P �{ �� e e �� � � U T~ %� � | U�QTp R� � 0| TE m� < N| U} Tv �� < n| U�UT�T �� � �| U �q �� � #߸ ��� � ;e !e �� �e �e � 8f .f � f gf � g �f -� �g �g :� oh mh G� �h |h T� �h �h �� � ( � �� i i �� *i &i �� Mi Ei �� zi vi �� �i �i �� @ �} �� �i �i � 7w Uv T< � P �} � j j �� 7w Uv T< � ` ~ � j j �� 7w Uv T; f� �� .~ Uv �� S# Q~ Uv T| Q1 �� S# t~ Uv T| Q1 �� � �~ Uv Q2 � S# �~ Uv T| Q1 4� S# �~ Uv T| Q1 D� � �~ Uv Q2 U� S# m� S# b� T� p �� � ,j "j r� aj Wj p �� �j �j �� �j �j �� � � ~� �� k k �� ?k 7k �� ik ck �� � � �� �k �k ι �k �k T� � U��T�� �� � Uv R| �� �� � ��� �� �k �k � ĸ �k �k Ѹ l l �� � z� Uv Q R>X0Y0 � �� Uv �� � �� Uv Q R>X0Y0 �� �5 ܀ Uv T~ �� < � Uv T~ Qs �� 1 � Uv T~ �� V6 <� Uv T~ �� P� Uv 2� �� i� U �� � U �t � �� �� � � -� � $b� ځ �� �t �� �t � � %� � � � � � .q o� �� k �� � 7l /l �� _l [l �� zl vl � � � U Px X2Y; � � U �x �� � c �� Ш �l �l ݨ �l �l � m m �� Bm 6m � wm qm �� W� W� �F �� �m �m "� � b #� �m �m �� � �� �� �m �m �� �m �m �� �� n �m [� � U} T~ �� n� n� � �� �� )n 'n �� � U} T| �� � A U} Tv Q0 � � U} T~ Qv <� � U} T0 T� � � U} Tv Q1 }� � U} R| �� � ٍ �� � ͊ ԑ R� �� d �� b� Dn 6n o� �n �n |� �n �n �� �n �n �� Do >o �� . X �� fo `o �� �� N �� �� �o �o �� �o �o �� N �� �o �o �� � U} T| �� �� �� �� �� �� �o �o #� � U} T~ m� � 7 U} Tv Q0 �� � U} T| Qv �� � { U} Tv Q1 �� � U} R~ � � T �L � p �o � Up Ip � �p �p � �p �p '� q q 4� d 5� 1q +q �� �� � �s �� Qq Mq �� mq eq �� � �� �q �q +� � U} T| �� ?� ?� �� �� �� �q �q {� � � U} T~ �� � � U} Tv Q0 �� � U} T| Qv .� � 1 U} Tv Q1 L� � U} R~ v� `� T � �� �q �q �� r r �� [r Sr �� �r }r �� �r �r Ƨ � � ǧ �r �r �� P� � �) �� s s �� 8s 0s �� � �� ds \s �� � U} T| �� �� �� �b �� �� �s �s �� � � U} T~ %� � � U} Tv Q0 B� � U} T| Qv �� � � U} Tv Q1 �� � U} R~ !� �� B �{ 1� �s �s >� �s �s K� t t X� � ` Y� Wt Qt �� �� � � �� wt st �� �t �t �� � �� �t �t �� � Uv T} �� �� �� � �� �� �t �t +� � Uv T} x� � ? Uv T| Q0 �� � Uv T} Q| �� � Uv R} �� � * �� � �t �t � u u � Iu Au ,� su ou 9� �u �u F� �u �u R� �u �u �� T� T� % �� v v q� E r� 'v v �� � ' � �� Qv Kv �� tv pv �� ' �� �v �v � � U} T�� �� � � � �� �� �v �v �� � � U} T| �� � " U} T Q0 � � U} T��Q �� h� h� %� �� �v �v �� �v �v �� �v �v u� � Qv 9� � � U} Tv Q� � � U} T~ Q1 z� � U} R| �� � $ U} Rv O� � L U} T| Q0R0 f� � d U} �� � � U} T �x �� � U} T| Q0RtX0Y0 E� |� `� d� �� �� @� � �� �� �v �v ͭ 1w )w ڭ aw Uw � �T �� �� �� [P �� �w �w �� � s U| Q�TR4 �� { � U| Tv R0Xs �� �� k� � g �/ {� �w �w �� �w �w �� ,x x �� cx _x "� / >� { U�UT�TR0X�Q � &� p� w �� 6� �x wx C� �x �x P� y �x ]� 7y 3y �� / �� { U�UT�TR1X�Q � �� � �� � Wy Ky �� �y �y � �y �y � �T �� A� A� �7 �� �y �y 0� � Z U| Q�TR4 \� { � U| Tv R1Xs �� �� �� �� � �� �� z z �� Qz Iz ǫ �z wz ԫ �z �z � �z �z � �@ �� '� '� �) �� �z �z � < E � { { �� A� R �� �� { { �� ,{ *{ �� R �� A{ 9{ c� � Uv T~ �� v� v� �� �� �� d{ b{ �� � Uv T| � � $ Uv T} Q0 5� � Uv T~ Q} �� � h Uv Q�@R8 � � � Uv $� � � Uv T} Q1 M� � � Uv R| �� �� B� f� �� � �; v� }{ q{ �� �{ �{ �� �{ �{ �� &| | �� E| A| �� �D �� �� b ` a �� ]| [| �� � � g� �� m| k| Ԫ r � ժ ~| z| �� � � g �� �| �| �� �| �| �� � �� �| �| ;� � U} T~ �� N� N� gO �� �� �| �| �� � m U} T| �� � � U} Tv Q0 � � U} T~ Qv �� � � U} Q�DR4 �� � � U} � � U} Tv Q1 4� � - U} R| h� �� @� p� � �d P� �| �| ]� Q} A} j� �} �} w� �} �} �� ~ ~ �� :~ 6~ �� W~ U~ �� �� �� �� �� i~ g~ �� � �� |~ v~ �� �� � �f �� �~ �~ �� �~ �~ �� � �� �~ �~ �� � U| T~ �� �� �� �� �� �� �~ �~ S� � � U| T} �� � � U| Tv Q0 �� � U| T~ Qv �� / �� � & U| �� � I U| Tv Q1 �� � U| R} ک � � �� � �� R J � � x � � � � � � *� �@ �� �� �� � �� � � H� � I� � � �� �� � } �� � � �� -� +� �� � �� B� :� �� � Uv T~ �� �� �� � �� �� e� c� ;� � � Uv T| �� � � Uv T} Q0 �� � Uv T~ Q} f� � ; Uv Q�@R8 }� � S Uv �� � v Uv T} Q1 �� � � Uv R| � �� �� �� � � �%# �� z� r� �� �� �� �� � ɡ �� q� ա D� 8� � x� v� � �� �� �� �� �� � Ղ ł � '� � !� �� t� .� Ճ à ;� +� � �� L� L� �� �� n� l� Z� � � _� �� {� �� ^� � �� �� �� �� Ą �� �� �� � ڄ � � Uv T| �� x� x� �Y �� �� �� �� �� � w Uv T| -� � � Uv T~ Q0 P� � Uv T| Q~ �� -� * �" �� � � �� )� %� �� * �� E� ?� � � Uv T| �� y� < � � � m� a� � �� �� �� � � " � � ߅ ݅ � � � � a# Uv T~ Q0 � f# Uv T~ �� �� g | � � �� � :� 0� �� 6� )� $ a � i� e� � �� }� ;� a# Uv T~ Q0 �� f# Uv T~ �� �� � �") � �� �� � �� � �� �� �� � 5� 3� � D� B� �� a# Uv T| Q0 �� f# Uv T| �� � � � ] �� S� Q� �� �� �� � �� b� `� �� �� � � �� s� o� �� �� �� �� � �� �� �� � � Uv T �� � � , �� LJ Ň �� � [ �� ڇ ԇ � p# Uv �� h� h� � � �� �� �� 1� � � Uv T~ I� � � Uv T Q1 r� � � Uv R| �� / �� � Uv Ts Q �� %# I Uv T 0u Q4 -� *# g Uv T �� /# Uv �� 4# � Uv �� 9# � Uv T Du Q1 �� � � Uv T~ Q0R0 �� ># Uv T Q2 �� � 1 U Fu Q| �� 4 U Uv Ts Q �� 9# Uv T �s Q1 � C# � Uv T QB *� � � Uv Q} R| W� � � Uv Ts Q w� � ! Uv Ts Q �� H# 6! Uv T| Q0R2 � M# N! Uv �� R# f! Uv �� C# �! Uv T QB � W# �! Uv (� \# �! Uv Q2 F� � �! U Xy d� 9# " Uv T 5u Q1 � � &" U y � k# S" Uv T��Q��R1 � � r" U �x 3� � �" U u \� � �" U �y n� H# �" Uv T Q0R2 �� H# # Uv T Q0R2 �� H# Uv T~ Q0R2 �� �� �� t� �� w� �� �� ֎ � �� �� ߏ �� � A� �� �� � �a) �� � � �� <� 4� �� z� b� �� � � ˠ ��ؠ � � � H� :� � �� �� �� ĉ �� � � � � =� � #� � ۊ 0� � �� �� � � 7 i$ �� !� � �� 8� 8� D�$ �� 4� 0� �� L� J� �� [� Y� D� � Q�� =� � �$ B� m� i� � p# Uv �� � _%% �� �� �� �� 6� aN% �� �� �� t� 1 j& u� �� �� �� � I a�% �� � �� �� �� �� I �� � � C� � Uv T~ �� V� V� a& �� �� 5� 3� �� � && Uv T} � � I& Uv T| Q0 �� � Uv T~ Q| �� L� L� =�& �� D� B� �� S� Q� �� b� `� U� � � /# �& Uv � 4# �& Uv � / /� � &' Uv Q��R4 Y� / z� � K' Uv �� W# c' Uv �� � {' Uv � / � � �' Uv T��1��0.( � W# �' Uv H� � �' Uv R�� � a) ( Uv T bu Q2 3� � 9( Uv T| Q1 \� � W( Uv R} *� M# o( Uv �� R# �( Uv �� k# �( Uv T} Q} R1 � k# �( Uv T}Q}R1 �� � �( Uv T| Q1 *� � ) Uv R0 w� �� �� � E) U uu �� � U �y Љ R� �� k �@- b� z� p� o� �� �� |� ��}�� � Ռ �� k� a� �� �� �� �� ͍ �� �� � � Ȟ 6� *� ՞ r� n� � �� �� � ^ �* � 4� *� � h� b� �� H z D v* �� �� �� �� �� �� �� �� �� �� � �* U} Q��}R5 ,� � �* U} Q��}R6 [� � U �u � � �+ � ͏ �� � � ��+ � � � � T� L� �� e � �{+ � z� x� � �� �� r a# U} T Q0 [ f# U} T ) � �+ U �y T~ Q| R2X; � 9# U} T �u Q1 �� � � �\, �� �� �� �� �� �� �� �� �� � � U��}R � / � / � �, U} Q��}R| � � �, U �u � �� � � �, U �u � � - U 0z � � $- U xz � � U Pz O� = ��3 _� �� ې l� b� Z� y� �� �� �� �� �� �� � � �� N� <� �� � �� � 7/ �� ��Ɲ . ˝ ��� � Uv Q��R4 ٝ 0 �. ڝ �� �� � �3 L. Uv Q��R8X Y0 �3 o. Uv Q| R0 = �3 �. Uv Q2 0 � �. U �z T| H � U �z � / � � �. Q��R8 � � / Uv � �3 Uv Q��R8X$ �� G 0 �� �� �� + + 6 �/ �� �� �� �� � a # �/ �� �� �� � � �/ Uv Q��R4 �3 �/ Uv R0 . � U �z � q c2 � ��&� ד ϓ �� W W e ^0 �� �� �� 3� � z1 4� � � �� \ � p �0 �� 8� 4� �� R� N� �� � �� p� h� I � Uv T �� � � p 1 �� �� �� �� � � 61 Uv T| - � Y1 Uv T~ Q0 P � Uv T Q~ �� � � m �1 �� �� �� �� �� �� �� ̔ ʔ � � > � �1 Uv Q} R4 * / Z �3 � � *2 Uv � �3 G2 Uv R1 ] � U v �� � ; 3 � � ۔ � 5� +� �� � � ��2 � b� `� � q� o� � a# Uv T| Q0 � f# Uv T| � / � 23 Uv Ts Q~ / � � n3 U �z R} X2Y; 9# �3 Uv T �u Q1 � �� � Q� ΐ ^� f� � ` E ��4 � �� ~� !� �� �� .� � � ;� �TH� !� � U� >� :� b� �� � � H \4 �� V� T� � / � � �4 U| Q�TR4 � �3 �4 U| R0 @- �4 U| Tv � �� � � U p{ �� � � �F7 �� q� c� �� �� �� �� �� �� ÷ ��~з (� &� ܷ ��~� Q� 5� �� ݗ ˗ �� � � | �5 �� )� '� �� 3 3 �6 �� :� 8� �� T� R� �� c� a� > � U � / 6 U~ , � =6 U| Q��~R4 H F7 U6 U~ � K7 k � �6 U| Q � %# �6 U| T Q} ���� � � �6 U| � @- �6 U| Tv Q � F7 �6 U~ �� � *7 U !v 6 � U �{ � �� � @ � ��9 � x� p� "� �� �� /� Ԙ ̘ <� � �� H� +� %� T� N� J� �� � � ��7 �� e� c� s� 9 t� x� r� �� � " �n8 �� �� �� �� �� �� �� " �� ˙ Ù � � Uv T �� � � ��8 �� �� � � � �8 Uv T| W � �8 Uv T} Q0 v � Uv T Q} e � '9 Uv T} } � J9 Uv Ts Q1 � � h9 Uv R| � @- �9 Uv T~ Q0 � �9 Uv T| Q1 k� �� 1 �@: Ѳ � �� !� � � <� 8� �� Y� S� P7 %: Uv T�TQ�Q & @: Uv T| �� "� @ � �> 2� z� r� ?� �� �� L� Ԛ Κ Y� �� � e� &� � q� T� P� �� } } �: �� m� k� �� 5 �; �� �� z� �� � Q c; �� �� �� �� �� �� �� Q �� ؛ Л [ � Uv T~ �� n n �; �� �� �� �� K � �; Uv T| � � �; Uv T} Q0 � � Uv T~ Q} �� f �< �� � � G > ;< Uv T Q0 X > W< U2Q0 � � z< Uv T} Q0 � > �< Uv T~ Q0 � � U | Q~ R X �� � � .= �� �� &� $� b � != Uv T0 z � D= Uv T} Q1 � � b= Uv R| � @- �= Uv Ts Q0 � � �= Uv T} Q0 0 �9 �= Uv T| Q1 � > �= Uv T~ Q0 � � U �{ Q~ �� |� *� ޱ � 1 ��> � 9� 3� �� Y� U� � t� p� � �� �� E: �> Uv T�TQ�Q @: Uv T| @� 0 � ��A P� �� �� ]� � � j� a� W� w� �� �� �� ɝ Ý �� � � �� u u `L? �� � � �� � h@ �� � � �� � � `�? �� <� 8� �� T� P� �� � �� p� h� � � U} T �� � � `@ �� �� �� �� # � $@ U} T| m � G@ U} T~ Q0 � � U} T Q~ �� � � g�@ �� �� �� �� �� �� �� � �� ڞ Ԟ � � U} Tv Z � �@ U} T0 r � A U} T~ Q1 � � -A U} R| � @- PA U} Tv Q0 � �9 sA U} T| Q; � � �A U} T| Qv RPX0Y0 � U <v �� � ��D �� � �� �� ^� N� ̰ �� �� ٰ � ۟ � � � � 6� 0� �� e e �`B �� V� T� � � |C � i� c� �� � � ��B �� �� �� �� �� �� �� � �� �� �� � � U} T �� � � �C �� �� ߠ ݠ � 8C U} T| ] � [C U} T~ Q0 | � U} T Q~ �� � � ��C �� � � �� � � �� � �� &� � � � U} Tv J � D U} T0 b � #D U} T~ Q1 � � AD U} R| � @- dD U} Tv Q0 � �9 �D U} T| Q< � � �D U} T| Qv RPX0Y0 � U <v �� + �NH � V� B� � �� �� !� � � .� J� <� :� �� �� F� �� �� S� �� � �� U U ��E �� #� !� r� �F w� 6� 0� �� � �F �� U� Q� �� m� i� �� �� �� �� � � U~ T �� �;F �� �� �� �� C � YF U~ T| � � |F U~ T} Q0 � � U~ T Q} �� � 1 � G �� �� �� �� ף ӣ �� 1 �� � � � � U~ Tv : � !G U~ T0 R � DG U~ T} Q1 { � bG U~ R| � @- �G U~ Tv Q0 � �9 �G U~ T| Q7 � � �G U~ T| Qv RqX0Y0 �9 �G U~ T| Q7 ( � 2H U~ T| Q0RqX0Y0 ; � U <v :� @ ? ��K J� � � W� w� g� d� Ƥ �� q� �� � }� .� (� �� O� I� �� p� j� �� � � ��H �� �� �� �� C J �� �� �� �� � _ �yI �� ¥ �� �� ڥ ֥ �� _ �� �� � ; � U} T �� N N ��I �� �� � � k � �I U} T| � � �I U} T~ Q0 � � U} T Q~ �� $ r �{J �� *� &� �� D� @� �� r �� `� Z� � U} Tv �� 6 � ��J �� �� |� �� �� �� �� � �� �� �� + � U} T~ j � �J U} T0 � � "K U} T~ Q1 � � @K U} R| � @- cK U} Tv Q0 � @- �K U} Tv Q0 �9 �K U} T| Q7 $ � �K U} T| Q~ RpXv Y � � U <v �� � � �zO �� � Ҧ �� &� � �� V� L� Ʈ �� �� Ү �� �� ޮ � � � �D �� � � ��L �� � � � � �M � � � �� � � �!M �� :� 6� �� R� N� �� � �� n� f� � � Uv T~ �� � � �ZM �� �� �� �� � xM Uv T| ^ � �M Uv T} Q0 } � Uv T~ Q} �� e e ��M �� �� �� �� � � �WN �� �� �� �� ̨ Ȩ �� � �� � � � � Uv T} � � tN Uv T0 � � �N Uv T} Q1 � � �N Uv R| & @- �N Uv Ts Q0 T � �N Uv Q�DR4 �9 O Uv T| Q7 � � MO Uv T| Q} RpX0 ! � lO U <v ! �� �� ! ] ��P �� � � �� >� 2� �� �� r� �� ��}Ǭ ԩ ʩ Ԭ � �� �� +" +" �NP �� � � �� &� $� �� 9� 5� @" � U Q~ R V! / �! � P U} Q R~ �! @- �P U} Tv Q| �! � �P U} T| Q0RVX Ys m" �� )� p" � ��R 9� \� P� F� �� �� S� ʪ �� `� � �� k� ��x� C� ?� �� �" �" �Q �� Y� W� �� �# � ��Q �� j� h� �� y� w� �� �� �� �# � U~ �" � �Q U} Q��R4 �" K7 # � +R U} T| Q~ &# @- OR U} Tv Q H# � ~R U} T| Q0RVX~ Y# F7 �# F7 �R U~ �# �� $ � U Ov ^� $ � �V n� �� �� {� � ޫ �� � � �� ���� W� O� �� �� y� �� �� �� Ŧ Ϭ ɬ Ҧ � � �� k$ k$ �S �� � � ߦ u$ �S � 4� ,� �$ V U T; �� �$ �$ ! T �� X� V� � � U � i� e� �� v& !�T �� �� ~� �� �� �� �� �� �� �� �& � U T} �� �& �& !�T �� �� Э έ & � �T U T| M& � �T U Tv Q0 j& � U T} Qv Z$ � @U U Q��R4 �$ � cU U Tv Q1 �$ � �U U R| #% V �U U T| Y% � �U U T| Qv $ & v% @- �U U Ts Q0 �% "V V U T| �& �� � � � � �& � �GZ � � ݭ %� %� � 2� W� K� ?� �� L� ��Y� �� �� d� �� �� p� � ۮ |� � � �� -' -' ��V �� 3� 1� �� 7' #W �� J� B� D' V Uv T< �� _' _' �WW �� n� l� �� sX �� � {� �� 5* 2 ��W �� �� �� �� �� �� �� 2 �� ʯ į ]* � Uv T~ �� p* p* �X �� �� � � �) � /X Uv T| * � RX Uv T} Q0 )* � Uv T~ Q} �� ( ( � �X �� �� � �� P) P) Y �� � � �� � � �� ,� *� _) � ' � &Y Uv Q��R4 \' � IY Uv T} Q1 �' � gY Uv R| �' GZ �Y Uv T| ( � �Y Uv Q~ R4 L( �3 �( � �Y Uv �( �3 �Y Uv T| X$Y �( @- Z Uv Ts Q0 �* � 9Z U v �* �� H� �� �* \ �Y_ � C� ;� � q� i� !� �� �� .� �� ;� ��H� �� � S� 8� .� _� p� b� k� �� �� x� ձ ˱ �� !+ !+ 8[ �� � �� �� ++ U[ �� � � 8+ V Uv T< �� S+ S+ <�[ �� F� D� �� E �\ �� Y� S� �� -/ a < \ �� y� u� �� �� �� �� a �� �� �� �/ � Uv T~ �� �/ �/ <C\ �� �� Ӳ Ѳ �. � a\ Uv T| �. � �\ Uv T} Q0 !/ � Uv T~ Q} ʣ v u^ ˣ � � أ 0� � �� Z, Z, � ] �� v� t� �� . . �[] �� �� �� �� �� �� �� �� �� . � �� 0. � n�] �� �� �� �� ۳ ׳ �� � �� �� � �/ � Uv T~ �+ / E, � �] Uv Q��R4 �, �3 �, � ^ Uv - Y_ 6^ Uv T| (- @- Y^ Uv Ts Q0 �/ � U v � �- 0 �^ � � � �- @- Uv Ts Q0 �* / + � �^ Uv Q��R4 P+ � _ Uv T} Q1 y+ � -_ Uv R| �+ GZ K_ Uv T| �/ �� � � 0 � �Xa � ;� +� � �� }� � ״ ϴ +� �D8� � � C� +� #� O� N� L� [� a� [� f� P0 ` k� �� |� ]0 V U| T; �� `0 `0 �P` �� �� �� �� �0 �0 ��` �� �� �� C0 � �` U| Q�DR4 �0 � �` U| R} �0 V �` U| T} �0 / 1 @- a U| Tv Q0 +1 � =a U| T} Qs $ & �1 * �1 �� 5� �1 � ��d E� е ĵ R� � � _� :� 2� l� �� y� ���� k� c� �� �� �� �� Ӷ �� �� )� � �� p� `� �� 2 -b Ɵ �� �� 2 V Uv T< �� 2 2 �ab �� � � �� x2 x2 ��b �� �� � �� T3 T3 � �b �� � � �� U5 � ��b �� � � �� �4 �4 � Mc �� 0� .� �� J� H� �� Y� W� �4 � �1 � qc Uv Q��R4 :2 � �c Uv R| �2 GZ �c Uv T| �2 / �2 @- �c Uv T Q0 3 / >3 � d Uv Q��R4 �3 �3 �3 � 3d Uv �3 �3 ]d Uv T| X$Ys R5 C# �d Uv T��QB s5 * �d Uv T Q0 �5 � �d U v �5 �� ˤ �5 � �uh ۤ p� h� � �� �� �� ̸ ĸ � �� � � ��)� � � 4� I� A� @� w� k� L� �� �� � Թ ҹ Y� � �e ^� I� A� �5 V Uv T< �� �5 ��e �� � � }� � �f ~� �� �� �� � �@f �� � � �� 4� 0� �� � �� N� H� �8 � Uv T �� �8 �of �� �� j� h� �7 � �f Uv T} B8 � �f Uv T| Q0 g8 � Uv T Q| �� �6 � �f �� y� w� �� �8 � Lg �� �� �� �� �� �� �� �� �� �8 � �5 � og Uv T| Q1 $6 � �g Uv R} �6 GZ �g Uv T} Q~ �6 � �g Uv Q��R8 �6 �3 +7 � �g Uv i7 �3 %h Uv T} X$Y �7 @- Hh Uv Ts Q0 /9 � gh U v 49 �� ˤ �h � � @9 d �i %� �� �� 2� Ӻ >� � � J� � � W9 i �h U�U h9 F7 �9 F7 �9 F7 � �� �9 _ � j �� )� !� ǚ T� J� Ӛ � }� ߚ �� �� � �� �� �� �� �� !� �9 � �i /� R� P� � �9 �i � a� _� �9 j �i Us : j U�TT /u E� �� �� �l � y� o� � �� �� � �� �� )� $� � 5� V� L� B� ʽ ½ O� D� <� !� : 6 �j /� p� n� [� 8: �j `� �� }� m� I �k r� �� �� � f Dk �� � � �� �� � ~: �3 Us Q Nt R>X0Y0 ! � �: � a � � � � '� 9� 7� 4� N� F� ; �3 Us Q Nt R>X0Y0 �� �: �k �� {� y� Z; j U�TT /u Z� `; � �mm g� �� �� t� �� �� �� �� �� � �� � � �� w� o� �� � � !� � � �l /� �� �; �l Ù � �� Й � m ՙ /� -� � �@�; mm �l Us T0R0Y�@ �; W# Us T| � �; =m � @� <� #< �� 2< j U�TT mv ߸ � @< � ��n � ^� V� � �� �� &� � �� 2� � � >� � � K� K� A� X� �� �� !� S< � � n /� �� �� d� d< 8n i� � �� v� �< ` �n w� ,� (� �� �� G� E� �� �< �n �� V� T� �< �n �n Us �< mm Us R0X~ Y0 �< j U�TT jv V� `� = , ��p m� l� d� z� �� �� �� �� �� �� � � �� C� ;� �� �� �� !� = � 6 �o /� � � �� � hp �� *� &� ʖ D� >� ז � �o ؖ f� b� > �p Us T| n= 9# p Us T} Q1 �= 9# 0p Us T} Q1 �= �3 Mp Us Q2 �= 9# > �p � �= �p � |� z� ,> j U�TT /u �� J� ɕ 0> , �rr ֕ �� �� � �� �� � � � �� >� 6� � i� a� � �� �� !� 4> H Nq /� ?� =� !� (r &� P� L� 3� j� d� @� ) �q A� �� �� K? �p Us T| �> 9# �q Us T} Q1 �> 9# �q Us T} Q1 �> �3 r Us Q2 %? 9# 5? �p P� ? Or Q� �� �� \? j U�TT /u ɳ `? # �L� ٳ �� �� � � �� � �� �� � ��~ � ��~'� Y� 3� 4� � � A� ��~N� h� T� [� ��~h� �� �� t� �� �� �� � �� �� �� t� �� '� !� �� R� D� �� �� �� �� �� �� ʹ �� o� ڴ %� � � �� �� � 4� 2� �� �? �s �� I� G� �� < t �� Z� V� �� t� p� �� < �� �� �� KA � Uv `� N �t e� �� �� r� ��~�� �@ , it �� �� �� �@ � �t Uv Q��~R4 �B / �B �3 �t Uv R0 .Q � U p{ �� u \v �� �� �� �� �A C u �� <� :� �� �G S qu �� M� K� �� g� e� �� v� t� �G � U��} A F7 �u U��} �A � �u Uv Q��~R4 �B / IC � �u Uv Q��} sC %# �u Uv T��} �C � v Uv NH K7 FQ � @v U �{ �Q � U qv � �A {v �� � � �v � �A V Uv *� � �v /� JB V Uv T< �� � Cw �� ��~�� � l w �� �� �� �� � l "w �� �� �� �C � Uv Q��~R8 �� �D � mw �� �� �� � yx � �� �� �� # �w �� �� �� �� � � �� # �� '� � UP � Uv T��} �� vP x �� �� L� J� �I � 3x Uv T| -J � Vx Uv T Q0 ZJ � Uv T��}Q �� |E 6�x �� [� Y� �� 8 L�x �� n� h� �� �� �� �� J �� �� �� %P � Uv �� \ RWy �� �� �� �� �� �� �� \ �� � � 5P � Uv Ts �� n ��y �� )� %� �� C� ?� �� � �� a� Y� EP � Uv T~ � � �y � �F V Uv T; �� � Az �� ��~�� �G r z �� �� �� �G � Uv Q��~R4 �� �H z �z �� �� �� �� �� �� �� �� �� �H � �� � �z �� �� �� �J V Uv T; ˵ � n| е �� �� ݵ � � � � � ��~�� ;� 5� � Y� W� #� � y{ (� ��~�� �K � Y{ �� h� f� �K � Uv Q| R4 � �{ � ��~�� ��{ �� x� v� �� + ��{ �� �� �� GK � Uv Q��~R8 �� �K �| �� yK �3 -| Uv R0 'L � Q| Uv Q��~R8 Q � U �z �� M _ $ ,} (� �� �� � �� �� � �� �� � �� �� 5� �� �� B� 1M . C� >M t� �| U _M �3 Uv T��}Q XDY0 %� �M l} *� � � �M V Uv T; F� ; ́ K� /� #� X� n� `� e� X �} j� �� �� UN V Uv T; �� �N ��} �� �� �� �� h � H~ �� �� �� �� � � �� } �� 8� 2� bP � Uv �� � � �~ �� X� T� �� r� n� �� � �� �� �� �P � Uv Ts �� � � �� �� �� �� �� �� �� � �� �� �� �P � Uv T��} �� � � a �� � � �� /� +� �� � �� K� E� �P � Uv T| �� � � � �� k� g� �� �� �� �� � �� �� �� �P � Uv T| �� }O � �� �� �� �� E� �� �� �� �� �� �� �� �� � �� �P � Uv T 7N e� ]� Uv hN V �� Uv T} Q1 �N > �� Uv T��}Q0 �N j� Uv T��}Q��}X} Y2 �N o� �� Uv T} �N � � Uv T} 4O y� :� Uv T Q��} HO ~� R� Uv �O � p� Uv R| �O F7 �� U��} �P � �� U X| aQ � U �| T��} �? / �? � �� Uv T} @ � � Uv R| -@ / G@ @- F� Uv T~ Q0 !B / nB * v� Uv T~ Q0 D � �� Uv 1D � �� Uv �D � ʂ Uv Q��~R4 E � � Uv T��}Q1 E [� � Uv T Q �t R0 UE `� J� Uv Q R �v �E e� h� Uv T| �E j� �� Uv T��}Q X��}Y6 �E o� �� Uv Ts �E � ׃ Uv Ts F F7 � U��} "F @- � Uv T~ Q0 IF �9 7� Uv T| Q7 bF � t� Uv T| Q~ R ��}�8$8&X0Y0 �F � �� Uv T0 �G / +H � Uv Q��~R8 �H / �J � � Uv Ts �J V � Uv T �L > 0� Uv T��}Q0 �L > L� U2Q0 ~M `� q� Uv R �v �M � �� U �| T��}Q��} �M V Ņ Uv T��}Q1 �M �9 � Uv T| Q< N �9 � Uv T| Q; P � >� Uv Ts Q0RtX0Y0 fQ �� ɳ [� � ɋ �� X� �� w� � '� � �� �Q �� �� � � �� ;� 7� �� V� R� �Q rr U�UT�TQ0U� �Q � �Q � �:� � {� m� � �� �� � $� � )� �� �� 6� ��C� �� �� O� �� �� \� � a� �� �� 1R / �� �� � � �� ;R ? ʇ �� (� &� +R � U~ Q��R8 �� uS O 4Ҋ ҥ ?� 5� ť j� f� �� �� �� �� �� �� O ߥ �� �� � �� �� �� � � � '� !� � N� D� � e �� !� �� �� zS V U~ T; �� �S �S T� �� �� �� @� u � A� �� �� �� V � Ti� �� �� �� �� �� �� �� � �� � � KV � U~ Ts �� ^V ^V T�� �� �� .� ,� �U � �� U~ T �U � � U~ T} Q0 V � U~ Ts Q} �S � '� U~ T} Q1 �S � E� U~ R �S V i� U~ T Q| T � �� U~ T Q} <T @- �� U~ Tv Q0 ;V "V U~ T Q| o� � Y� p� ?� ;� �� �T �T * � �� W� U� �T �3 =� U~ R0 �V � U } �Q / �R � �� U~ Q��R8 [S �d �� U~ Tv R} pT { ̋ U~ Tv U � � U @} T| -U / �U rr ,� U�UT�TQ1U� �Q xV �� ֔ �V � � � n� d� � �� �� �� �� �� � � � � 7� 5� !� G� E� .� �v �;� � Ό @� l� j� M� � � R� {� y� _� � � d� �� �� q� � � v� �� �� �� � :� �� �� �� �� U� �� �� �� �� p� �� �� �� �� �X � � �� �� �� �X �3 ō Uv T �w Q8R1 �X � � Uv T2 Y � � Uv T| Q �w Y � *� Uv T; 2Y � U� Uv T| Q �w ?Y � r� Uv T; TY � �� Uv T| Q �w mY � ώ Uv T| Q �w Rv� uY j � Uv �Y � Uv T x Q2R3 �V � T� U ��Tv Q| R �v X �v �V � �� Uv T �v Q �9 R| X /u Y0 W � � Uv T �v Q~ R| X �v Y0 EW � +� Uv T �v Q @< R| X �v Y0 nW � n� Uv T �v Q~ R| X �v Y0 �W � �� Uv T w Q `; R| X �v Y0 �W � � Uv T w Q �f R| X w Y0 �W � L� Uv T 1w Q �g R| X w Y0 X � �� Uv T Ew Q Ph R| X �v Y0 0X � ّ Uv T Vw Q~ R| X /u Y0 YX � � Uv T nw Q~ R| X /u Y0 �X � _� Uv T �w Q~ R| X /u Y0 �X � �� Uv T �w Q = R| X /u Y0 �X � � Uv T �w Q 0> R| X /u Y0 �Y � U�U �� �� � �� ߓ {� � �Y N �Ɠ �� � �� �� c� a� 9Z Փ s� TP YZ Փ �� TP �Z Փ �� U�hTp �Z Փ U�hTq {� Փ �� ݒ �� [ h �� �� �� v� �� �� �� �� 2� � �� �� �� �� �� �� �� � �� �� e� [� � �� �� �� �� �� �� �� �� �� � $ � � �� � �� �� +� 3� )� X� 7 3� ]� ���� \ - � �� a� _� h� �^ ` i� r� p� v� �^ �3 U~ T} �� �] / �� �� �� � �� �� �� �� �� �� �] � U| 8� �] c ݕ =� �� �� J� �� �� �] �3 U��T�� �� V � �� �� �� �� p^ �3 U} Ts �� _ [ ]� �� � � �� 7_ �3 U~ T} {[ � {� U| Tv �[ � �� Ts � 7\ � �� U| Tv �\ � і U| R4 :] � U| h_ �� �� � �� �� � l� �� B� F p_ � �� O� !� � i� Q� M� \� g� e� \� �� f ��� �� � y� �� �� �� �� v �� �� �� �_ � Uv �� � �� �� �� �_ �3 � Uv Q Nt R>X0Y0 �_ *� U�U B� *� \� /� L� � �x� \� � �� i� �� �� t� � �� �� j� X� �� �� �� �� � � �� .� "� �� q� g� �� �� �� ͜ �� �� ڜ � �� ߜ ��� 7� /� �� i� _� � �� � ��&a }� /� U��T��Q��R0 Fa �p G� U| �e H# q� U| T} Q��R2 f �9 �� U| T} Q3 f � U h} �� ]b � ț �� �� �� �� �� �� �� �� �� �� � �� �� ]b ?� �� g� a� jb V U| T< �� � s� � �� �� �b V U| T; � � �� � �� �� �b V U| T; �� �e � �� �� �� �e V U| T< c 9# � U| T} Q1 #c 9# -� U| T} Q1 3c �3 J� U| Q2 Qc 9# m� U| T} Q1 tc 9# �� U| T} Q1 �c �3 �� U| Q2 �d 9# �d 9# !� �c � &� �� �� d "� U} ϓ | 3� �� 4� �� �� A� �� �� �� 4f 4f P k� �� �� �� �� :e � �� U| T} �e � U| Ts Q0 P` �3 ޜ U| Q Nt R>X0Y0 �` x� �� U| Tv �a f) � U| Tv 3b � 9� U �} Jb f) W� U| Tv �c @- z� U| Tv Q0 �c �� �� U| Tv �c � �� U| $� v Pd � ѝ U�U �d �� � U| Tv �d K7 � U� e H# 1� U| T} Qv�R2 �e �� O� U| T} Uf �� jf � U x �� � '� �� �� ǘ �f � �B� Ԙ � � � D� :� � v� t� �� �� �� � �� �� � �� �� !� �f � #� /� � � � 3 �� $� '� #� /� <� ?� ;� � g E ? �� >� 3� U� S� &� d� b� g /� Us T Q0R0 �f �n Ɵ Us *g W# ޟ Us ]g �3 Us Q2 J� 2g � K� s� q� qg j U�TT 1x 3� �g � �ա @� �� �� M� �� �� Y� �� �� e� �� �� q� "� � ~� �� x� !� �g [ � Ԡ /� �� �� �� q �� �� �� �� �� �� �� �� ߛ �g � H _� � �� �� �� � � � h /� Us T0Q} R0 h W# w� Us :h �3 Q2 �� h �� �� � � Nh j U�TT =x �� � �ä �� 1� '� Ɨ o� c� җ �� �� ޗ �� �� � �� �� �� <� 6� !� Th � [� /� �� �� � � y� � �� �� � �� �� X� �h � P d� u� �� �� h� %� � � �� V� T� �� k� c� �� �� �� �� �� �� �� �� �� O� Û �� �� Л �� �� �i �3 Us Q~ R>X0Y0 �h �3 }� Us Q~ R>X0Y0 i x� �� Us 8i mm ǣ Us T0Q} R4X0Y0 �i K7 � U 5j /� � Us T0Q0R4X6 ]j Փ *� U} Tp qj f# H� Us T} �j �� Us T} Ki W# Us #� Si �� $� #� !� �j j U�TT Jx <� �� I� �� O� x~ � � "� � 9 / � � ?�) � �� %�$ %� * %j< %e< %�$ � & %_0 � ( * @int j �( *6 % �? �= �% �6 \ �6 � �= �D �6 H, �= 0' �� �6 �j �( �� �3 �� A � � � � � � �2 �� �B �!� G = %�$ G ^ @� �% O� �2 l% k �3 � � �= &� � �@ � = � = �8 � � � Z8 � � 1 %`< G = %z / �" 6 � � & S �$ j l# / S � � � R � �/ " � h #� p�. $� x1 '� � � � = � "� 1 q � � = N � � p *! k r � � K � ^ �( v �9 J � Z = � � � �? > � ! j @= "� H Z � = k/ F � 3� � G j xD 0E � &8� 6= :� �+ ;� &?0 � A j �( B j � C� &Ga 6= I� �+ J� � K� & O� 6= Q� �+ R� � S j �D T� ;0 U� &a� � c �. d ^� Z e� � gv & Y# w< [ [ ]W �1 h � &lG GF n� �, o j &tx � v �; w j - x6 p3� � 5� �$ <� �: D� -_rt L0 &; Va �6 i� �F p# �@ yG j � = &�$ = �0 & j � ( j � * j � 0 j 8 { x * |� N 'Y j = m ^ ^ B%� * Q3 �� �7 �u �D � � � G � = � � "75 � � � "� � � � "17 � � � "i �9 �Z = �u 5 �� <: �� ^ �s _ ;, � = u ^? � f 2 �C X �% 2 i i � " � � � "�- � � � " / � � � "T< "�? ' "E 1 1 ; � E � O � Y � c m Z w � � � � � � � � � " � 6 � �& 2 =: � 2 !� {& �( � ( JA � 8 �B � H 8 = & H = 2 X = �C �s � � � = �C �T yB � �6 $ � ; ,� �A -� / � �, 0 � � 2 j $�$ 4 � (9 9 � 0�8 = 8�) ? @? J� H�3 K� X & L� h3 YT x 1 d = )tm 8� � j � j � j f j � j q8 j �9 j I j �/ j O@ � (� � 0 S8 A �> = �@ Y � j V> 2 ) b� " d = $" e Y � fj � gj �/ h Y � �� �@ = tC Y j �3 = 4 D n? F = �4 G Y 6D Hj G = � *DIR + "0: $IV o� 0 $UV p= $NV �[ K %� %t$ 5 f � i $OP h � )op (�X 5 ��0 �& ��0 Y ��G �# ��E �- �00 � �00 �8 �00 6C �00 �- �00 @ �00 � �00 �6 �00 �9 � 0 "� � 0 # $COP i d 4cop X�� 5 ��0 �& ��0 Y ��G �# ��E #�- �00 #� �00 #�8 �00 #6C �00 #�- �00 # @ �00 #� �00 #�6 �00 �9 � 0 "� � 0 #� �h0 $ ��E (-A � = 0�! � R0 8�# � R0 <&) ��N @�1 � �N H�6 � R0 P � o � : `�� 5 ��0 �& ��0 Y ��G �# ��E �- �00 � �00 �8 �00 6C �00 �- �00 @ �00 � �00 �6 �00 �9 � 0 "� � 0 #� � �0 (�6 � �0 0(- �E 8�8 R0 @� �G H� �G P�0 �0 X �$ s � 1C P� 5 ��0 �& ��0 Y ��G �# ��E #�- �00 #� �00 #�8 �00 #6C �00 #�- �00 # @ �00 #� �00 #�6 �00 �9 � 0 "� � 0 #� � �0 (�6 � �0 0�! � �0 8� � �0 @P$ � �0 H � ~ * 5� �r# �2 #�0 .Iop $�0 o3 %�0 � '�0 GB (�0 � *�Z (% ,<0 0� -<0 4BC /�Z 8Y 0<0 @o 1<0 D� 3�0 H�= 4k Pz" 5k X�- 6k `Z$ 8R0 h� :�Z p!@ <�Z x5 =�Z �� A 0 �* C@ ��5 E�0 ��' H�G ��8 K�> � L�> ��2 N�0 �rA O�0 �@ ^00 �� h 0 � E i 0 �29 j�0 ��, v 0 �^1 }0 �hA ��0 �3( ��0 ��2 ��Q �� ��0 �54 ��Z ��8 ��0 �VA �0 ��0 � ��0 j ��> �! ��Z � ��Z (�* �&F 0� �# 8O! �# P"' �# h_' �# �V. ��/ �a ��/ �6ISv ϒ0 �d ��Z �4 ��0 6Ina �i x �� h) ��0 ��% ��0 �6Irs ��0 �Q ��0 �� ��0 �� ��0 �c �� �NC ��0 ��A ��0 �n= ��0 �z �0 �r $P h $P U4 �N " �0 ��; ,3 �� �0 �< �0 � �0 - �0 � �0 �> = (� i 0}0 00 8)? ? 0 :� A�0 ; B�0 <W6 C�0 =�F D�0 >� H ?� K�0 @� N�Z H e Z xl } Z �g �vZ �'9 �Y � D �= �I �R0 �$= �R0 �q �j �� �j �� �Y �; ��0 �� ��0 ��9 ��0 ��( �= ��: �� �0 ��0 ��F ��0 �� ��0 � ��Z �9< �� � ��0 � ��0 � ��0 � ��0 � ��0 D ��0 � ��0 � ��0 g �= + ��0 �" �| � �<0 (� �<0 ,� �<0 0�= �j 4 ��Z 8� ��0 @b ��0 H" ��0 P 9 ��0 X� ��0 `�D ��0 h�= ��0 p1 ��0 x� ��0 ��B ��0 � ��0 ��# ��0 ��9 ��0 �� ��0 �v ��Z �L ��0 �.% ��0 �6A ��0 ��# ��0 �� ��0 �� ��0 �� ��0 �� ��0 1> ��0 �" �= �F Z9 � �0 �0 (�, �0 0 �0 8�+ �Q @�? j H� j L�0 = Pj �0 X%% �0 `�' �0 h�3 j p�! <0 t�E �0 xL; �0 y�/ 00 zm j |� <0 ��? #<0 ��; $[ �5 3�0 ��8 6[ �� 8X �x :Z9 �' ;!F � <�E XF =�E �. EZ9 �5 Fj O IR0 $C' K�0 (� L�0 )� M�0 *� N�0 +�F Q_ ,� R_ 0� SS 4z7 TS 8CIan UR0 <�D XR0 @3) `R0 D�' cR0 H:3 dR0 Lm7 eY P� i= X�" k[1 `- n$1 h� o01 p� q[ xZ3 sc0 �� uR0 �� Y �; ��0 9 �<0 ;% ��E � ��E �1 ��E ( �C ��E 0 � ��E 8 H? �)[ @ �> �= � \% �� � �� � � �R0 � �: � 0 � �" ��0 � y= � 0 � �2 ��0 � �; �= � : �� � �E �= � � �� � �9 ��0 � �? ��0 � ' ��Y � G/ ��0 � � �D � �j � }. ��0 � Q- ��0 � �7 �= � < ��0 � � �: ��0 �D ��0 98 ��0 Y! ��0 �? �9[ ( �( ��0 0 �< � 8 ; �0 @ J: �0 H # C[ P � �E X � �E ` |9 H[ h 2 �0 p ; �0 x B 1 � �2 M[ � ; M[ � p �0 � )0 �0 � �B � � [ #?Y � �. $?Y � �' -?Y � �- 1aY � p) 4nY � # 7�Y � � :�0 � �+ @�0 � Y C�0 � E�0 � E: GR[ "F KW[ ~ M�Y T? P�Z X �C Y\[ ` � Zj h D b�X p $ oa[ � F z�E � � |i � �& ��E � ? �q[ � �0 ��0 � �& ��0 � �5 ��0 � � ��0 � �: ��0 � % ��0 � �$ ��0 � R& ��0 X ��0 D# ��0 �+ ��0 � ��0 � ��0 ( �B ��0 0 �% ��0 8 �- ��0 @ � ��0 H B ��0 P I1 ��0 X �B ��[ ` �C ��[ � YE ��0 `d ��0 h4 ��0 p<& ��0 x ��0 ��9 ��0 ��/ ��0 ��0 ��0 ��@ ��0 �� ��0 �u? ��0 � �_ �]; �_ �b= �_ � $SV � "# # )sv �b# #1 � 1, �R0 � �R0 S ��2 $AV � m# )av ��# #1 ��4 1, �R0 � �R0 S �14 $HV � �# �# )hv ��# #1 �"5 1, �R0 � �R0 S ��4 $CV � $ �# )cv �M$ #1 �,4 1, �R0 � �R0 S ��3 28 � Z$ 0 �$ #1 �7 1, R0 � R0 S �5 $GP � �$ )gp P X% �@ �0 �' �E C8 Z9 + R0 ' R0 �: �0 �7 �0 (c9 Z9 0� �0 8�8 R0 f+ R0 , /8 H $GV � c% )gv �% #1 ��3 1, �R0 � �R0 S �;3 $IO � �% 4io �% #1 �5 1, R0 � R0 S '5 � � & p hn & �. r�R B@ h��& @ � 0 �% � 0 y8 � 00 � � <0 � <0 ". <0 )4 �Q �F �> � k � <0 (*1 �Q 0 �- � �& 0 I' - Z8 � T D= 00 �E G ( 0 = k � �0 �7 = ( $XPV � U' 4xpv ��' 03 ��0 + �48 N �i � �_8 � � �' � ( �' 03 �0 + 48 N i � �8 �A �7 � ( { ( _( 03 �0 + 48 N i � �8 �' �7 � l( � 0 �( 03 �0 + 48 N i � �8 �A �7 �% �7 ( � � �( 0 ?) 03 �0 + 48 N i � �8 �A �7 �% �7 ( � L) �D ( �) 03 �0 + 48 I7 k �A k p, �0 L � �) � !��) 03 !� �0 + !�48 �0 !�i !�i T � �) e 0 ;Z* 03 <�0 + <48 N <i � <9 �A =�7 �% >�7 ( : � g* �E h" ++ 03 "�0 + "48 N "i � "�F �1 "�0 �5 "�F ( "�F 0� "�F 8<+ "= @� " G H "Z9 P)< "R0 X�; "=9 \/; "<0 ` � � 8+ � � eC, 03 f�0 + f48 N fi � fi9 �A g�7 d# i63 (�F v�9 0W/ x 0 8l y 0 @�. z 0 Hh? { = P�3 | �0 X�! } = `A ~ �0 hS9 = p� � �0 x7 � G �Q � 0 � y- � U, C, � @ �, o �S `A �S �! �S �= �S K< �S \D �S (�; T 0� �S 8 $ANY � �, Dany ��- O � %! ��0 > ��0 ��0 R ��0 � ��0 { ��0 ; �= � �Y �; � <0 w � R0 A � 0 s" � @ �> � � �2 � �0 � � �0 L> � �0 �8 y�- z�X �> {^ � | � � . �7 0l. R, ��X � � @ Q � @ � ��X � ��X ��X ( k � y. }! ( ��. �4 ��0 v9 �@ �6 ��0 � ��0 # ��0 � � �. _ # / � # k � #&+F �" #' R0 �5 #( R0 $PAD � b# A � 6/ � (#+�/ � #, k c #-WF � #. k � #/�E $# #0 R0 � �/ � 0#L0 OF #M= �8 #M�0 �& #MaF �5 #MR0 @2 #MR0 �, #MR0 A #Mj $�/ #M 0 (V #M 0 ) *I8 $�D *U8 $� 0 *U16 $�* *I32 $�j <0 ;<0 *U32 $�6 R0 ;R0 � $� R0 = � = '�0 �0 # �0 �0 �0 X% b# �# �0 { %w '�0 �0 �0 G �0 = � %<�0 "J K %> 1 �0 � %Q 1 "� W &4I � &5<1 A1 'V1 j V1 u0 < &;$1 3�1 '��1 G> '� <0 �+ '� = �+ '� �0 C1 '� �0 �1 '�g1 76 �"2 �( a �# �$ �< � S+ � .8 � ' ] $ M � � � \B ��1 "2 *HE �>2 )he ! q2 �9 !$ ,3 3 !% /8 \ !)�L *HEK �}2 )hek !-�2 ^2 !.R0 � !/<0 99 !5�0 �'3 �= } �0 � �@ e �K J ��0 �@ ��0 I �'3 � �13 - �63 ,3 32 �$ 1 ��3 �= } �0 � �@ e �K J ��0 �@ ��0 I �'3 � �13 - �63 �) �,4 �= } �0 � �@ e �K J ��0 �@ ��0 I �'3 � �13 - �63 Z* ��4 �= } �0 � �@ e �K J ��0 �@ ��0 I �'3 � �13 - �63 ?) �"5 �= } �0 � �@ e �K J ��0 �@ ��0 I �'3 � �13 - �63 �) �5 = } 0 � @ e K J �0 �@ �0 I '3 � 13 - 63 ++ ,6 = } 0 � @ e K J �0 �@ �0 I '3 � 13 - 63 �E �(n�7 03 (o�0 + (o48 N (oi � (o�: ( (p!�; �@ (q �: (�+ (r �0 0�@ (x R0 8�, (y R0 <)' (z k @� ({ k H� (| i P> ( �; X6 (� `> (� R0 hQ (� R0 l ! (��; p> (� Y xP0 (� R0 ��# (�R0 / (�R0 $< (� = �Y" (��0 �. (� k �&E (� k �" (� k ��# (� k � (� Z9 � ,6 8�. ��7 L � K I8 � �0 �4 � h0 lD � �0 8�A �/8 1. � 0 5 � @ �C � /8 t � �0 q2 8�F �Z8 � � Z8 ) � i �& ��8 " �i � ��7 �8 " i � �7 �8 " i � �7 �8 " i � �7 9 " i � �7 <=9 " <i � <�7 6 A R0 'Z9 �0 Z9 �# J9 �. f�9 " fi � f�7 s�9 o+ t�9 �> u � (�9 v9 ( 0 @ ( 0 5 ( 00 � ( �9 � (((H: % () k �) (* k (+ �0 (, �0 e (- k � �(/p: �9 (0 0 �D (1 p: �9 �: = �5 (<�: �# (= k .end (> k �! (E k �5 (F�: M$ �: (o�: " (oi � (o�7 ( h(��; �@ (�< � (�R< � (��< �< (��< � (��< �E (��< (� (�= 0 C (�'= 8� (�O= @�, (�r= Hg (��< PO= (��= X�@ (��= ` �: �; H: �: �E (�,6 (��; �7 (� Y (��; k K2 (��; �: < �0 �0 R0 �; <0 R< �0 �: = = = k �0 R0 < = �< �0 �: �0 � = = ^0 �< �; W< �0 �< �0 �: �< '�< �0 �: �< '�< �0 �: H0 �0 �< '�< �0 �: H0 �< # �< �< <0 '= �0 �: �< H0 = �0 O= �0 �: �0 �0 ^0 ,= �0 r= �0 �: �< ^0 T= �= �0 �: �= l. w= �: �= �0 �0 j �0 �; �: �= R0 R0 �0 �= !X(� > rex (� > �8 (��> Y" (��0 < (�= . (� i &E (� i (" (� i 0sv (��0 8, (�Z8 @pos (� k H� (� 0 P �; � Q5 (��= ! (� �> Z5 (� �> n (� 1? � (� r? � (� = �> � �(�1? �# (� j F (� = =# (� = sr0 (� �@ u (w�D �> 5�! x(�r? � (��E �B (�r? h (�"r? p 6? �2 (��> < (� <0 !(��? Y@ (� 1? !(� �? Y@ (� 1? Q (� R0 P0 (� R0 cp (��? ! (�<@ Y@ (� 1? Q (� R0 P0 (� R0 cp ( �? � (<@ �9 !@(�@ Y@ ( 1? Q ( R0 P0 ( R0 cp ( �? :1 ( R0 ( �0 � (�@ me (<@ (� ( �@ 0� ( R0 8� ( 00 <] ( 00 > 00 0 !@(�A Y@ ( 1? � ( 1? �1 ( $1? � ( �: cp ( �? ~C ( �? $9 ( R0 (B (!<@ 09 ("= 8 !0(%�A Y@ (' 1? z: (( <0 �3 () <0 �$ (* 0 �# (+= end (,= me (-<@ ( ! (01B Y@ (2 1? 1 (3 1? � (4 �0 �D (5 = !(8JB val (9 j !8(>�B Y@ (@ 1? � (A 1? me (B<@ B (C<@ cp (D�? � (E �0 $� (F j (�$ (I j ,� (J = 0 !((M;C Y@ (O 1? �* (P 1? cp (Q�? ~C (R�? � (S = m: (T <0 i (U <0 $ !`(XD Y@ (Z 1? c1 ([ j c2 ([j cp (\�? Q (] R0 P0 (^ R0 ?3 (_ <0 �$ (` <0 � (a �0 $A (b<@ (B (b<@ 0me (c<@ 85? (dD @� (eD N 0 D = !h(h�D ? (i R0 cp (j�? Q (k R0 P0 (l R0 c1 (m j c2 (mj �7 (n = U% (o = �$ (p j (min (q j ,max (qj 0A (r<@ 8B (r<@ @5? (sD H� (tD V h(��E �2 (�w? Z5 (� �> /yes (��? � (� �? � (�? �. (A@ (#�@ i0 (.�A �0 (6�A � (:1B �* (KJB �@ (V�B & (f;C (uD � (x�> �E �E = �! (�6? �! )D= �% / #k &#!!F � #"!F � ## &F � #$ &F )/ / # MF 8> # MF l #%RF &F �E \F �/ #M�F G6 #M�0 �' #MZ9 "�F " "i � "�7 "�F 01 "�0 # "�, "�F I& "�0 � "_9 " G �1 "�0 C< "/8 "-G [ "d9 m " � {G ZC ��E -sv ��0 -iv �0 -uv �@ -pv �= � �k �; �-G �0 �G �0 �G {G �G �# �0 �> �E K) �0 �G <" �0 C- �E @( 0*1`H *3 = �+ *4 = �: *6 � H@ *7 � � *8 = %$ *9 = i; *: = ( � +*�H �- +, = =( +- = �( +. � �: +/ Y <6 �,HI �. ,MI - ,VI �I ,[I 3 ,b&I ,iG �h ,n7I G I 0= G &I 0= � G 7I 0= � G HI 0= �w �B H-+�I | -- = � -. = -/� -0� h -1� � -2� ((7 -4� 0� -6� 8�D -8= @ E�.� UL � .�= K .� � � .�UL .�= � .� � .�`H (a .�= H�< .� � PX .�ZL X�! .�A `t# .�= �." .� � �G .�_L ��8 .�j �c .�= �+ .� � ��4 .�� ��1 .�= �� .� � �9. .�dL ��2 .�j ��@ .�� ��A .�= $ .� � � .�iL � .��G � .�= H�> .� � P� .�nL XC .�� `y+ .�= ��0 .� � �;E .�sL �r .�HI �� .�= � .� � �� .�xL �h( . d �i1 . d 0 0 ."= h� .# � pn2 .'= x�C .( � �#0 ., j � �H `H A � � �G � HI % .-�I !&�L R7 !'�0 K" !( � Z, !E�L g !F M �7 !G� � !H 00 lF !I 00 � !J R0 �L �0 M �0 �0 R0 M t. H!M�M �F !O�0 Q# !S�0 eC !T�0 RB !U R0 L !V R0 1 !W�M .isa !X�0 (h' !Y�0 0� !ZZ9 8e ![ R0 @ �L 3�1 !g�M E !h /8 �E !i �M /8 * 8!l_N � !m�M �& !n �0 y !o ,3 � !p <0 4- !x <0 p. !y_N !{R0 (\ !|R0 ,< !R0 0 M z � �N �B !�N T= "� �# # j ��B $ �0 �� %00 ��: &k � dN )dN � �N "a3 i �N �N �+ 0SSO F T �0 �E U<0 W &F cv X Z9 U1 Z <0 �A [ �0 ( h& 0`�O F a �0 �E b<0 d &F cv e Z9 gv g �0 ; h �0 ( 8�$P F � �0 �E �<0 �& � �0 �, � �0 �F � �0 cv � Z9 ($6 �$P 0 �N �MP /svp � �0 /gv � �0 !�sP ary � �0 ix � 0 !��P �5 � <0 ix � 0 !��P cur � 0 end � 0 !��P cur � �0 end � �0 �&Q /ary �MP � �sP 8 ��P [= ��P +C 0�{Q � � {Q \+ �)P �0 ��0 o6 ��P t � &F ( � �5 ��Q B ��0 �1 � �0 8�Q ^ �N $: SO j$ �O c: &Q �- �Q X DA X.�R -= / 0 C 0 0 � 1 00 { 2 <0 D 4 k D3 5 k : 6 = � 7 �0 �3 8 �0 (�* 9 = 0�* : = 8� ; = @ < HT =�: P ho�R �% p & AA q�Q 94 8 �S � �0 & �S L �S r; �S � <0 �$ <0 $v <0 (� <0 ,� <0 0 �% �R q- !�R j �S �0 �0 Z8 �S R0 �S �0 �0 Z8 �S j �S �0 �0 Z8 �0 � <0 �S j T �0 Z8 �= T C, &/ bT .val / �1 �# / W & / <0 y / Z9 4 /$T ! (/�T 1 /�T / �0 �( / = *B / = M / �0 nT d! / nT <!C �/"�X � /&�X 7 /'�1 - /(j 1 /+j � /-�X y /.�X .ps //�X (6 /0j 0� /4 <0 4�3 /5 <0 8� /6 <0 <� /7 = @,$ /8 = H&3 /9 0 P�* /: 0 QN% /< 0 R�0 /= �0 S�* />�0 T� /? 0 U� /@ �0 X�6 /A �0 `� /B �0 h0 /C 00 p) /D 00 r� /E <0 tE /F �0 x�# /G <0 �� /H <0 ��$ /I @ ��C /J @ �HE /K�0 �� /L 0 �d" /M 00 ��+ /N <0 �l4 /O �0 � 2 /P �0 �� /Q�X � /R �0 ��( /S = ��A /V = ��A /W = � /X = �yE /Y = �� /Z = �� /[ = �a /` h0 ��4 /a 00 �^) /b 0 �� /c 0 ��/ /d �0 �! /e 63 E /f �0 � /h �X � /i �X @�= /j 0 TY) /k 0 U`4 /l 0 V� /m 0 W� /n �Q X� /o `�C /p h0 `e. /q h0 d�: /t@ h�E /u@ p� /vG x /w�0 y&& /y�0 z�' /{00 �� /|00 �b /}00 ��6 /~00 � �T bT �T �1 �X = <0 �X = !C /�T �- �X "� �X � �Y � ��0 �B �$Y �$Y �X � &+Y 0Y j ?Y �0 u 'LY QY 'aY �0 �0 � (+Y > *{Y �Y �0 �Y �0 �0 * +�Y �Y '�Y �0 F8' 6 y�Y � V �= n' w6 �2 �' 8B H Z pad Z # Z = �& &)Z .Z '>Z �0 �0 "8 7KZ PZ <0 iZ �0 �0 �0 & :_9 [ >)Z < B�Y C I�Z fn J �0 ptr K A9 L�Z �, <0 �S �E �E �X = �Z = � j 0 [ = �Z R0 )[ = = 9[ = �- 9[ �0 }L 1 I' � �0 q[ = " G �[ = �0 �[ = GX :# 76 0>q\ � � �( � % � 3 �5 k% ~/ � ND z$ �1 �< � z; � �- �4 �< �/ �6 E. q ,! �B 3 )/ �3 � �> 76 1F^ � \> � � �> �= �" � @ �' " }% Q r �" Z +2 � B � v Y *2 � A � u : G 0 )( � ! �4 " � # �/ $ � % �% & �? ' v/ ( � ) ? * - + - , B - m . c, / l 0 b, 1 �8 2 0 3 �8 4 / 5 : 6 �0 7 9 8 �0 9 � : �, ; 9 < 9 = B > C ? � @ �D A �& B �+ C =? D � E � F � G � H �7 I �D J � K 0 V^ = �' 2��^ � 2� = ~' 2� i �E 2� = L5 2� = eD 2�= : 2i 2O �^ /nv 2PK F 2QF^ C 2R�^ 5B 02`�` ~ 2a j �7 2b j �- 2i�` R 2l �0 0 2m �0 o 2n �0 f> 2o �^ (g2 2p �0 0�% 2q �0 8� 2r �0 @2 2s0 H�4 2t0 P� 2u j X�" 2v j \�@ 2w j `{ 2x j d 2y �0 h^& 2z j p� 2� j t� 2� j x�+ 2� j |�< 2�V^ ��' 2�V^ �}) 2�V^ �fio 2� 63 � 2� j � 2� j �z, 2� a ��B 2� �0 �5 2� �0 � 2� �0 J 2� j v9 2� j ; 2�0 ; 2�0 {1 2�0 ( . �0 a �0 a � �^ a �` 2��^ 22 2�C, N Ha = 8a � 2�Ha N ja = Za � 2�ja N �a = |a R' 2��a ' 2Z�a �a �a j �a �0 �a �0 a �a �a = �a �? 2\�a �" 2�b �a b �0 %b �0 �a � b 5b = " %b w4 2� 5b ; 2� 5b < 3� pb pb �0 �0 �% [( 3<0 �b �0 �0 <0 � � �b �0 �0 � �$ 3?�0 �b �0 �0 t 3a<0 �b �0 � <0 =� � c �0 �0 k � 3�0 %c �0 �0 7 39 �0 Fc �0 �0 � 8/ �bc �0 �0 0 �zc �0 � , 3W= �c �0 �0 v v �& � �c �0 �0 �0 q � H0 E+ 3� �0 �c �0 �0 �0 * 3T�0 d �0 � <0 1�4 %�j #d 63 1� 4@ j Cd ^ ^ � &5 3�k id �0 63 � w( ��d �0 �0 "2 # 3s �0 �d �0 � v � 3� �0 �d �0 �0 <0 �% 3�0 �d �0 �0 � <0 1�> 3&j e �0 �0 �0 3� K .e �0 �0 H0 [7 3� @ Oe �0 �0 H0 1� 3��0 te �0 �0 k <0 *D 3k �e �0 �0 � ��e �0 �0 ,3 / ��e �0 �0 <0 �< 3��0 �e �0 �0 ,3 h5 3P�@ f f �N �= f +0 f �D 3m Xf �0 �0 �0 � i j j �0 R0 �, 3�0 tf �0 �0 , 3�<0 �f �0 �f �# �4 3 <0 �f �0 �0 �0 D0 w �f �0 �0 � >Z .+ 3 �0 �f �0 �0 k �0 gE 3��0 g �0 ,3 =8 �3g �0 �0 k 3^<0 Tg �0 � <0 � 3� �0 zg �0 � v ^0 H ��g R0 �0 �0 , 3� �0 �g �0 � v � 3o �0 �g �0 V sF � �g �0 �6 N�g �0 � 3d<0 h �0 �0 M0 � 3} �0 ?h �0 �0 �0 k G( 3��Z Vh �0 �. 37 �0 rh �0 �0 @ 0 �h �0 � � �h �0 � 3\Z9 �h �0 � <0 �= 3� = �h �0 �0 �N H0 1 3� �0 �h �0 �0 <0 �D 4�� i � (i � , A 3-� Ii �0 �< q �$ � ji �0 >[ c 1 D %�j �i 63 j �C 3� �i �0 >[ c � 3�k �i �0 63 ^ � �( 3s �i � 5 3^ �0 j �0 .2 � 3� 9[ j �0 q l -j � HIj �0 �0 ; = 3� Z8 ~j �0 �0 �0 q �j � H0 P, ~j 4 3< �0 �j �0 �0 `/ 3P �0 �j �0 v > ��j � , ' u �j �0 �0 ^0 � � k �0 >[ �? 3�,3 &k �0 �0 <0 . 3�<0 Bk �0 �0 �7 ^k �0 �0 R0 & s uk �0 �0 �" *�k �0 �0 t 3��0 �k �0 �0 �* 3n �k � q0 3�j �k �0 �0 �# 3�Z8 �k �< j >D 3� �0 l �0 �0 � 3o Hl �0 �0 � <0 q �0 ^0 �; Kdl �0 �0 ; �B 3� 0 �l �0 �0 H0 o 3��0 �l �0 � <0 �- 3� �0 �l �0 >u> ��l �l � $ �l p &�l �0 H0 � 3$�0 m �0 � <0 .2 � 3�Z9 @m �0 �0 � �0 4 3k �0 \m �0 ; � 3W�0 �m �0 � R0 <0 k9 3� Z9 �m �0 � iZ � � R0 � 3(<0 �m ^0 � , H�A 5Z �n 3 5Z �0 cv 5Z Z9 ax 5_ <0 �0 5_ �0 sp 5_ �0 U 5_ <0 1A 5d � Kn p_ 5t ]n p_ 5v on p_ 5x �n p_ 5z �n p_ 5 �n p_ 5� �n p_ 5� 43 2� �0 5F ^o 3 5F �0 cv 5F Z9 sp 5H �0 ax 5H <0 �0 5H �0 U 5H <0 No �% 5L 0 �# 5M �0 � 5Q 0 1 5S ; d 54 �o 3 54 �0 cv 54 Z9 sp 56 �0 ax 56 <0 �0 56 �0 U 56 <0 �o �% 5: 0 �# 5; �0 � 5? 0 1 5A ; � 5 �p 3 5 �0 cv 5 Z9 sp 5 �0 ax 5 <0 �0 5 �0 U 5 <0 ix 5 <0 kp p_ 5 �p P 2Z �0 �# 2] �0 cxt 2] �a 1 5/ ; � 5 1q 3 5 �0 cv 5 Z9 sp 5 �0 ax 5 <0 �0 5 �0 U 5 <0 !q sv 5 �0 �% 5 �0 1 5 ; O 5� �q 3 5� �0 cv 5� Z9 sp 5� �0 ax 5� <0 �0 5� �0 U 5� <0 �q sv 5� �0 �D 5� 0 �% 5� �0 1 5 ; :$ 5� Xr 3 5� �0 cv 5� Z9 sp 5� �0 ax 5� <0 �0 5� �0 U 5� <0 Hr f 5� 63 �D 5� 0 �% 5� �0 1 5� ; $ 5� �r 3 5� �0 cv 5� Z9 sp 5� �0 ax 5� <0 �0 5� �0 U 5� <0 ix 5� <0 �r p_ 5� �r obj 5� �0 �% 5� �0 1 5� ; � 5� �s 3 5� �0 cv 5� Z9 sp 5� �0 ax 5� <0 �0 5� �0 U 5� <0 ix 5� <0 ts p_ 5� f 5� 63 obj 5� �0 �% 5� �0 1 2" ; h@ 5� t 3 5� �0 cv 5� Z9 sp 5� �0 ax 5� <0 �0 5� �0 U 5� <0 1 5� ; �, � j Vt 3 2� �0 sv 2� �0 mg 2� $Z8 cxt 2� �a � �0 �t 3 2 �0 sv 2 �0 �# 2� �0 cxt 2� �a 7@ 2� i ] 2� �a out 2� �0 �# 2� �0 cxt 2� �a [ l �0 u 3 2l �0 sv 2l �0 �D 2l '0 F$ a �0 Ju 3 2a �0 f 2a $63 �D 2a *0 � � �0 Mv 3 2� �0 f 2� 63 in 2� �0 �7 2� j v9 2� j �# 2� �0 cxt 2� �a sv 2� �0 �" 2� j �F 2� j v � 2� i > 2� � �E 2� = �0 2� i D 2� �0 1v rv 23 �0 43 2M �0 rv 2N �0 ~4 � �0 Pw 3 2��0 cxt 2�$�a <@ 2�5� @ 2� j svh 2� �0 sv 2� �0 ++ F �v tag 2��^ �v �? 2�<0 G 2�<0 p_ 2 w tag 2! <0 p_ 26 len 2^ <0 43 2_ �0 ref 2p �0 p_ 2p �0 x 3 2�0 cxt 2'�a buf 2 x \# 2!.x c 2" j � 2# j ! 2$ j 0@ 2% j � 2& j � 2' j � 2( j x len 23i < 24i ! 2z j .x 0= u& � �0 �x 3 2� �0 cxt 2�-�a <@ 2�>� len 2� <0 7@ 2� <0 i 2� <0 hv 2� �0 sv 2� �0 c 2� j W 2� �0 �x p_ 2� �x p_ 2� p_ 2� � v �0 �y 3 2v �0 cxt 2v.�a <@ 2v?� len 2x <0 i 2y <0 av 2z �0 sv 2{ �0 c 2| j vy p_ 2� p_ 2� � % �0 �z 3 2% �0 cxt 2%+�a <@ 2%<� �9 2' j ~2 2( R0 B 2) i re 2* �0 v9 2+ �0 �9 2, �0 sv 2- �0 sp 2.�0 �$ 2/ <0 43 20 �0 Nz s 2I�Z `z p_ 2_ rz p_ 2a ref 2a�0 p_ 2a �* � �0 �{ 3 2��0 cxt 2�)�a <@ 2�:� sp 2��0 @ 2� <0 �$ 2�<0 2 2�0 cv 2� �0 sv 2� �0 �F 2��0 sub 2��0 J 2��0 43 2� �0 X{ p_ 2� y{ ref 2��0 p_ 2� �{ p_ 2� �{ p_ 2� �{ p_ 2� �{ s 2 �Z �{ p_ 2 �{ p_ 2 p_ 2 � �0 } 3 2 �0 cxt 2 .�a <@ 2 ?� len 2 <0 7@ 2 <0 i 2! <0 hv 2" �0 sv 2# �0 43 2$ �0 �! 2% j �| p_ 2: �| p_ 2< �| ref 2<�0 p_ 2< v9 2G j � 2H j �| sE 2]�0 p_ 2n y& � �0 �} 3 2��0 cxt 2�)�a <@ 2�:� len 2� <0 7@ 2� <0 i 2� <0 hv 2� �0 sv 2� �0 43 2� �0 �} p_ 2� �} p_ 2� ref 2��0 p_ 2� �7 { �0 �~ 3 2{�0 cxt 2{%�a len 2{-@ �! 2{6j <@ 2{N� 7@ 2}@ i 2~@ hv 2 �0 sv 2� �0 43 2� �0 i~ p_ 2� {~ p_ 2� ref 2��0 p_ 2� �3 D �0 \ 3 2D�0 cxt 2D&�a len 2D.@ <@ 2D?� i 2F@ av 2G �0 sv 2H �0 43 2I �0 6 2J �0 , p_ 2R > p_ 2T ref 2T�0 p_ 2T � �0 � 3 2�0 cxt 2*�a <@ 2;� len 2 <0 i 2<0 av 2 �0 sv 2 �0 43 2 �0 6 2 �0 � p_ 2 � p_ 2! ref 2!�0 p_ 2! � � �0 t� 3 2�"�0 cxt 2�1�a <@ 2�B� ref 2�0 p_ 2 � �0 � 3 2��0 cxt 2�*�a <@ 2�;� sv 2� �0 43 2� �0 ref 2��0 p_ 2� Q � �0 P� 3 2� �0 cxt 2�+�a <@ 2�<� sv 2� �0 43 2� �0 ref 2��0 p_ 2� �= � �0 �� 3 2� �0 cxt 2�-�a <@ 2�>� sv 2� �0 43 2� �0 ref 2��0 p_ 2� n! � �0 >� 3 2��0 cxt 2�*�a <@ 2�;� sv 2� �0 43 2� �0 � p_ 2� ref 2��0 p_ 2� J � �0 3 2��0 cxt 2�)�a <@ 2�:� sv 2� �0 43 2� �0 siv 2� j tmp 2�D �� p_ 2� ref 2��0 p_ 2� �A t �0 d� 3 2t �0 cxt 2t+�a <@ 2t<� sv 2v �0 43 2w �0 nv 2xK F� p_ 2 ref 2�0 p_ 2 �. V �0 � 3 2V �0 cxt 2V+�a <@ 2V<� sv 2X �0 43 2Y �0 iv 2Z <0 ҃ p_ 2g ref 2g�0 p_ 2g �9 �0 �� 3 2 �0 cxt 2,�a <@ 2=� @ 2 j len 2 @ sv 2 �0 �! 2 j m� buf 2 �� svh 2$�0 p_ 2* R0 �� = � � �0 '� 3 2� �0 cxt 2�,�a <@ 2�=� sv 2� �0 43 2� �0 iv 2�0 � p_ 2� ref 2��0 p_ 2� C4 � �0 �� 3 2� �0 cxt 2�-�a <@ 2�>� s 2� = len 2� R0 sv 2� �0 F � �0 ߅ 3 2� �0 cxt 2�,�a <@ 2�=� s 2� len 2� j sv 2� �0 � � �0 $� 3 2� �0 cxt 2�-�a <@ 2�>� len 2� R0 � y �0 i� 3 2y �0 cxt 2y,�a <@ 2y=� len 2{ j a8 h �0 �� 3 2h �0 cxt 2h+�a <@ 2h<� len 2j j ( X �0 � 3 2X �0 cxt 2X,�a <@ 2X=� len 2Z R0 ?) �0 �� 3 2�0 cxt 2'�a len 2/@ == 28j <@ 2L� sv 2 �0 43 2 �0 o� p_ 2 ref 2�0 p_ 2 =! � �0 8� 3 2� �0 cxt 2�-�a <@ 2�>� tv 2� �0 sv 2� �0 43 2� �0 idx 2� <0 � p_ 2� )� ref 2��0 p_ 2� p_ 2� � � �0 �� 3 2� �0 cxt 2�-�a <@ 2�>� tv 2� �0 sv 2� �0 key 2� �0 43 2� �0 �� p_ 2� Ԉ ref 2��0 p_ 2� � p_ 2� p_ 2� � �0 �� 3 2�!�0 cxt 2�0�a <@ 2�A� tv 2� �0 sv 2� �0 obj 2��0 43 2� �0 p� p_ 2� �� ref 2��0 p_ 2� p_ 2� Z t �0 >� 3 2t �0 cxt 2t.�a <@ 2t?� tv 2v �0 sv 2w �0 43 2x �0 � p_ 2� /� ref 2��0 p_ 2� p_ 2� 3F R �0 ܊ 3 2R �0 cxt 2R/�a <@ 2R@� tv 2T �0 sv 2U �0 43 2V �0 �� p_ 2` ͊ ref 2`�0 p_ 2` p_ 2g � ; �0 � 3 2;$�0 cxt 2;3�a <@ 2;D� sv 2= �0 M � �0 �� 3 2� �0 cxt 2�/�a <@ 2�@� rv 2� �0 sv 2� �0 43 2� �0 �� p_ 2 �� ref 2�0 p_ 2 j 2!� s � �0 � 3 2� �0 cxt 2�,�a <@ 2�=� sv 2� �0 ( � �0 �� 3 2��0 cxt 2�(�a <@ 2�9� rv 2� �0 sv 2� �0 43 2� �0 q� p_ 2� ref 2��0 p_ 2� �@ � �0 nj 3 2��0 cxt 2�)�a <@ 2�:� �< � �0 z� 3 2�!�0 cxt 2�0�a <@ 2�A� e 2�Lj len 2� R0 buf 2� z� B; 2� = v9 2�6 ) 2� i < 2� �0 � 2� <0 av 2� �0 � 2� �0 sv 2� �0 rv 2� �0 �6 2� �0 43 2� �0 � 2� j � 2� j �A 2� G & 2�6 2� j � p_ 2� � p_ 2� (� p_ 2� :� p_ 2 L� p_ 2 ^� p_ 2 ~� sva 2$�0 idx 2% <0 �� 9; 2@= �� buf 2l �� �� � 2q R0 Ɏ p_ 2� D� ary 2��0 i 2� j tag 2��^ svh 2��0 xsv 2��0 !� buf 2��� 4� tmp 2�R0 p_ 2� � C5 2� �0 W: 2� �0 u� p_ 2� �� p_ 2� �� p_ 2� �� p_ 2� �� p_ 2� Ϗ p_ 2� � p_ 2� � p_ 2 p_ 2 #� ref 2�0 p_ 2 5� p_ 22 G� p_ 26 Y� p_ 2L k� p_ 2R p_ 2� G �� = i g �0 � 3 2g �0 cxt 2g,�a <@ 2g=� len 2i R0 sv 2j �0 buf 2k z� B; 2l = 9; 2m = T ; �0 m� 3 2;!�0 cxt 2;0�a <@ 2;A� idx 2= <0 B; 2>� sva 2? �0 sv 2@ �0 � ! �0 �� 3 2!�0 cxt 2!*�a <@ 2!;� �= �0 ݑ 3 2�0 �# 2�0 cxt 2�a S � j `� 3 2��0 f 2� 63 sv 2� �0 �7 2� j ! 2� j res 2��0 �# 2��0 cxt 2��a � 2� j =7 4 j ے 3 24�0 cxt 24'�a T 2D � \ 2I � a 2c� � 2d k nsz 2~i ^C 2~i % � = ے % � = � % �$ � j y� 3 2��0 cxt 2�!�a sv 2�*�0 svh 2� �0 ret 2� j @ 2� j �- 2��` +�D i� � 2� �^ �� nsz 2�i ^C 2�i Γ nsz 2�i ^C 2�i �� buf 2��� nsz 2�i ^C 2�i � nsz 2�i ^C 2�i � 2� <0 K� nsz 2�i ^C 2�i nsz 2�i ^C 2�i pkg 2 �0 ) C j �� 3 2C�0 sv 2C �0 � j �� 3 2�0 cxt 2'�a sv 20�0 len 2 i buf 2 �� o� v 21 j � 21 2� nsz 21 i ^C 21 i R� nsz 21 i ^C 21 i nsz 21 i ^C 21 i �� nsz 21 i ^C 21 i �� nsz 21 i ^C 21 i ޕ buf 21 �� nsz 21 i ^C 21 i �� nsz 21 i ^C 21 i � nsz 21 i ^C 21 i v 21 j L� nsz 21 i ^C 21 i y� y 21 j nsz 21 i ^C 21 i �� nsz 21 i ^C 21 i nsz 21 i ^C 21 i G ǖ = O N � j �� 3 2��0 cxt 2�#�a sv 2� �0 @ 2� j pkg 2� �0 � 2� �0 B; 2� = len 2� <0 �4 2� <0 k� nsz 2� i ^C 2� i �� 2� nsz 2� i ^C 2� i � �D 2� ̗ nsz 2� i ^C 2� i �� y 2� j nsz 2� i ^C 2� i nsz 2� i ^C 2� i 6� nsz 2� i ^C 2� i e� � 2� nsz 2� i ^C 2� i � �D 2� �� nsz 2� i ^C 2� i Ę y 2� j nsz 2� i ^C 2� i nsz 2� i ^C 2� i nsz 2� i ^C 2� i � � j s� 3 2� �0 cxt 2� �a sv 2� �0 @ 2� j pkg 2� �0 � 2� �0 len 2� <0 B; 2� = ) 2� i ref 2� �0 av 2� �0 ary 2� �0 �$ 2� 0 v9 2� pv 2� = i 2� j j 2� j � 2� j �4 2� <0 ret 2� j � 2� j �A 2� G � 2� � 2� j +� +� �c� p_ 2: u� gv 2h �0 |� � 2�= rsv 2� �0 xsv 2� �0 tag 2� �0 &+ 2� �0 ۚ nsz 2�i ^C 2�i �� nsz 2�i ^C 2�i � nsz 2� i ^C 2� i ;� nsz 2�i ^C 2�i [� nsz 2� i ^C 2� i m� p_ 2� p_ 2� �� nsz 2.i ^C 2.i �� nsz 20i ^C 20i ܛ nsz 21 i ^C 21 i �� nsz 23 i ^C 23 i � nsz 25 i ^C 25 i I� y 2: j nsz 2: i ^C 2: i i� nsz 2: i ^C 2: i �� 2< nsz 2= i ^C 2= i Ŝ y 2A j nsz 2A i ^C 2A i � nsz 2A i ^C 2A i � � 2C nsz 2D i ^C 2D i 4� nsz 2F i ^C 2F i c� buf 2L �� nsz 2L i ^C 2L i �� nsz 2L i ^C 2L i ߝ ) 2Q R0 y 2R j nsz 2R i ^C 2R i nsz 2R i ^C 2R i � � 2T nsz 2U i ^C 2U i .� nsz 2X i ^C 2X i U� � 2\ j �� � 2_ j � y 2`j nsz 2`i ^C 2`i nsz 2`i ^C 2`i ˞ � 2f nsz 2g i ^C 2g i )� tag 2t�^ � buf 2u�� nsz 2ui ^C 2ui nsz 2ui ^C 2ui � 2{<0 nsz 2|i ^C 2|i mg 2�Z8 svt 2�j � z j [� 3 2z �0 cxt 2z +�a sv 2z 4�0 mg 2| Z8 ret 2} j � nsz 2� i ^C 2� i idx 2� <0 � nsz 2� i ^C 2� i =� y 2� j nsz 2� i ^C 2� i nsz 2� i ^C 2� i R 3 j .� 3 23 �0 cxt 23 &�a sv 23 /�0 mg 25 Z8 obj 26 �0 ret 27 j svt 28 j �A 29 G � nsz 2I i ^C 2I i � nsz 2L i ^C 2L i nsz 2O i ^C 2O i �E j ע 3 2 �0 cxt 2 (�a sv 2 1�0 re 2 �0 v9 2 �0 0 2 � 2 � ~2 2 i B 2 i �9 2 0 ޡ nsz 2 i ^C 2 i �� nsz 2 i ^C 2 i Z� � 2 R0 =� y 2 j nsz 2 i ^C 2 i nsz 2 i ^C 2 i z� nsz 2# i ^C 2# i �� nsz 2$ i ^C 2$ i �� nsz 2% i ^C 2% i nsz 2& i ^C 2& i % � j �� 3 2� �0 cxt 2� &�a sv 2� /�0 re 2� 8�0 v9 2� A�0 sp 2� �0 rv 2� �0 cv 2� Z9 �$ 2� <0 j� s 2� �Z |� p_ 2� p_ 2 � } j ߧ 3 2} �0 cxt 2} &�a cv 2} /Z9 sp 2 �0 len 2� i �$ 2� i �B 2� i �F 2� �0 z 2� �0 !� s 2� �Z 4� s 2� �Z T� nsz 2� i ^C 2� i Ф v 2� j � 2� �� nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i nsz 2� i ^C 2� i � nsz 2� i ^C 2� i � nsz 2� i ^C 2� i ?� buf 2� �� nsz 2� i ^C 2� i _� nsz 2� i ^C 2� i � nsz 2� i ^C 2� i � v 2� j �� nsz 2� i ^C 2� i ޥ y 2� j nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i nsz 2� i ^C 2� i �� v 2� j � 2� Z� nsz 2� i ^C 2� i z� nsz 2� i ^C 2� i nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i צ nsz 2� i ^C 2� i � buf 2� �� nsz 2� i ^C 2� i &� nsz 2� i ^C 2� i F� nsz 2� i ^C 2� i v 2� j t� nsz 2� i ^C 2� i �� y 2� j nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i nsz 2� i ^C 2� i B j � 3 2B �0 cxt 2B '�a hv 2B 0�0 �! 2B B ret 2E j i 2F � ix 2G @ AF 2H '3 � 2L �0 ~ 2c ,3 val 2f �0 w3 � j �� 3 2� �0 cxt 2� �a hv 2� �0 i 2� @ hek 2� #/8 val 2� ,�0 �! 2� ? ret 2� j � 2� j v9 2� len 2� <0 � 2� �0 key 2� = V� nsz 2 i ^C 2 i �� y 2- j nsz 2- i ^C 2- i �� nsz 2- i ^C 2- i nsz 2/ i ^C 2/ i S � j w� 3 2� �0 cxt 2� &�a hv 2� /�0 len 2� @ i 2� � ret 2� j � 2� <0 } 2� ,3 � 2� j �! 2� � 2� �0 Iout 2� �� nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i ƪ nsz 2� i ^C 2� i � nsz 2� i ^C 2� i � buf 2� �� nsz 2� i ^C 2� i 5� nsz 2� i ^C 2� i � l 2� <0 e� nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i �� nsz 2� i ^C 2� i ҫ y 2� j nsz 2� i ^C 2� i nsz 2� i ^C 2� i 7� av 23 �0 � p_ 23 $� he 2: ,3 } 2E j v9 2G �. 2H = 2# 2I i V 2J <0 key 2K �0 he 2O ,3 val 2P �0 �� !4 2� � D 2� �0 ̬ nsz 2� i ^C 2� i �� y 2� j nsz 2� i ^C 2� i � nsz 2� i ^C 2� i nsz 2� i ^C 2� i V� he 2� ,3 val 2� �0 h� p_ 2� p_ 2� � B j 2� 3 2B �0 cxt 2B '�a av 2B 0�0 sav 2D �0 len 2E @ i 2F @ ret 2G j � 2H �0 � nsz 2Q i ^C 2Q i ,� nsz 2R i ^C 2R i [� buf 2S �� nsz 2S i ^C 2S i {� nsz 2S i ^C 2S i �� l 2[ <0 �� nsz 2\ i ^C 2\ i خ y 2] j nsz 2] i ^C 2] i nsz 2] i ^C 2] i � nsz 2u i ^C 2u i nsz 2� i ^C 2� i U j ڶ 3 2U �0 cxt 2U (�a sv 2U 1�0 iv 2W 0 pv 2X = len 2Y i v9 2Z R0 +D) +� +� � ү nsz 2g i ^C 2g i � nsz 2j i ^C 2j i � nsz 2� i ^C 2� i 2� nsz 2� i ^C 2� i �� siv 2� d� nsz 2� i ^C 2� i nsz 2� i ^C 2� i а niv 2� <0 �� nsz 2� i ^C 2� i nsz 2� i ^C 2� i � nsz 2� i ^C 2� i � nsz 2� i ^C 2� i ^� nv 2� �^ A� nsz 2 i ^C 2 i nsz 2 i ^C 2 i mg 2 Z8 �& 2 @ N� len 2 w � v 2% j � 2% ɱ nsz 2% i ^C 2% i � nsz 2% i ^C 2% i nsz 2% i ^C 2% i &� nsz 2% i ^C 2% i F� nsz 2% i ^C 2% i u� buf 2% �� nsz 2% i ^C 2% i �� nsz 2% i ^C 2% i �� nsz 2% i ^C 2% i v 2% j � nsz 2% i ^C 2% i � y 2% j nsz 2% i ^C 2% i 0� nsz 2% i ^C 2% i nsz 2% i ^C 2% i ʳ v 2, j � 2, �� nsz 2, i ^C 2, i �� nsz 2, i ^C 2, i nsz 2, i ^C 2, i � nsz 2, i ^C 2, i � nsz 2, i ^C 2, i 9� buf 2, �� nsz 2, i ^C 2, i Y� nsz 2, i ^C 2, i y� nsz 2, i ^C 2, i � v 2, j �� nsz 2, i ^C 2, i ش y 2, j nsz 2, i ^C 2, i �� nsz 2, i ^C 2, i nsz 2, i ^C 2, i �� v 2. j � 2. T� nsz 2. i ^C 2. i t� nsz 2. i ^C 2. i nsz 2. i ^C 2. i �� nsz 2. i ^C 2. i ѵ nsz 2. i ^C 2. i � buf 2. �� nsz 2. i ^C 2. i � nsz 2. i ^C 2. i @� nsz 2. i ^C 2. i v 2. j n� nsz 2. i ^C 2. i �� y 2. j nsz 2. i ^C 2. i �� nsz 2. i ^C 2. i nsz 2. i ^C 2. i �9 j �� 3 2 �0 cxt 2 %�a sv 2 .�0 � 2 j . 2 j y� 43 2' �0 \� nsz 2* i ^C 2* i nsz 2, i ^C 2, i nsz 2. i ^C 2. i � j � 3 2��0 cxt 2� �a �7 2�= len 2�j �4 2��Z svh 2� �0 g2 2� �0 � w �0 �� 3 2w�0 obj 2x�0 � 2y�0 �7 2zj sp 2|�0 �$ 2} j av 2~ �0 i 2 j �� s 2��Z �� p_ 2� sv 2� �0 p_ 2� �5 < �0 �� 3 2<�0 obj 2=�0 � 2>�0 �7 2?j av 2@�0 v9 2A<0 sp 2C�0 �$ 2D j sv 2E �0 M� s 2O�Z x� ary 2S�0 cnt 2Tk i 2Uk p_ 2g � �0 � 3 2�0 c1 2�0 pkg 2�0 2� svh 2 �0 sv 2 �0 �= 2� � 2� O� 3 2��0 c1 2��0 pkg 2��0 2 � �= 2� p_ 2 � 2� �� 3 2��0 c1 2��0 pkg 2��0 2�� �= 2�� �3 � �0 � 3 2��0 c1 2��0 pkg 2��0 2�� gv 2� �0 sv 2� �0 �= 2�� � � j @� 3 2� �0 �# 2��0 cxt 2��a k 2y �� 3 2y�0 cxt 2y)�a �B 2{�a �� p_ 2� �# 2��0 % b�a �� 3 2b"�0 �" 2b1�a cxt 2d�a � X; 2h�0 5 2h�0 �# 2l�0 � 2F %� 3 2F�0 cxt 2F*�a 06 2 �� 3 2$�0 cxt 23�a _� o 2 �0 r� �% 2! �0 �� � 2( �0 R 2/ �0 cB 2� � 3 2�#�0 cxt 2� �a �7 2�j �" 2� j � p_ 2� �� p_ 2� � p_ 2� p_ 2� � 2 �� 3 2!�0 cxt 20�a he 2� ,3 a� �- 2��` t� g2 2� �0 �� � 2� �0 �� 0 2� �0 p_ 2� {A 2 (� 3 2 �0 cxt 2 �a f 263 �7 2 j ! 2 j � p_ 2^ � p_ 2k p_ 2t �C 2 C� cxt 2 $�a t@ 2� �� 3 2� �0 �# 2��0 cxt 2��a X; 2��0 5 2��0 � 6�� sv 6�0 J+ 6�߾ (3 6��0 2sv 6� �0 Krc 6�R0 9� ג0 �� 2sv 6��0 9 Ͽ0 � (3 6� �0 2sv 6��0 9� �<0 :� (3 6��0 :Y 7 j c� 2__s 7 B (X 7 � , :� 89 �� (�3 89 (� 89j (" 89� :� 8 ˿ (�3 8 (g 8h (" 8� L� 91v (N 91v I ~ 4 1�B H} 1�B H} 1 1U 4 1 . 1 4 1 1R�BUX!YW 1R�BX!YW .1@z H } 1 1R�BUX!YW U 1U 1 1R�BX!YW 1 H} 1R�BX!Y!�W! H}� 1X!YW! H }� . ?<n:!;! % U $ > H}� H}� 1 !H} "4 1 #.1U@z $.1 %. ?<n I ~ 1�B H} 4 1�B H} . 1 1U H } 1R�BX!YW 1R�BUX YW .1@z 1U 4 1 1 1 1X!YW 1UX YW 4 1 H}� .1 I �~ 1R�BX!Y!�W! .1U@z U .1n@z 1R�BUX!Y W! 1 H}� . ?<n:!;! % U 1 H} ! 1R�BUX YW ". ?<n 4 : ;9 I 4 : ;9 I : ; 9 I8 I : ;9 I8 : ;9 I8 !I : ;9 I ( : ;9 I : ;9 I : ; 9 I .:!2;9 'I .?: ;9 'I< : ; 9 I & I : ;9 I : ; 9 I8 : ;9 I8 I ! I/ : ; 9 7 I : ;9 : ; 9 I k .?:!3;9 '< 'I .: ;9 ' : ; 9 : ;9 ! : ;9 " < # : ;9!I k $ :!;9 I %$ > & : ; 9 '' ( : ; 9 I ) : ; 9! * : ; 9 I + :!2;9 , - : ; 9 I . : ; 9 I8 / : ;9 I 0! I/ 1.?: ; 9 'I< 2 : ; 9 I 3 !: ; 9! 4 : ;9! 5 : ;9 6 :! ; 9!I8 7>! !I: ; 9 8 !:! ;9! 9.:!6; 9!'I :.?: ; 9!'I ;5 I < : ; 9 =.?:!3; 9!'< >.?:!3;9!'�< ?% @$ > A B& C : ;9 I8 D : ;9 E : ;9 F> I: ;9 G4 : ;9 I?< H.?: ;9 ' I : ;9 J.: ; 9 ' K4 : ; 9 I L.: ; 9 'I *q K � / E W c l w � � �= � &Amt <J �Ys YI�X J Y �� J Y ��� J Y ��� J Y ��� H� Y�t=Y<<� �~�J�v �~gu��� S� J�t���f .u< �uf (L XY u /WJX ....zJ Ks� X u= Gt� � �8�8 � v r7� X �� ��~�t � � � � t X < � � �5s = � . < < � X �< J � � . Ye Y g � � � �~ t�t%� t � t � �J �~< t(R � t � O 7 t �� J wX � Q � � � � � � G i � � . � # ' � � � � � � � .�� � t � �$ �� � �# N� '< ' 'X ' c� c� k� k k k m m�l m m m�J m�lX m. m� mJ � �f � � �J �� � �X � $� $X $ [� c. c c c f v� v v {t { { {t � � #� # &� .. . . 0� 8. 8 8 8 9 9 9�lX 9 9 9�. 9�lJ 9. 9�. 9J 9�l 9 9� 9� G� Of O O QJ Q�Jt�KJ �'� '�l � �lt.�-K � . � '&� t � t � �J �~< t $� $X $ [� c. c c c f w� �� � � �J �# # # &� .. . . 0� � < < < � w � � � � �X� K � X � X � �g � . � a% t � � � < �% � X. t% �" J �J " � � < J e� e�l e e e�J e�lX e. e� eJ h� h h mt m m m� : F� F F Kt K K K�k K KX KJ K� K� K�% �" �B� � � � �k � � t � � � � �� � � ��k � � �� �� �� �� P P P U� U U U�k U U U� U� U� U� M t 3 $ � . < J � t % % '< Z� Z \< \� % % '< Z� Z \< \� / / 1< ny� ~� ~ ~ �t � � �t �� �� = = = Bt B B B�k B BX BJ B� B� Bt / / 1< w� < � $ �~ � 7 t � � b�f b bt d� dJ dt < � < � � � � �t � � ��k � � �� �� �� �� a t � � t �l X J � � t X t �l X J � � s <* q� �*�'J. � $ � . < J � t $ � . < J � t X � � � R R R� RJ R R R R� R R� R� � � �� �J � � � �� � �� �� �~ �� �~< t � � -. " � � < �< t � W � < � � . v� v v {t { { {� �~ �� �~< t � � �. t �k � � t z X X pz p p ut u u u� Q t d t t � W < < (� ( (" ( ( ( (� ( ( (� ( (.*�'03V (� ( (" ( ( ( (� ( ( (� ( j0 j j" j j j j� j j� j� ] ] ]" ] ] ] ]� ] ] ]� ] ]. ? ? ?" ? ? ? ?� ? ?� ?� ] ] ]" ] ] ] ]� ] ] ]� ] ]. 2 2 2" 2 2 2 2� 2 2 2� 2 20 2 2" 2 2 2 2� 2 2 2� 2 H. H H" H H H H� H H� H� ew e et e� e e e e� e e< et eJ e� e e. t � . � X � � . . � X � � � � �� � � � �J � �< �t � �� a J � � � / � < � � � X � < � � � � t � � � x� . x x" x x x x� x x� x� x x x" x x x x� x x� x� �y � �$ � � � �� � �< �t �� �� r r r$ r r r r� r r< rt r� r� . f � X � t � � " � � � J � � � .� kXt�X t.�5��a�.5 a�t5 ^J5"<� T`x<DY ��J���J� �c M�K��g<YX ��g�Yf�KJ�� J � � < � � \ p � � . � r� � J X � Jw�tvJ Y ;K / � �f . � � � � � v t � t � < � � < � � �e � � s � � t � � t �e � � � [Ȃ� X . � � t J � � t � J � � . < < . y . . � X � � . . � X � � % � t < � . " X < J # � � �PX��� + J � � . < � J � � . < �\ X-�� �v<� � k �_X� X� �_� � � �_<t� � r= � . � � + X � �� � < � � < � oX��a<�� 9� f �a<9� < ; ; X t �_ � � �1 � �_� J � � t � # � � �a� � � wt " $ � . < < . $ � . < < . �a9� �a<9� <�a�� Y� �~ � t �# � ��x.�x<�6� f<:LY�� � � J � � � J r L Y K �JzJP� � � J � J � � � Z � J L Y K � = JK �Y � J � C � � . % g- � � � � � g . � < _ yf C f J � J MfX��h<�� <�� �h<<�<;W � <�J� �..J�. � X � � � � � � %< )J )<� �/�.. l� X � -� - 0� 8. 8 8 : V -� - 0� 8. 8 8 : B0 B B B CJ C C�fX C C C�. C�fJ C. C�. CJ C�f C C� C� Q� Yf Y Y [X f< jJX � �h�-� � . X � �h� f� <� $ t < . .J . o� w. w w w zJ �X � � �� � � �f �� �X . .J . o� w. w w w zJ z� � �t � � �X �< �J �� �� X � X � ^ q� � � X � � � X J &%� ( & � J < < f � < #�fJ # # #� #� #� #� n n pX p� n n pX p� / / 1X /� / 1X �h�<� �h<<�<� � � ' � J < � y y�f y y y�J y�fX y. y� yJ |� | | �� � � �� D P� P P U� U U U�f U UX U< U� U� �� �( g �( � � �� � � �< ��fJ � � �� �� �� �� Z Z Z _� _ _ `< d�fJ d d d� d� d� 9� 9 ;X 9� 9 ;X G� G G L� L L L�f L LX L< L� L� LX�h�X � & � J < < f & � J < < f � �� a �� � � �� � � �� � � �% � � � �� � �� �� �f \ \ \% \ \ \ \� \ \� \� \� q q q$ q q q q� q q q� q qJ 2 2 2$ 2 2 2 2� 2 2 2� 2 2H 2 2$ 2 2 2 2� 2 2 2� 2 <J < <$ < < < <� < < <� < ~L ~ ~$ ~ ~ ~ ~� ~ ~� ~X < < <$ < < < <� < < <� < qH q q$ q q q q� q q q� q qJ R R R$ R R R R� R R� RX I I I$ I I I I� I I� IX �h�# �� � �$ � � � �� � �� �� � � �$ � � � �� � �� ��o�� KX��X�� XJ�rfK/�/s����X�XJ�t � . �t<,� t�uu uX ..��)KG yEA Y �<Y� H� Y ��� J Y ��� J Y ��� �}X!�J� �}g ��}J��� � K, uf �8 < L M �}8gu��<0�2 zJ�X � K; �X OX�X�XX�q �. �q�/��#�t�.J-� ..�XK9 ? f t � �4 O < X � - = Y = � t. H ���� J � X j<7= ���� < t.�� tJB� � XK�=3v �Y�� � � J � K I J � � � �; K Lr K � t J �f� ?.; � � J X L #�L Y < K�pYf�K���. k� X � �x� b< � X � � � X � � X���E�1<\� t � J pt X� � � X � � < �^X �!. �^J . �!. J �^ �! J � � �=�I��^ .�!M X t < X � & t � � q t � � < < � ) L�LHL X 7� �(f..y. Xt � � � �Y YX7� � ;K �f..w.� Y J � � � < J q t � � � � < J " X < J � �^ X J �! � � t �^ X J �! � t J � � � . r � < � � . " � � �=�o�K5v <O E$w � u � J � t t f X <E� ��XX ..g� � � � � p; w f��* �$ tA� �X .. m� � ( $ � . < < . t � $ $ � . < J � t���: �[qJY7 � � . � . . �kX �. �kJ . �. J �k � � �;f � t � �R�;<(� � kJ J � � � <2Y s Y � � [X8X� JJ � < � < . � � �k X J � �; � "�8a� � X ��J� Y . �( tGY � nt � tt < < t � . � X � � t t � . � X � � fs K � . � �k �J �kX . � J � " � � � � W < Y � � v � �k X J � � X $ � . < J � . $ � . < J � . u $ � . < J � 0 $ � . < � � $ � . < � � $ � . < � � $ � . < � �7 UX�� � � .ttGB Vw�JY g s�Ag<X � X � s � � � � � � �~AX 'J0M � X � � � � � � t f � G @ # t�� G�� s�A=<. � < � s � � . < �jX �. �jJ . �. J �j � � � f � # t ut Y; J % � gt� � K ;K � �< ��� =�J<�~�.. �~� K> � X X P�A� /J . �j �J �jX . � J � fG @ # t � g" � � = I K Y � � J � �� uJ ^ � > [J u� J � 20[��~ s�Ag � < � < � t �j X < � � � < � o < � � < � < PJ 0�A Qt /J < x�AX � . J < X f t � *�f *JJ �< �F�@t<� �}��t�t�<3�~?)F @ t Y�� �~X < $ t �� � �~ t �j X < � � X>�kf�� �� �k<�<$:J � ��X =\� 0 �8 @X z� PX z �v �a� � � �i �J �iX . � J � � XK � � < �f� �% J% � �% z� 0 \ ~ @ u �Jt�C(. � ��. � t � K �KsK � < t< � � t t � X� K W > I K �!�]!`� Y ;K!v<� ��~ @ u�<Z� � p� < � � t � t �h � � ��f� �<X . � X t f � � � < � J � � � � < � J � � � J < � � � � �j� J$� �� � f � " � � � " � � � " � � � z " < � � . r � f � # < X � P� 0�A Q< � � f � � � � � t � � � � � t � �k($�� �X�� �j� �k<�<�k�� Yf#� �X��JK jK6 r �!\ � X X�� � #J � zJ l . . . zJ e� � X X��X Y t � tf X X X ��� Y � � zt < ? < � t � < X � < J% � d� t � < X � < J t � < X � < � �..gX Y'J�lzXX�;X� Zx�Hg X � �O O� ��lJf ..lJ x� < � JJ> � .O ?M < � �e X � J � t f � X� r� < � r t � X < J Xx� � � t x� " X < J J � � � . J � � � �bt�$X� �st sJ Xs</M X=� � J X t � K < tX X t� . t<7 w Z rN� � . L r � � t Y�!n� � � v r � � � t # � X �| Jg] *���Vt fXfEuX WX '�L � o�FJ �tX J � <Y �tY2Y�tf�J��J� [�JJM \ ~0 J L�<�Ȃ�f� K K�pYK ��"��X��ׄ� �e�=�<<� @� t XJ� X K ;Y . = X�X� �~x��< �K� f �dY�<X � N 81> �� � JJ �J � �G = Z � X!� < � Mq J �X����t�. �. # � � � = � �cYX � �d� �<�d��XK0� �d��X��uX WX � < � < �}�X�<.�<� �<.���<��< �t��<t<< ��<t<< ��<t<<<<� �S� N� �Yj�0V<et���G>I� � ����. � Y s g��� � . . �` � t �`� . � t � �r � . . �` f � t � + t �` � � ��|�� ' J < � �sJ3 L.X,#� I �t'� � �N�.-J �Y u= <�}�����<t<< � �tX � ���a f � t� & �s ���a � <J �a�. � <t�a � � # � Y��,��� l. � . �2 � � � ' t � � < � w < � < � q < ��| ��x���$�<tJ�f � <�<J � t � � X t t f � X t � . f � � � < t J � # � < J � . t # � < J � . # � < J � f �~ ���a � J �a�. � t# J & � I Y =��a < � �/6� T� K? p K h,�,I �Y��a � < �a�.� t# u��I� =��a� �aJ.� t�a � .t�"!J � Kr`�a .� uX"y��<��y�t�a �<� �Xt�a <� ��..�X�t�y..�X�t�..�X��� � # � < J � t. J � � < J � . $ � � � � �~" Y��x" Y�� ��wt�a J � ��rXXW.W�XX � <<t�a � � �Xt�a � � ��cX�X � ��S������ X��J�X\< �<< ��a �J � �X q<< << �tf�X <. NJ�� <J�}#� <J� 1<� � " � � � �~#��� � # � < � � �~#���k#� <J� � " � � � # � < � � �~�� h���_��Xy��&.t�X u#�J��.YJ��J�� �#�J��. "���"��t� x#�J��.#��f<�.L#�J֞�"��� "��� o"��� "�JX h"���"��� "���"��� �~��6��ւ� �~X=�~X� `���f Ys K�XJ�}���gsue�;KsKWY<tt � � < � �K % R xJ { K� <�8h- �P � �h $ xJ K o< � t �t � � � � � K t Y "� ]� K " X s� L < � X w� J X � L X�X�u!5X�� �j�t� �~O �ptJp<^��9� �u� .-�� t X�uff �~J KqM�] ��"t�!�iX -X. ��. � f t �\ �-��".�t�X�t� �jt $&XX 9L XW c � �\tf��#. �\�. �#�� p< �$ ��K% �q K � / E W c w l � � �� �$g Mg ht��.Y [.tt� �K z� B.X=/ X � = �R Yg�- $ X � JJ 9 < J < t � t f <���R�-J��RY<�-�R<J�- ...�<�R��X�-��RJ f�-�K /u#w �wX < / �/ X < X < � $ X � JJ � < J < t � t f <���R�-X��RY<�-�R<X�- ...�<�RX�X�-��RX f�-�K /u!z�/B X < X X = $ X � JJ H < J < t � t f <���R�-X��RY<�-�R<X�- ...�<�R��X�-��RX f�-�K /u z�/B X < X X = $ X � JJ H < J < t � t f <���Q�.X��QY<�.�Q<X�. ...�<�R��X�-��RX f�-�'K 3o]7�J�X X X �uX . < J X t � t f X���Q�.J��QY< �.�QtJ�.X ..�Qf� �.���RJ f�)�Hv �v<J JX=/ X � = �U Yg�* $ X � � � � � J � ! u � � .A� �� J.. Y� t �S � �, t p� < J J t t t f � J�.�UX�*J��U�<J�* �� � � X � �t yb�< X ��U"�X�*��UJ ��*tLr� X X �f J t �S . �, J !J .r � < . � 0 �K �oA X X XH g = Y - r � J �1 <. �K" �oA X X X g = � - � � J �� <. �Oo�# X X �f J t �S . �, J KJ .H � < . � 0� ��yt�: � < � � �/ X � = �S Yg�, � X �� w� � t � < t J � < J J t � t f J���S�,J��SY<J��X�,��TJ f��+� X�yt�9 � X � � �Q �.J �Q< . �.5 � / X � = �R Yg�- � X ��Xr� � � � � t < J < t � t f <���S�,J��SY<Jh�X�,��SJ f��,"�K7s �st < � X . X? = �/ X � = �R YY�- � X � J..uJ < f uf � J � � < J < t � t f <���R�-J��RY<�-�R<J�- ...�R<�X�-��RJ f�,��yt�9 � < � � �/ X � = �R Yg�- � X �� w� � t � < t J � < J J t � t f J���R�-J��RY<J��X�-��SJ f��,�XK� < Ko.Y7 X=/ X � = �N Yg�1 $ X � � X � � �� = � <= X u�X � X � �N Y �<X�1 J�M�� t��2��� = �=Y J f J ��K= JM�M�� /�2< !t < J < J �� < � �� = o� < J J t t t fJ J���N�1X��N�<X�1 �N�� �2 " �0�Mf�� =�2� �M<=�2< ;"; � 0�MYg �2!,� J�� �� =c �� = f-� � � � J ��Mg�2�MYK�<J�2ׄ�M��1 �N�@2 �2 .� d�� � J � X � � J � � �t� c�< K�M�J�2 �MJf � f �2 wt �M � "�!�X `�2< �MJ=�2 �M<=�2<� �M8����!�X `( �� `X X ��1��NX � I$# �2 � W � XRt�\t�?Xt � J � yf �C# �Cw<�Y� � X � s K � �� � � � � s = � � � t < � � � � X � � � = � � Xqt5<� K� � � Y < � � �K . �4 # < � � � �K � �4 � t < � � � � � J � K I J � J N ~ N t Z L � >JN�K�L�Ju�3/X���LJu�3 $ � � < J X t � t fJ X���M�2J��M�<� �2 � Y� � � �K � �4 � � < � !f h� X � ��M��3/X��=�L� �2 � ��M�3J�J�M.�X�2��MJ � �2 kXt�_t�X �� � fgt . � � f 5� � t = t o.�.�X �� � � f .A � g � � � u M v �t&RA� -,T<uM� -<< g Q < �,X �& 0 < � � -<<2&f i � t� sY � � 1 � = � � � � �t V� f � Y < � �H < � �7 t`��Jf�� ��5 A t �I � �6 �It X �6 �� �Jt$�5 wX EX �J���5 w� @ � � �-9tGJAv M� J&j �J�� YT �5Ȃ �J��5 hXt �t�t�t M� -<<j7J7JJL&V;� f Ntk� � � � X �� \ o Z � � � � %� fX � < P � 6 I= �IY��7� �~. � X � ��* � < X < �* � � � �H �7J �H� . �7 J u �t. � � � < t X � � � 1 � . � � � � twX#g �# X �� � � � �G . �8 � � � � < t J Z � * � J � * � t � � � �Z � � � � � � K � � u ; K u � � � J J t t t fJ J���H �7J��H�<J� �6 � � < � Y' �I�.�6 w � � < �� � � � < w < zf t � � t �G � �8 � X M�If�� ��6�I�� �6X �H.�6 w 2X��IJ � I�� YT �6Ȃ; �HX��6tv�t � t�k vt�>F � X � K � t � �[ . �$ J �8x D�J.gX � . J � K � � �� qXt � �nt/:F � < X � s � �t � �<#. Z� . J � � � � t �[ . �$ JI � �� �= �\�< � t �[ � �$ t e�; X � � < wf" _ # X �k< dJX X$. dXt�St��K6 p tp. .X= Y�?�XYg�' $ X � � ���X>� J. Zf J J J t � t f J���X�'J��XY<J��'< X�X�X��X�'��XJ ��'fK: �X= Z��. �K=u .u. JX=/ X � = �W Yg�( $ X � ! � ! � � = �X � ; X ^. � g � J � � D =8 � � � t � K�WX f��(� J mX � �� � J t � e J X J t � t fJ J���W�(J��W�<J� �( J � �� p �s�<�W��X�(��WJ � �( ��� ut!)KA �X= Z��. �K=y�C �. c X=/ X � = �V Yg�) $ X � � ����W=�<<�( X.. t� < J J t t t f J���W�(J��WY<J��( <�.�W<�X�X�(��WJ f �(ttt K<y�C �. c X=/ X � = �V Yg�) $ X � � ����V=�<<�) X.. t� < J J t t t f J���V�)J��VY<J��) <�.�V<�X�X�)��WJ f �(ttt K>y�C �. c X=/ X � = �V Yg�) $ X � � � g�� �V=�<<�) X..uf�v X.. lf < J J t � t f J���V�)J��VY<J��)<�.�V<�X�X�)��VJ f �)ttt @ "K;x�D �. c X=/ X � = �V Yg�) $ X � � � �=����V=�<<�)�VK�<J�) X.. q� < J J t t t fJ J���V�)J��VY<J��)<��V��X�X�X�)��VJ � �)ttt � .�; �. c X=/ X � = �U Yg�* $ X � � � � � t �T f �+ J � � �U K �<J�*� y� t � � < J J t � t f J���U�*J��UY<J��*<�U��X�X�*��VJ f �)ttX�t�zt0 � X . �I . . X ZvB�#Jof< X � X J � I � �R X � �- �����zt� � X �� J t �R . �- J) ��s= � . � \��<`�JJ m. � t� t � � � �R� �-< �R X �- tX iXt�. �st�8 � X � � t �P f �/ J% � / X � = �Q Yg�. � X � X J��_� �� j� <3 � v � L X uX J <(K � Z SJBzf� � d� � � � � < J < t � t f <���Q�.J��QY<J�. X�Q��X�.��QJ f��.���rt�7 � X � � � �N f �1 J% � / X � = �O Yg�0 � X � J,J� O�&� � < � � f � �N . �1 < � � � � K � � { y.2 K d� J)� � � � t � � t �N � �1 � ^f � � j J X J t � � f J���P�/J��PY<J�/ J�P��X�/��PJ f� �/ t�f �vt� � X < �< � � � �M f �2 J= � / X � = �O Yg�0 $ X � J&��J r< � X � �+ J K � � � < qt � � � � � �M . �2 J � � � � K � � t w�* L ���J �) � [ � t � � �U� <� ��> � = [� < � w t �M � �2 �h��NK�< �0�OfJ�0t� � t � � < � � � < J J t � t fJ J���O�0J��OY<JX�1J� ��N<� �0�OfX�0t�It�O��X�0��OJ � �0 t � ��<rt�< � X � f t% � �L YK�3 � X J�.`t � �K f �4 �� � � X X \ �(� X = Z �tX< � � < � rX � � � � Xftpt�; � X � f �% � �L YK�3 � J=J���J � �J f �5&� � \t < < w X X �-� � = � � X � � � � � �J . �5 J � � � � K � � { y.2 K S� J � � < � 3� �K� �4X�Kt< �4 � f � � � � � t �J � �5 � N� � � f =�K �4 � �� nXt �{� XX hJ �X</X��P<YX�/6+X� fX� �z< XX � �Ot. �0� = Y- {y. Q d�J� � �f��e J�H��P��/J�P�Y<J�/ �N<� �1 Ge�<�PX�X�/�P� � �/J(� K(!L J YZ t YY(vt YY< S t YYv<��K �D#�; �D� J �;� �DJ< �;t <u�~J�Xt�X y<tX : � �C��<J= �C# �<� �C<< �< It J<v�~� t �<�f � � < � � : - �: J f t J < �J � �~f �RJ�X��-�RMJ �-<J��<tX `; � �D �;� �DJ< �; ;<K tv[ �~< u�JL�~ ;K � �~�X �JJ ���J �~�f�Xr<tX @< ` �D��;J= �D# �. �; ;JK <J<v� : >:J��~��~J�f�~<C tC<� �t� .J m<tX = �K �B#�<. �C� J �<� �CJ< �<t <u� � �~� 1 �t J X < J X J � J t X < . �~J �� X � � .y<tX 0> K �B#�=. �B� J �=� �BJ< �=t <u� � �~� 1 �t J X < J X J � J t X < . �~J �� X � � .y<tX `? �f%� [t. x<�<�< �=�`X < _X!X�[<Yf�$ $ �X x�L ��[�=�<< �$+ x<J<x< <sx< � �� �Z. �%� '��<#�X �X�#t�� <A[Z<&< YX'X � � �) �Y�. �&O� �<�� f�W�� q�# 9.� �<� X �x� �~�X�X �tJ0X4z<P #� s � �Y1�. �& � gW= Y��u< �� �� g K s g% �Y�. �& K � �~��� �}� �< �}� �f\ �@YX+�� � �� Xlf�YJJ�& < Y � =�Y �=�<<=�<<�&X�&� g_ �� >$��X��K�<JX�$�W��W� 0*+it.�&�( h) �Y�.�& `� �Y�� �&J#v' %S� u� sX>� NtX'� �Y�� �& V%t<tXX&v,t<tX *Xt+�*���@�J��Yt�&J�Y��<JX �%� �-� J ��� � X<tL� f�<�X�<�� �Y%�.�'� � X=�ZtYJ�%!_<J� s� # �XJ. �'.� X �w< tJf� �x�&t<tXXt<tXXXX<� � ���g<Ⱥ< L�X�� " �X �� K� <��T�X�~�J �d Zh� �< �L� ��YJJ�&=Y�=�Z �&J�Z<Y=�<<=�<< �&��Y��=�<< �&� � � ��YYY�<X���&�YJYf �&�Y$ �&J�Y��<J.�&�� �~�Z*�X�X�X�X�X�&�Y� � i�X�X�X�X�� �%X`X �~�t ����}XJ A�<K .X �Q � �vt�: � X < �& � � � � � �R � . �- � " % �p�� <�f @� � J � & � . z< P zf t � � � X � � ��}� �XL X</X�=�QYY�.$X�� n� XA � v � L Xu�J(� � � YXf �}�� � v� /� O= �S�� �, t < t X " �tYt � X4t 3<MJ3�....M.��<�-J���Q�.<��QY<<X�.��QJ�X�.��QJ f��,XXt �V �N 2<� 2tht 2p $8 @T NX mf< � � �<q u Y �<� u Y �<zt u Y �<I u Y # # � �<� u Y �<� u Y �<I u Y�|#��=XK""����Hh ..,X �Y �a L< L&. �% ��A�?Xy�_ k� t �U � t �Z �Y��6�r��='V�� ��'�� �Y �v< ( x< 6 xJ � u<J �� Y� �N<8NX <�_ yJ fKWgZ� < Y + � �h f �� o��f ��� =�<�'f<ptk)=t<< 0t��X� -��t �g�� n�)��1(@ '9'4 �v�J��r�Y=Y<<� *�X ��r<X�7�/;=WYeYs�s�tX � � < � R xJ K * m<C {J K� <� <s�8>- f t f � J � � & P& z Y ] [ � ? g \�?< � > I I K � � f� � � . t sf t � � X �� rf v � Y6 H � �S ' � � rt M .�M �otX��KX JqfK rX��={ u!� X�X�u!5X �t?�+ � Yf � zf P Y t Y�1^ Y8 �2 J+ J> X �, � = Ig .. I%IX 7��.f �S<X!/X. �+�s =, <s�8>- f � (�� ( K e = � � < t t t fJ < . � � ��S��� �+& { �. 9 < ZX � � � �GJ � �8 �X to�t�X �f �K �C#�<. �C� �<J �C< � �<< �CJ< �<JJu<�<J�fL[ X t �}< J� �~ �� �}<<� Y�tX .J. v� �}� X�<tX �g K �C#�<. �C� �<J �CJ � �<< �C<< �<<Ju<[ <fL �[� � t �|< J� �~ �� �|<<� Y�tX J v< X �|X X�<tX Ph K �C#�<. �C� J �<� �CJ< �<t <u��| �J�|<��L�~ �~t.� ��|�XtXK u� �� t Kt� ��tX J�}�+XJ-I 5X� tX� �K 7� q� b�#� �'���<tX �< �� �-�|��*��.-I K� k c �� � E \ � V / ;� � � � � � m o � � � � � , { � N � � � � � # � � � � W K � � � � � � � � : � 9 P � � ) � B @ W 2 � � c � w l � GNU GIMPLE 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -mtune=generic -march=x86-64-v2 -g -O2 -fno-openmp -fno-openacc -fcf-protection=full -fPIC -fstack-protector-strong -fltrans -fplugin=annobin __builtin___sprintf_chk __stack_chk_fail __builtin_memcpy sv_type.constprop.0 store_hentry.constprop.0.isra.0 __builtin___memcpy_chk free_context.isra.0 retrieve_tied_hash Ilaststatval long long int version_minor old_parser subtr_ass_amg blku_oldsaveix retrieve_other Iorigargc Iorigargv si_errno keeper __pad0 tbl_arena_next _spent_size Iin_utf8_CTYPE_locale hostent ls_prev close_paren lex_stuff XS_Storable_mretrieve xpvgv free_context Istatcache Icompiling store_array Idbargs new_perl Perl_newSVsv_flags blku_oldsp retrieve_integer sub_error_count xpvhv PERL_CONTEXT _asctime_buffer Inumeric_standard prevcomppad Ie_script Perl_newSV_type xhvnameu_name sv_u PL_sv_placeholder Ipreambleav IDBcontrol memset xpvio xpviv tbl_max s_dirty Perl_ptr_table_new si_tid Imy_cxt_size blku_old_tmpsfloor Imain_root Perl_SvREFCNT_inc accept_future_minor xcv_outside ver_minor allocate_context seen_null blku_type _PerlIO __locales he_valu Iutf8_totitle _spent_struct named_buff want_vtbl_hintselem h_length op_first Idoswitches _netent_size thrhook_proc_t next_branch Perl_POPMARK Perl_newCONSTSUB block_eval s_port __in6_u in_port_t gp_refcnt prev_mark Idef_layerlist errsv result sv_h_undef saw_infix_sigil Irestartjmpenv save_lastloc Iwarn_locale _spent_buffer Icolors version_major mg_obj je_old_delaymagic fallback_amg multi_end PerlIO_list_s PerlIO_list_t COPHH scream_pos xpvmg Iargvgv despatch_signals_proc_t rshift_ass_amg xio_flags Isharehook tm_mday old_regmatch_state xcv_xsub store_hook nextword Iminus_E Icheckav pad_1 pad_2 Imarkstack xpvnv Idump_re_max_len tm_zone retrieve_utf8str Istatusvalue IDBsingle utf8_substr __u6_addr8 min_offset hook_seen pmop st_atim sival_int Ilast_in_gv real_context Ireg_curpm share_proc_t Ihash_rand_bits_enabled pw_gecos _call_addr long double op_private retrieve_tied_key lex_formbrack SVt_LAST __ch sbu_dstr Irunops Ipsig_pend ver_major _ctime_buffer Icomppad_name Imarkstack_max sbu_iters __bsx network_file_header internal Ireentrant_retint XS_Storable_last_op_in_netorder check_done saved_curcop max_amg_code Perl_stack_grow __blkcnt_t Perl_gv_fetchpv PTR_TBL_t clen Perl_call_method sig_seen xhv_max _protoent_size hent_hek xhv_aux_flags retrieve_byte _grent_ptr _getlogin_buffer xivu_eval_seen __locale_data pos_flags eflags Istack_base exec Imax_intro_pending poscache op_pmstashstartu to_gv_amg group sbu_strend smart_amg re_scream_pos_data_s cop_stashoff sv_store_t s_addr st_size sge_amg Iperldb lastparen si_addr_lsb Iinplace __locale_t xpvuv _pkey old_magicstr tm_min re_len32 IDBline want_vtbl_nkeys sin_amg Isv_arenaroot jump gp_egv newval padname states xio_bottom_gv stcxt_t XS_Storable_stack_depth_hash Iphase is_weak yylen subbeg cos_amg _asctime_size Iblockhooks end_shift Perl_get_sv sbu_oldsaveix _pwent_ptr Iosname n_addrtype lex_casemods lex_brackstack numbered_buff_STORE Iefloatsize PADLIST store_tied_item retrieve_flag_hash Ipeepp PADNAME magic_check sv_type mro_which Iregex_pad retop pkg_gen retrieve_idx_blessed retrieve_blessed bdeparse xcv_padlist_u minmod sp_pwdp Iutf8_foldclosures Ilocale_utf8ness Isv_yes parenfloor store_other Perl_sv_catpv branchlike old_magic JMPENV Imain_start qr_anoncv Istashpad _arch my_perl Ienvgv Iperlio in_retrieve_overloaded Ipadname_const Perl_xs_boot_epilog Perl_get_cv __wchb pow_ass_amg mult_ass_amg Iregmatch_state prev_rex Iisarev Iutf8locale Perl_av_fill tm_mon key_sv op_opt c2_utf8 sa_family_t sockaddr_inarp subcoffset svu_fp yy_stack_frame NV_bytes Idebstash keylen topword destroy_gen Perl_safesysfree retrieve_weakoverloaded want_vtbl_ovrld reg_substr_datum si_stack xpadl_max Inomemok __uint8_t tm_hour do_retrieve firstpos want_vtbl_debugvar Imbrlen_ps Perl_warn_nocontext Idiehook prev_recurse_locinput any_ptr Sighandler1_t large CLONE_PARAMS Icompcv padnl concat_ass_amg lex_repl timespec fake_tag retrieve_lutf8str PerlInterpreter xpadnl_max_named store_flags need_large_oids Perl_hv_common_key_len has_large_oids ILatin1 Isighandler1p st_nlink Iminus_F re_eval_str Iscopestack_ix sp_max Iscopestack_max iter_amg Iminus_a any_pvp Iminus_c want_vtbl_arylen_p Iminus_l Iminus_n Iminus_p Iargvout_stack old_retrieve_array Iinitav retrieve_svundef_elem store_scalar Perl_newSVpvn Perl_SvREFCNT_dec sin6_family tm_yday tbl_items Perl_ophook_t cache_mask Perl_sv_tainted firstchars xpvlenu_rx Imaxsysfd Ilocalizing Isighandler3p lex_shared retval servent _crypt_struct_buffer rxfree ncmp_amg Perl_av_pop pw_name sp_lstchg curly croak_now _getlogin_size nomethod_amg add_amg Iunicode __fmt blku_sub qr_package neg_amg Irestartop ICCC_non0_non230 gofs __mask_was_saved PERL_PHASE_CONSTRUCT Ilastgotoprobe cop_line Isecondgv __locale_struct Isavebegin want_vtbl_vec initialized XPVAV to_av_amg retrieve_ref STRLEN frozen exitlistentry abs_amg op_ppaddr xpadnl_alloc Icheckav_save Idebug_pad __jmp_buf_tag concat_amg lex_flags Iendav blku_oldscopesp Iutf8_idcont flagged_hash tlen3 Icomppad_name_fill my_op IHasMultiCharFold __mbstate_t known_class extra_type tmpXSoff XPVCV Perl_savetmps store_blessed xhv_last_rand recursed mark_stack_entry regnode Perl_PerlIO_write xhv_name_u Iperl_destruct_level si_cxix mg_virtual padnamelist interpreter PMOP Istashpadix Perl_xs_handshake st_uid longfold sp_min xcv_xsubany PADOFFSET sbxor_amg sbu_rflags xpv_cur xpadn_flags Istderrgv xio_page_len xhv_eiter perl_memory_debug_header xhv_riter Iin_clean_all si_type mark_name Istashpadmax old_regmatch_slab __ino_t reg_substr_data lex_super_state _grent_struct xcv_root_u curlym setting my_sv Icustom_op_descs si_prev XPVGV _addr_bnd XS_Storable_stack_depth sp_namp lex_starts Isavestack Sighandler3_t si_code array_call Imodcount prev_curlyx Isortstash Istdingv svt_local clean_context sp_warn Perl_SvTRUE Icustom_ops Perl_sv_2nv_flags sbor_ass_amg CHECKPOINT tagn XPVHV any_av sprintf _grent_buffer aseen sne_amg placeholders last_uni obj_type XPVIO sp_expire XPVIV __uint16_t minlenret Iofsgv TARGi_iv Idelaymagic_gid xcv_gv_u Iunderlying_numeric_obj Icollxfrm_mult tbl_arena_end Isavestack_ix want_vtbl_defelem sockaddr_x25 store_tied SVt_PVAV sin6_flowinfo Perl_call_pv xmg_magic ltagval svu_gp any_dptr intuit Ibody_roots si_sigval hek_len Icollation_ix memcmp tokenbuf op_nextop line_t mgvtbl Iutf8_xidcont cnum retrieve_tied_scalar si_cxstack yyerrstatus Siginfo_t _hostent_ptr sbu_rx xcv_padlist resolve svt_get _Bool svu_iv XPVMG sbu_rxtainted seq_amg div_ass_amg Perl_hv_eiter_set op_moresib xpv_len_u Ipatchlevel Perl_call_sv _pwent_struct nextval svu_pv XPVNV any_gv store_lhash not_amg Ihash_rand_bits sbu_orig _servent_struct do_store __gid_t Iparser xpadlarr_dbg stack_max1 runops_proc_t any_hv Ipadlist_generation destroy SVt_PVFM xpadnl_max Idefoutgv _lower Istatusvalue_posix _pwent_buffer pkg_uncache Iutf8_tosimplefold __ctype_tolower siginfo_t Perl_newSViv any_iv Perl_load_module_nocontext Ichopset Irpeepp oldcomppad sbu_rxres SVt_PVGV Iincgv Perl_newSVpvn_flags si_markoff xpadnl_fill clean_store_context want_vtbl_arylen tv_nsec nexttype sig_slurpy want_vtbl_backref Icurpm_under SVt_PVHV lshift_ass_amg Sighandler_t svu_hash hseen ISCX_invlist svu_nv sband_amg si_cxsubix lex_inpat last_lop sv_seen store_code tm_sec pkg_hide sockaddr_ax25 ptr_tbl_arena SVt_PVIO SVt_PVIV filtered Ilastfd want_vtbl_collxfrm Ieval_start ls_linestr Perl_warn Perl_gv_stashpv ntag_t PADNAMELIST SVt_PVCV PERL_PHASE_START __src xcv_hscxt any_u32 Perl_croak_nocontext __bswap_32 pkg_can _ctime_size repeat_ass_amg op_pmreplrootu Perl_ptr_table_free Isavestack_max Perl_newSVnv XPVUV xhv_rand Ilocalpatches Isv_root SVt_PVLV p5rx op_next __saved_mask svu_rv retrieve_sv_yes copline sockaddr_eon ilen any_op Icurstack SVt_PVMG Ipadix_floor Perl_push_scope si_status recur_sv xpadl_arr h_addrtype XS_Storable_pstore _strerror_size Idelaymagic_euid retrieve_sv_no bufend Perl_newSVpv lex_inwhat any_pv atan2_amg xnv_nv store_hash sin_zero Iopfreehook retrieve_weakref ssize string_readlen _protoent_ptr Iunitcheckav svu_uv PerlIOl XS_Storable_dclone sgt_amg to_hv_amg Isetlocale_bufsize retrieve_regexp flags_pv Perl_sv_setpv_bufsize xpvhv_aux protoent mg_len Imemory_debug_header slt_amg SVt_IV Itop_env want_vtbl_sigelem __blksize_t Perl_SvAMAGIC_on Perl_sv_setiv short unsigned int _spent_ptr Perl_av_fetch bool__amg Itmps_stack Perl_gv_stashpvn yy_lexshared use_network_order offs any_sv want_vtbl_substr retrieve_tied_idx Isv_undef Ipsig_name LEXSHARED retrieve_undef clone_params perl_drand48_t Igensym Iregmatch_slab op_redoop rsfp hash_flags _hostent_struct start_tmp xio_fmt_name svt_len cop_hints __len h_name Ierrors xpvlenu_len h_aliases _hostent_size op_pmreplstart hent_refcount saved_copy lex_sub_inwhat any_uv Itmps_floor Istrxfrm_is_behaved __wch xpadl_id parent_cxt dec_amg int_amg Perl_av_undef is_tainted sv_retrieve_t Ibasetime Iop_mask Isighandlerp unreferenced Isignalhook xpadnl_refcnt keylen_tmp loceol IUpperLatin1 mro_linear_current xio_ofp __value _hostent_buffer cop_seq multi_start op_pmreplroot SVt_NV IDBtrace maxlen pre_prefix op_targ Ibeginav je_ret perinterp_sv resume_state Perl_mg_find XS_Storable_mstore Isv_consts pw_dir lex_casestack XS_Storable_pretrieve op_lastop Isub_generation blku_eval float want_vtbl_isaelem Perl_sv_rvweaken __count unsigned char Perl_ptr_table_store si_cxmax multi_open _kill st_rdev LOOP ILB_invlist SVt_PV get_regexp want_vtbl_dbline REENTR Imess_sv Iglobalstash Imin_intro_pending expect oldloc Icollxfrm_base want_vtbl_envelem copy_amg aclass Iutf8_perl_idcont cx_blk Istatname RETVAL Perl_gv_fetchmethod_autoload modulo_amg xnv_u __uid_t sin6_scope_id blku_gimme XSUBADDR_t Perl_sv_free st_ctim recheck_utf8_validity Iutf8_tofold xcv_root ISB_invlist canonical block_format old_retrieve_hash in_addr_t op_sibparent Perl_sv_magic old_namesv log_amg xpadn_type_u IAssigned_invlist peep_t xhv_backreferences wlen Iinternal_random_state Perl_sv_free2 Isv_no minlen __off_t perl_phase Iin_clean_objs byteorderstr Isv_zero super PERL_PHASE_INIT asiz PERL_PHASE_DESTRUCT in_pod membuf gp_io Imultideref_pc Iors_sv string_amg xpadn_protocv xuv_u Ievalseq Iunlockhook extendable regexp_engine mg_flags retrieve_lscalar subtr_amg Icurstash gr_passwd Perl_markstack_grow Perl_eval_sv _gmtime_struct Perl_sv_upgrade gr_gid want_vtbl_checkcall Perl_safesysrealloc si_overrun __clock_t SVt_NULL ls_bufptr Ibeginav_save __uint32_t Iorigfilename wlen2 xmg_hash_index last_lop_op cop_warnings Icop_seqmax get_lstring op_pmtargetgv form_lex_state Istatgv Idestroyhook msaved st_blocks max_offset GNU C17 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -march=x86-64-v2 -mtune=generic -g -g -O2 -flto -ffat-lto-objects -fexceptions -fstack-protector-strong -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection=full -fwrapv -fno-strict-aliasing -fPIC -fplugin=annobin sbu_m sbu_s Perl_safesysmalloc save_curlyx Icomppad sub_no_recover lex_dojoin retrieve_code xmg_u gp_cvgen first_time av_hook Perl_av_store xcv_file Perl_sv_bless SVt_PVNV itervar_u gp_flags xiou_dirp _servent_buffer paren_names Iregistered_mros si_uid pw_passwd Iin_some_fold sqrt_amg lex_allbrackets opval Icurcopdb block_sub membuf_ro pos_magic gp_file_hek Perl_hv_placeholders_get sv_refcnt sockaddr_in6 __nlink_t tbl_ary mro_alg sband_ass_amg xav_alloc retrieve_vtbl si_fd nparens Perl_av_shift xpadn_refcnt scmp_amg Ieval_root old_eval_root storable_free named_buff_iter st_gid Idowarn yychar Ifirstgv rshift_amg mg_moremagic op_pmoffset xhv_name_count op_pmstashoff Inumeric_underlying_is_standard PERL_SI MGVTBL op_static pseen MAGIC Perl_sv_newmortal Itmps_max want_vtbl_pack sockaddr_ipx Ithreadhook blku_givwhen gr_name op_type Iutf8_perl_idstart Perl_hv_iterinit sublen blku_oldmarksp xivu_iv _netent_ptr want_vtbl_regexp Ipadname_undef preambling xhv_mro_meta Inumeric_underlying _upper cx_u output IDBcv trie Ilockhook __ctype_toupper Perl_newRV keyval _xnvu retrieve_netint xio_lines_left Perl_hv_riter_set compflags sockaddr_iso want_vtbl_utf8 Perl_hv_ksplit Iin_load_module xio_page Perl_newSV sigjmp_buf pow_amg want_vtbl_hints tm_isdst div_amg Ilaststype __ctype_b h_addr_list Iutf8_charname_continue in_my_stash want_vtbl_regdata xpadn_len _strerror_buffer add_ass_amg re_pv dummy Iunitcheckav_save si_stime Perl_sortsv lastcloseparen short int ifmatch Perl_mg_get Idumpindent Ioldname preambled klen_tmp op_code_list xhv_keys itersave sbxor_ass_amg IAboveLatin1 Iutf8_mark _servent_size si_signo IDBgv Perl_sv_2bool_flags __names sv_any blk_u xcv_start accepted gvval IWB_invlist olddepth Iutf8cache _localtime_struct max_recur_depth_hash _bounds prev_eval Ipadix defsv_save want_vtbl_lvref _netent_buffer xcv_stash YYSTYPE _xhvnameu xcv_gv cop_hints_hash tagnum Icustom_op_names lex_sub_repl sle_amg vtbl_storable xpadn_high re_scream_pos_data hek_hash hclass _ttyname_buffer re_len Iknown_layers _netent_errno Itainting Icurcop Istack_sp __ssize_t any_bool regmatch_info_aux PERL_PHASE_END Icollation_standard __glibc_reserved want_vtbl_taint lex_defer xmg_stash Iorigalen sbu_maxiters sockaddr Idebug refcounted_he Icurpad store_hentry pkg_fetchmeth __time_t st_mtim want_vtbl_uvar s_proto sbu_targ __dest logical get_larray Iforkprocess lex_brackets xio_top_gv Iutf8_tolower Perl_newRV_noinc keysave blku_oldcop Icurstackinfo retrieve_lvstring Istart_env lex_fakeeof lex_sub_op sv_old_retrieve Perl_sv_cmp stashes Istashcache classnum xnv_lines mult_amg want_vtbl_packelem PerlIO_getc p_aliases _netent_struct in_my next_off xivu_uv sin_port Imodglobal Perl_PerlIO_read sockaddr_at attached aend regmatch_info_aux_eval Perl_bytes_from_utf8_loc xcv_start_u scalar_call want_vtbl_env basesp Igeneration IGCB_invlist Istrtab xpadl_outid xpadn_low block_givwhen regexp_paren_pair crypt_data pprivate cv_flags_t cur_top_env clean_retrieve_context xpadn_typestash Iin_utf8_COLLATE_locale state_u PERL_PHASE_RUN _sigfault op_spare lex_op st_ino cop_features __pid_t parsed_sub op_last Perl_free_tmps attach proto_perl want_vtbl_regdatum xio_type yylval Perl_sv_derived_from sp_inact sockaddr_dl magic_write xav_fill hent_val Perl_sv_2uv_flags Iorigenviron Idelaymagic_egid gp_av ftest_amg optype scream_olds mg_ptr maxpos Perl_hv_undef_flags get_lhash sa_family cloning ptr_tbl Inumeric_name lazyiv _sifields Perl_av_extend SVCOMPARE_t SVt_REGEXP Ipsig_ptr gp_cv xgv_stash netent tv_sec retrieve_scalar tm_year blku_u16 Iprofiledata sbor_amg __sigset_t gp_line Imainstack Icurpm op_pmflags st_blksize xpadn_ourstash ptr_tbl_ent _hostent_errno op_slabbed scompl_amg Isubline Iargvoutgv Iwatchaddr Idefgv hek_key PerlExitListEntry xio_bottom_name gp_form Perl_newXS_flags Ireentrant_buffer hent_next check_ix op_flags Iunsafe tm_wday Ihintgv store_ref sockaddr_in retrieve_lobject __jmp_buf IDBsignal Iutf8_charname_begin Ilanginfo_bufsize blku_format __dirstream sin_addr IXpv Iregex_padav attach_hook blku_loop cache_offset wanted pw_uid _timer Istrxfrm_NUL_replacement IInMultiCharFold je_old_stack_hwm sig_elems gr_mem Ixsubfilename gp_hv Ipad_reset_pending dfoutgv max_recur_depth sv_retrieve _sigchld xcv_depth malloced_classname Itaint_warn self Imbrtowc_ps pw_shell si_next want_vtbl_nonelem _syscall Iexitlist Ilanginfo_buf Isubname any_i32 Ihv_fetch_ent_mh UNOP_AUX_item svt_dup xcv_flags Perl_sv_setiv_mg Inumeric_radix_sv Perl_sv_2io globhook_t xcv_outside_seq Isplitstr xcv_hek svt_free sockaddr_ns long long unsigned int si_addr old_len want_vtbl_pos Ibody_arenas checkstr _grent_size Perl_hv_iterval keybuf SVt_INVLIST want_vtbl_mglob retrieve_hook_common Isortcop sin_family Perl_sv_magicext Isignals sbu_type si_pid isutf8 mg_private dupe je_buf lazysv Iwcrtomb_ps Itoptarget Istrxfrm_max_cp Ierrgv Perl_sv_2pv_flags inc_amg retrieve_sv_undef svt_clear PERL_PHASE_CHECK nexttoke hvname mbuf2sv Itmps_ix Isig_pending substrs any_svp intflags destroyable_proc_t Ifdpid xpadlarr_alloc ival any_dxptr n_net to_sv_amg where_is_undef Perl_croak_xs_usage Perl_Gv_AMupdate op_pmtargetoff Icollation_name Iefloatbuf to_cv_amg magic_vtable_max _pwent_size oldval any_long xiou_any ITR_SPECIAL_HANDLING_UTF8 lshift_amg Iexit_flags c1_utf8 repeat_amg Icurlocales Iglobhook sin6_port xio_top_name IPrivate_Use nettag sv_store modulo_ass_amg Iptr_table Icolorset Perl_hv_iternext_flags __jmpbuf Ifilemode __dev_t Iexitlistlen sockaddr_un numer_amg op_folded Idelaymagic Imarkstack_ptr use_NV_size cname block pw_gid tm_gmtoff prev_yes_state XS_Storable_init_perinterp s_name _protoent_struct forgive_me op_comp gp_sv svu_array retrieve_hook whilem IInBitmap mother_re __val n_aliases _sigsys extflags xio_fmt_gv xpadn_gen Perl_sv_reftype cop_file Icurstname cx_subst __u6_addr16 Isv_count svt_set Idefstash Itainted init_store_context boot_Storable Ibodytarget oldoldbufptr xav_max xiv_u retrieve_double mtype _protoent_buffer st_mode savearray _xivu stcxt leave_op flags_len Iutf8_xidstart re_eval_start perl_debug_pad Istack_max cache_gen svtype init_retrieve_context st_dev __u6_addr32 je_prev want_vtbl_sv Iclocktick Perl_sv_2iv_flags __syscall_slong_t IXPosix_ptrs IDBsub spwd reallen Iutf8_idstart je_mustcatch numbered_buff_LENGTH yy_parser block_loop op_savefree Iscopestack Iformtarget pad_offset mro_nextmethod s_aliases lastcp Iconstpadix multi_close stat herelines Imy_cxt_list IPosix_ptrs xivu_namehek reset_context _ttyname_size sin6_addr Perl_ptr_table_fetch Iwatchok is_utf8 PerlIO_putc Perl_av_len p_proto Perl_sv_2mortal want_vtbl_isa svt_copy stag_t xnv_bm_tail sival_ptr Perl_hv_common mark_loc si_utime xpvav Isrand_called undef_special_case strlen regexp_amg __mode_t sp_flag Ireplgv sa_data Ibreakable_sub_gen rsfp_filters Iin_eval suboffset __sigval_t _servent_ptr lex_re_reparsing Iutf8_toupper Perl_hv_iterkeysv linestart sig_optelems xhvnameu_names old_cxsubix Icv_has_eval asbytes mg_type aptr store_regexp xpvcv Isetlocale_buf numbered_buff_FETCH Irandom_state retrieve_vstring Iscopestack_name retrieve_tied_array si_band xpadn_pv Icomppad_name_floor kflags Perl_pop_scope Idelaymagic_uid Iwarnhook _xmgu _sigpoll mro_linear_all xio_dirpu Iin_utf8_turkic_locale cur_text pre_06_fmt blku_oldpm Imain_cv <artificial> /home/.cpan/build/Storable-3.25-0 /usr/lib64/perl5/CORE /usr/include/bits Storable.xs inline.h byteswap.h string_fortified.h stdio2.h <built-in> Storable.c struct_stat.h intrpvar.h av.h __locale_t.h iperlsys.h string.h handy.h perlvars.h sockaddr.h grp.h struct___jmp_buf_tag.h dirent.h __sigval_t.h util.h overload.h gv.h pwd.h /usr/lib/gcc/x86_64-redhat-linux/11/include crypt.h struct_timespec.h netdb.h types.h mg.h perlio.h /usr/include time_t.h regexp.h cv.h cop.h hv.h stdint-uintn.h pad.h parser.h /usr/include/netinet __sigset_t.h reentr.h proto.h perly.h mg_vtable.h socket.h sv.h /usr/include/sys __mbstate_t.h siginfo_t.h /usr/include/bits/types stddef.h struct_tm.h perl.h setjmp.h shadow.h in.h l �= U�V���U���U��V �= T�S���T���S �= P#P �= T �= \ > \ 3> \ b> T`gT b> V`jV e> Q t]dQ �> #S �> 3U3LVLU�U�U�V �> /T/KSKU�T�U�S �> 3Q3N\NU�Q�U�\ �> 3R3R^RU�R�U�^ �> XP]PU�X�U�] ? P!(P �> *_+x_ �? DUD[~�}�[��U���U��^���U���U��^��U��^��~�}���^��U��^��~�}����U���^��U��^��U��^��~�}���^���U���^���U���^���U���^�� ~�}�� � ^� � �U�� � ^� � �U�� �!^�!�"�U��"�"^�"�#�U��#�#^�#�#�U��#�$^�$�%�U��%�%^�%�%�U��%�'^�'�'U�'�3^�3�3�U��3�3^�3�4�U��4�9^�9�9�U��9�:^�:�:U�:�:^ �? RTR�S���T���:S �? [Q[��Q���Q��\���Q���Q��\���Q���Q��\��Q��\���Q���Q���Q��� \� � �Q�� � \� ��Q���Q���Q���\��Q��\���Q���\���Q���\��Q���Q���\���Q���\���Q���\���Q���\�� Q� � �Q�� � \� � �Q�� � \� �#�Q��#�$Q�$�&�Q��&�&Q�&�&�Q��&�'\�'�'Q�'�(�Q��(�(\�(�)�Q��)�)\�)�.�Q��.�2\�2�4�Q��4�4\�4�6�Q��6�8\�8�9�Q��9�9\�9�9�Q��9�:\�:�:Q�:�:\ ,A W]��]�� ]� �]��]��]��]��]��]� � ]�"�"]�#�$]�%�%]�&�.]�1�5]�6�6] �? -Ve�V��_��V��V��q ��V��q ��V��V��q � � V� � _� � V� �q ��P��V��_��_��V��_��q ��_��V��q � � V� � _�#�#q �$�%_�%�&q �'�'V�'�(_�(�)_�3�3_�8�9_�9�:V �@ \V��V�"�#V �Q ] 5s� AR 7] �C EPE�V��P�� V��V��V��P��V��P��V� � V� � V�&�&P�&�'V�'�'P�'�)V�-�0V�1�1P�1�1V bA !\� � \� � \ bA !\� � \� � \ �O ?_ �O v q � v ��~ � C \� � \��\ C \� � \��\ �J \ �J ] �J s� lK ?_ lK v q � v ��~ � P ?_ P v q � v ��~ � �P /^ �C B_�� _��_��_��_�'�(_�1�1_ �G `_� � _� � _��_� � _�&�'_ �G `_� � _� � _� � _ S $ &� S v( S s� �W R ?�� �W ��u � ? ����~ � �W R ?�� �W ��u � ? ����~ � �[ Q F�� �[ ��r � F ����~ � !D �� [ Q A�� [ r � ! ��~ � xN ��� $ &� xN v( xN s� OX QN�� OX r �) ��~ � W R I�� W q � ! ��~ � �Z Q A�� �Z r � ! ��~ � �U 7\ dZ /\ �I �� �T /\ �J ��� $ &� �J ] �J s� 3Q 4\ U 7\ Z /\ kE PQ �L 8� �L ��� �L s� pU /\ 6J 8� 6J ��� 6J s� K �� K ] K s� �P 4\ �S 7\ mT 7\ V 7\ sV 7\ �V /\ �N 8� �N ��� �N s� �X 7\ Y /\ (F P �[ /\ @\ 7\ �I (\ �M 7\ O 8� O ��� O s� �Q 7\ �R 7\ iY /\ �Y 7\ �\ ;U;�V���U���V���U��� V� � �U�� �V���U� �\ T �S���T���S �\ Q h^h��Q� �\ �0���\��\��\� � 0���0� �\ �0���]��]��]� � 0���0� �] �\��\��\�� \� � \ ^ �^��^��^�� ^� � ^� � ^ �\ �0���_��_��0���_��0���_��_�� _� � _� � _� � 0�� �_��_��0� �\ ��, ���, � � �, ���, �\ �� ��� � � � ��� �\ 1^1��Q����Q�� � �Q����Q� �\ �S��S� � S��S �\ U�V��V� � V��V �\ g\gp|�p�\��Q��qx���P��v ��v � � \� � P� � \��Q (] P�^��^��^��^� � ^��^ ] P�]� � ]��] {] "P��P��T 4] P� � P� � P �] ] �] \ F_ P d 7_ d } q � } �� � td ;_ td } q � } �� � 9` �� 9` \ 9` s� �` �� �` ^ �` s� �a 0_ �a } q � } �� � b R ?�� b ��u � ? ���� � nb R ?�� nb ��u � ? ���� � �b <_ �b } q �#} �� � :c (] �c 4\ �d <U<�\���U���\��U��\���U���\���U��� \� � �U�� � \� � �U� �d <T<�S���T��� S �d <Q<�V���Q���Q��V���Q���V���Q���V���Q��� V� � �Q�� � V� � �Q� xe P�V��V��V��V��V��V��V ?e ' t � ?e '] xe �V��V��V��V��V��V��V xe �V��V��V��V��V��V��V �f :V}�V��V �f :]}�]��] �f s�}�s���s� �g /^ �h 0_ �h ~ q � ~ ��~ � �h 0_ �h ~ q � ~ ��~ � �f P3]��]��]��]��P��]��] �f 3\��\��\��\��\ h ] h \ �i <U<�V��U��V��U���U���V���U���&V �i T �\��T���T���\���T���&\ �i <Q<�^���Q���^���Q���Q��^��Q�� �Q�� � ^� � �Q�� � ^� ��Q���^���Q���^���Q���^��$�Q��$�$^�$�&�Q��&�&^�&�&�Q� �i u Q�]��}���]��_�����]��}x���Q��qx���qx���v 8 ���u �����]��_��}x��&�&]�&�&Q �j p $ &��� p $ &��$�$ p $ &��$�$ p $ &� �k P��P��S�#�#S \k �]��]��]��]� � ]� �]��]��!]�!�#]�#�#] �j �S��S� �S��S�$�$S Xj P��P �j P��P �k !S� � S��S �k !S� � S��S �v 3_ �v ~ q � ~ �� � �l P6]��]��]��]��P��]� � ] �l 6V��V��V��V��V� � V �o ] �o V m ���������� m ���������� �r T �r |� �r 3_ �r ~ q � ~ �� � Gt <_ Gt ~ q � ~ �� � 6w 3_ 6w ~ q � ~ �� � �n PQ �v 8� �v ��� �v |� �{ 3^ p +^ �t �� Dz 3^ �u T �u |� �w $^$9|� �x ;^ b| 3^ { ;^ �| 3^ �t 8� �t ��� �t |� �u T �u |� ex $^$9|� $y ;^ �y ;^ �y ;^ �z ;^ d{ 3^ @} 3U3�V���U� } �] �} _S �} P.S �} Pk\ �} 1 0� �} 10� �} 1S 0~ &U&�V���U� 0~ "T"�S���T� G~ \ s~ \ �~ \ �~ \ �~ S lUlm�U�mtUtu�U� lTlm�T�mtTtu�T� [ )T � U �V���U� � T�S���T� � �\��P � P/\ � P�] � A 0� � A0� � A\ i� p �� SUS�]���U���]���U���] �� WTW�^���T���^���T���^ �� )Q)�V���Q���V���Q���V �� WRW�_���R���_���R���_���R� � P#.P.>\ � _ � ,\ /� a_a��R���_���R� /� �V��V /� �^��^ /� �]��] n� P��P �� P7_{}P ^� i\��\ � .U.�V���U���V � .T.�_���T���_���T� � .Q.��� � .R.�\���R���\���R���\ � .X.�S���X���S���X� � .Y.��� 1� X]Xs^s�]��\��]��\��]��P��Q��\��P��Q��P��^��P��]��P��\��]��P W� P)XdpXs�X 1� �0���\��P��0���\��0� S� P��P��P  }^��^��^ ҂ $_$ns���s���_ � 1� P U_UZP��_��1� g� \ `� 4U4�]���U���]��U���U���]���U���]��U���U���]���U���]�� �U�� � ]� � �U�� � ]� � �U� `� 0T0�V���T���V��T���T���V��T���T��� V `� 4Q4�\���Q���\���Q���\���Q���\���Q���\��Q���Q���\��Q�� �Q� �� P Gp���p�����#�����#���p���P��P����#���p�����#� Ɇ AR��1���R �� e^��^��^��^��^��^��^��^ � PQ �� 8� �� �@� �� v� j� /S |� P �� (^ � /] ؈ 8� ؈ ��� ؈ v� � (^ Z� (^ /S ^� ,| ,4X �� GUG�V���U���OV �� (T(�_���T���_���T���_����~�� �T�� �_���T���_���T���_�� �T�� �!_�!�#�T��#�'_�'�0�T��0�2_�2�3�T��3�4_�4�;�T��;�<_�<�<�T��<�=_�=�?�T��?�@_�@�O�T� �� 0Q0���~���Q�����~���Q��� ��~� � �Q�� ���~���Q�����~���Q�����~���Q�����~�� �Q�� � ��~� � �Q�� �!��~�!�#�Q��#�#��~�#�#�Q��#�#��~�#�#�Q��#�$��~�$�$�Q��$�'��~�'�0�Q��0�1��~�1�3�Q��3�4��~�4�5�Q��5�5��~�5�;�Q��;�<��~�<�<�Q��<�=��~�=�?�Q��?�@��~�@�M�Q��M�N��~�N�N�Q��N�O��~ �� R�]��O�R� �� GXG�\���X���\����~�� �X�� �\���X���\��$�X��$�$\�$�3�X��3�4\�4�O�X� �� P&^��P��^� � ^��^�#�#^�3�3^ 9� R^��^� � ^��^��^� � ^� � ^�"�"^�#�$^�/�0^�0�1^�;�<^�>�?^ �� S� � S�$�%S 6� =^ 6� | q � | ��~ � /� S� � S�!�"S � P G��~ � | q � | ��~ � �� p ��� � ��� � ��� � ���� ���&�' ���)�* �� � �� N� 6\ N� s q � s ��~ � t� >\ t� s q � s ��~ � �� 6\ �� s q � s ��~ � �� P �^� � ^��^� � ^�0�0^ �� �\����~�� �X�� � \� ��X����X���\���X�� � �X�� � \�#�,�X��.�0�X��0�0\�0�7�X��8�9�X��9�;�X��<�J�X��J�K�X� �� �]� � ]��]��]� � ]� � ]�0�0]�2�2]�J�J]�K�K] �� ���~� � ��~����~����~� � ��~� � ��~�0�0��~�2�2��~�J�J��~�K�K��~ �� �_����~�� �T�� � _� ��T����T���_���T�� � �T�� � _�#�,�T��.�0�T��0�0_�0�7�T��8�9�T��9�;�T��<�J�T��J�K�T� �� � V� �V��V� � V� � V�#�,V�.�7V�8�9V�9�;V�<�JV�J�KV �� ���~����~�� ��~�.�.��~�0�0��~�H�H��~�I�I��~ �� P ���~����~����~�.�.��~�/�/��~�G�H��~�H�I��~ � ���~����~����~����~�,�-��~�E�E��~�F�F��~ ]� .R.���~��R����~����~�D�D��~�E�E��~ 8� p� P���~��P����~����~����~�D�E��~�E�F��~ 7� � ��~�@!�����~��S�� ��~�@!�����~��S��S� � ��~�@!�� � S�"�$S�$�$S�-�.S�.�/ ��~�@!��/�0S�0�0 ��~�@!��1�3S�4�6S�7�7S�8�:S�;�<S�<�AS�B�FS�H�HS�H�I ��~�@!��I�J ��~�@!� �� _�������D�D���E�E�� �� )1�)=��~hsPs���~����~����~����~� � P����~� � 1�� �&\�C�C��~ �� �0���_��P����~� � _� � 0�� � P� � ��~� � P� � ��~� � ��~� � P� ���~��_��^��0���^��0�����~��^� � 0�� � ^� � 0��0�00��2�20��3�3^�5�6^�?�?^�I�I_�J�J^�J�J0��K�K0� ֯ @3�a���~����~� � ��~� � 3��/�0��~�1�1��~�I�J��~�J�J��~ � P��P �� /P/4��~4APA|��~|�P����~� � P��P� � ��~�0�0��~ �� �0�����~� � 0�����~��0�� � ��~� � 0��0�0��~�1�2��~�J�J��~�K�K��~ �� �0�����~� � 0�����~��0�� � ��~� � 0��0�0��~�1�2��~�J�J��~�K�K��~ �� �0�����~��P����~� � 0�� � ��~� � ��~� ���~����~��0�����~��0�����~� � 0�� � ��~� � 0��#�$��~�.�/��~�0�00��0�0��~�1�20��2�2��~�3�4��~�4�4��~�5�7��~�:�;��~�<�=��~�=�=��~�=�=��~�>�@��~�A�B��~�C�E��~�E�F��~�F�H��~�I�I��~�I�J��~�J�J0��K�K0� �� ���~�.�.��~ �� �^�.�.^ �� P ���~����~�.�.��~ �� �V��V�.�.V �� TH��~HQTQwSw�s���P��s�����~����~��q ��~� $ & 3$��~"8 ���q ��~� $ & 3$��~"���q ��~� $ & 3$��~"8 ���| ��~� $ & 3$��~"8 ���q ��~� $ & 3$��~"8 ��-�.S�.�.P�.�.��~�.�.P�.�.��~ Q� PSFs�F���~�#� c� CPC_���~����~����~�.�.��~�F�G��~�G�G��~ c� s�4S4C��~CQq�QhQi�|���q� P�.�.P�.�.P c� CPC_���~����~����~�.�.��~�F�G��~�G�G��~ �� R �� R � ��~�,�-P�-�-��~ � V�,�-V � Q ��~#�,�,Q �� P��P�E�EP � P X JX��P��X��P��X����~��X����~��X��X��X��X� � X��X�C�CP�C�CX � J\Z�\�� \��\��\�B�C\ � J^p�^�� ^��^��^�C�C^ � *X��X � ��~_~P~���~����~����~����~����~�B�CP�C�C��~ � \��\ � V��V �� Q q���Q A� ^ �� Q :�� �� u � ! ��~ � � Q :�� � u � ! ��~ � A� Q :�� A� u � ! ��~ � i� Q :�� i� u � ! ��~ � �� T J�� �� q � ��~ � .� { �t � .� {\ .� NZN{��~ .� {V x� N^ � | 3� /] Q� \P �� 8� �� ��� �� � � /] E� &\��\��\ �� C^ �� } r �C} ��~ � � P�/�/P �� P �� �� �� /] �� \��\��\ �� C^ �� } r �C} ��~ � � P <� /] �� 3] �� \ a��~�1 �� � \����~�1 ���\����~�1 �� � \�"�#��~�1 � �� \ �� /\ &� /\ �� P �� R F��~ �� ��~u � F ��~��~ � 7� PQ 8� 8� 8� ��� 8� � � R F��~ � ��~u � F ��~��~ � h� 8� h� ��� h� � �� Q N��~ �� ��~u � N ��~��~ � �� \��\��\ � ?] � s u � s ~ � "P"?s ~ � %� \��\��\ �� C^ �� } r �C} ��~ � �� 8� �� ��� �� � /� ��� $ &� /� ��~ /� � h� �� h� �� h� � �� D^ �� } q � } ��~ � � >^ � } q � } ��~ � �� 7] �� 4] �� =^ �� } q � } ��~ � :� J^ :� } r �J} ��~ � ]� $\$7� {� N^ {� } r �N} ��~ � �� /] �� /] $� m ���� ��� � ��� � ���� ���$�% ���(�( �� W� | �� /\ � >^ � s q � s ��~ � ]� /\ �� ��� $ &� �� ^ �� � �� >\ �� s q � s ��~ � X� >^ X� s q � s ��~ � �� >S �� | q �%| ��~ � � U�V���U���V���U���V � |T|�S���T���S���T���S � 'Q'�\��\��\ L� 8P � #0�#�} ���� �)����} ���� �)����} ���� �)�� :� |^��^��^ p� O_ p� ~ q � ~ �� � � 0_ � ~ q � ~ �� � � 2U2�S���U���S � T �_���T���_ � 2Q2�V���Q���V � P5dP��P��P��P��P��P �� 0��^��0���^��^ #� P #� �]��] �� PQ �� 8� �� ��� �� � �� 7^ �� | q � | �� � &� �� � 7^ � | q � | �� � �� ?^ �� | q � | �� � r� 7^ r� | q � | �� � 7� 8� 7� ��� 7� � F� R ?�� F� ��u � ? ���� � �� R ?�� �� ��u � ? ���� � 8� ?^ 8� | q � | �� � �� ?^ �� | q � | �� � a� 7^ a� | q � | �� � Д ,U,�\���U���$\ Д �T��]��T��]��T��]���T���T�� ]� � T� � ]� � T� � ]� � T� � ]� � T� � ]� � T� �$] Д @Q@�V���Q���$V � 0�tS��0��� S� � Q� � s�� � S� � 0�� � P� � ��~� ���~����~����~��P *� z0���0���0���P�� 0�� � P� � _� �0���0���P��0���0���#0��#�#0� �� S �� ���~����~�� ��~����~����~�� ��~ 0� 1��1���0���0���1�� � 1�� � 0�� � 1�� �1�� � 1�� � 1�� � 0� 0� 1��1���0���0���0�� � 0�� � 0� 0� t��t���t���t���}���t�� � t�� � t�� � t�� � }� /� �� @� 0^ �� D^ �� 0^ J� 9^ �� P@_ ,� P�^ e� P5S��0���S��s� �� jS��0���S��S��0���@���S��0��� S �� �^��^��^��P��^��P�� ^��^ �� P�_��_��P��_��_��_ �� )P��P��P �� a^��^��^ �� �� �� R E�� �� u � / ��~ � �� 1^��^ Р ��� $ &� Р ^ Р }� 4� R2_ 4� ��u �2 ����~ � O� QR�� O� r �< ��~ � � R E�� � u � / ��~ � ,� P�^ V� P � PQ �� 8� �� ��� �� }� �� P 7��~ (� �V��V�� V (� �]��]�� ] (� �\��\�� \ (� Z0�ZcPc�0���P��0��� 0� p� 0� Q^��^ (� H0��� 0� p� P Q��~����~ ;� P���~����~�� P� � ��~ x� I_��_ �� P �� PF^Y^P � P � 8� � ��� � }� �� C_ �� ��~q �C ��~��~ � ̜ P7^� � ^��^��^��P��^ ̜ 7\� � \��\��\ �� ^ �� \ � /^ � ��~u �/��~ � �� /^ �� ��~u �/��~ � ^� /^ ^� ��~u �/��~ � � P 7��~ � &U&�]��U���U���]���U���] � BTBV�T���T���T��V��T��V��T��V��T��V��T��V��T��V��T��V��T��V���T���V � FQF�\���Q���Q��\��Q��\��Q��\��Q��\��Q��\��Q��\��Q��\��Q��\���Q���\ }� P\}P��P��P��P $� o0�o�Q��0� ?� 'Pm�P��P��P��P��P��P��q �����P��q �����P��q ��� ?� 1P�1Gq�m�P���P���P���q� � (^ J� (^ �� (^ � U�]��U���U���]���U���]���U���]���U���]���U���]���U� � T�V��T���T���V���T���V � 4Q4��Q� %� ,P,vS��P��S��P��S��S��P��S��S��P p� P.\��P��\��\��\��\��\ +� �� � /] �� (^ Z� /] � (^ P� LUL�V��U��V��U��V���U���V��U��V��U�� Vp< V P� 5T5�\��~����T���\�� �T�� � \� � �T�� � \� � �T�p< �T� \ P� *Q*�S��S� � Sz< S P� >R>�����P����������������� � ��� � ��� � ��z< �� ���1!� P� X�]���X���]���X���]�� �X�� � ]� � �X�� � ]� � �X�� � ]� � �X�p< �X� ] P� FYF������Y��������Y��������Y������� �Y�� � ��� � �Y�� � ��� � �Y�� � ��� � �Y�p< �Y� �� �� P �� �^��^��P�� ^p< ^ 0� �� P 6S��S��P��S��Sp< S � �]��] � ������� � \P~�P��T����T� � �^��^ � �V��U��V��U��V��U��V��U��V � P~0 �� P �� P T� >^��^��^��^��^ T� >V��V��V��V��V y� Qv{Q{�]��]��]��] y� R\v�R��\��\��\��\ � *\��\��\��\ � *]��]��]��] � ~���~���~� G� R F�� G� ��u � F ���� � �� sV��Vp< V �� P � Pp< 0� � �� VUV]�U�]dUdk�U� �� +T+k�T� �� Qk�Q� � U}]}��U���]���U���] � TuSu��T���S���T���S � Q7V7��Q� ?� PU\a�\��P��\��\ W� BVI�V��V W� \ �� P�^��^ � ^*B^ � ]�U�*B] � Q~q�*<Q n� ^ �� ;U;~]~��U���]��~�}���p�}���] �� 3T3vSv��T���S���T���S �� 8Q8CVC��Q� �� h^hq}��qt�U#��t�^��P��^��}����^ �� 7V>�V��V ,� P�\��\ �� \(8\ �� ]~�}�p�}�(8] �� Q|q�(2Q �� \ � -U-l]lo�U�o�]��~�}���p�}���] � $T$dSdo�T�o�S���T���S � )Q)-T-1V1��Q� � V^V_}��_b�U#��b�^��P��^��}����^ 1� 7V>�V��V �� P�\��\ �� \(@\ �� ]~�}�p�}�(@] �� Q|q�(:Q ?� \ `� -U-l]lo�U�o�]��~�}���p�}���] `� $T$dSdo�T�o�S���T���S `� )Q)-T-1V1��Q� m� V^V_}��_b�U#��b�^��P��^��}����^ �� 7V>�V��V �� P�\��\ P� \(@\ P� ]~�}�p�}�(@] P� Q|q�(:Q �� \ �� 5U5VVV[�U�[�V���U���V �� 1T1USU[�T�[�S���T���S �� %Q%X\X[�Q�[�\���Q���\ 4� P �]��] �� ] :] �� V �U� :V �� Q} q� -Q �� ] � (U(�]���U���] � T �S���T���S � (Q(�V���Q���V � (R(��� � (X(�^���X���^ <� P�\��\��T��\��\ T� �_��_ T� \ �� PEYEW������ � Y��Y���� � ]��] � Q y��Q � Y h� V h� T h� | @� ?U?�\���U���\��U��\ @� T V��T���V @� 6Q6~S~��Q���S��Q��S �� �T � U9\9=U=>�U�>f\fg�U� � !T!2V2=T=>�T�>`T`dVdg�T� � !Q!.S.=X=>�Q�>TQTaSag�Q� "� P<>P p� U<\<@U@A�U�Av\vw�U� p� !T!2V2@T@A�T�AhThtVtw�T� p� !Q!.S.@X@A�Q�A\Q\qSqw�Q� �� PDFP �� ?U?�\���U���\��U��\ �� T �V���T���V �� 6Q6�S���Q���S��Q��S A� �T �� EUE�V���U���V��U��V �� T �S���T���S �� <Q<w]w��Q���Q��]���Q� � PQ\��\ '� 9]��] '� \ �� P�^ A� "^ A� "V A� Q ~ q�!Q v� ^ �� GUG�]���U���]��U��] �� T �S���T���S �� >Q>~V~��Q���Q��V���Q� �� PQ\��\ � 9V��V �� �D � \ �� P�^ � ^ � ] � Q ~ q� Q N� ^ p� U�\���U���\���U���\���U���\ p� )T)�S���T���S���T���S���T���S p� )Q)[V[��Q���Q��V���Q� �� PY]Y\P��]��P��] �� =Vx�V��V �� P��t �� �� t�� �� ] \� P�^��^ �� ^%^ �� \�U�%\ �� Q~q�$Q �� ^ � EUE�V���U���V��U��V � T �S���T���S � <Q<x]x��Q���Q��]���Q� �� PQ\��\ �� 9]��] �� \ D� P�^ �� "^ �� "V �� Q ~ q�!Q �� ^ � 0U0�V���U���V � 'T'�S���T���S � 0Q0�_���Q���_���Q���_�� �Q�� � _� ��Q���_���Q���_���Q���_���Q� ,� P�����P��px���P��������� � ��� � ��� � ��#�� ���������P��������������P���� �� .P��P��P��P��P��T (� P ,� �]��] �� R� � R� � �� 4� PY\��\��P��\� � \� � \��\ �� P �\��P��P��P��\� � \� � \��P��\ �� P�_��_��_��_��_��_��_ �� P�^��^�� ^� � ^� � ^� � ^��^��^ L� �^��^��^� � ^� � ^��^��^��^ L� \ �� P�\� � \� � \ ^� \� � \ ^� V� � V ^� Q |� � Q x� \ -� \� � \ -� V� � V 2� Q |� � Q P� "^��^��^� � ^� � ^� � ^ P� "V��V��V� � V� � V� � V � ^ � V �� C^� � ^� � ^� � ^� � ^ �� CV� � V� � V� � V� � V 6� T^ 6� UV �� P6\��\��\��\��P��\� � \� � \ �� 6V��V��V��V��V� � V� � V �� \ �� V � P �� \ �� _��_ �� V��V �� Q ��Q � \ �� #P��P��P h� P �� 2U2�V���U��� V �� 2T2�S���T��� S �� 2Q2�\���Q���\���Q��� \� � �Q�� � \� � �Q�� � \� � �Q�� � \ � .PBXP��p ��� �� R M��������R �� P�^��^��P��^�� ^� � ^ .� P(_��P��_��_��_ � #P��P��P��P � �]��]��]��] � �]��]��T��t���T��u ��Q��qx���Q�� ]� � ]� � T� � }�� � Q� � v � � ]� � Q� � v � � Q� � Q � P��P��T 6� P \��P � �� 8� R �� 8� T 8� �� P��P � ]� ] 6� ]��0� �� P �^��^ � ^��^ � V��V � Q ~��Q V� ^ L� Q L� T L� ~ �� FUF�]���U���U�� ] �� T �S���T��� S �� ^��}�����}�����}�����}�����}�����}�����}�����}�����}�� � ��}�� � ��}� � P �V��V��V��V � Q#\��Q��Q �� �V��V��V��V��V��V��V � \��\��\ � z0���0���0���0���0���1� �� v 1&�^ � z0���0���P��\��0���0���\��\��0���\��0���\��0��� \� � \� � 0� � 5�q4���4���4���4� � Q:���:���:� H 6� H P s�qz� H ��}� � 1���1���1���1���1� � P/_��_��_��_��P��_ � /]��]��]��] e _ e ] � Q � s� � ��}� U ��}� _U_�V���U���U��V��U��V��U��V��U��V��U��V "T"�S���T���S VQV�^���Q���Q��^��Q��^��Q��^���Q���Q��^��Q��^�� �Q�� � ^� � �Q�� � ^� � �Q�� �^���Q���^���Q���^���Q���^���Q� � �]��]��]��P��]� � ]� � ]� � ]� � ]��]��] � P;RP��P��P��P + \��P��\��\� � \� � \� � \� � \��\ \��\ + \ � �� � P�^��^��^ W P � P�_��_��_ \ _��_ \ V��V \ Q q���Q � _ � } � $ &� � T � s� � \��P��\��\��\��P��\��\ � V��V��V��V��V � \ � V ` U�\���U���\ ` 5T5�V���T���V��T��V ` 5Q5��Q���Q���Q� � p #p � P��P � P � AUA�\���U���U��\��U��\ � ETE�V���T���T��V��T��V � EQE��Q���Q���Q� � P � V��~�Vc_����~���P��^��_����~���_����~���_����~���P��_����~� � V0�Vc^��0���P��^��0���^��0���0� � ��~ 3 ��~� $ &� 3 T 3 _ @ $U$�V���U���V @ T �^���T���^ @ $Q$�S���Q���S h P�\��\��\ � P��P���� � x]}�] � \ P~_��_ � _=N_ � V=NV � Q q�=HQ � _ U.V.1�U� T1�T� Q1�Q� P\P @ !U!�V���U���V @ T�S���T���S @ !Q!=]=��Q� e P�\��\��\ � P�^��^��^��^ } �]��] } \ U P �^��^ � ^��^ � V��V � Q ~q���Q n ^ : l_��_ � \ � U.V.1�U� � T1�T� � Q1�Q� P\P 0 )U)�]���U���]���U���]��U���U� 0 T �V���T���V���T���V��T��V 0 )Q)E^E��Q���Q���Q� ] P�\��P��\��\ � PEV��V u �^��^��^ u \ , P}_��_ � _8H_ � ]8H] � Q q�8BQ � _ � V��V � ]��] � Q v��Q )U)�]���U���]���U���]��U���U� T �V���T���V���T���V��T��V )Q)E^E��Q���Q���Q� M P�\��P��\��\ � PEV��V e �^��^��^ e \ P}_��_ � _8H_ � ]8H] � Q q�8BQ � _ � V��V � ]��] � Q v��Q )U)�^���U���^���U���^���U���^��U���U� T �V���T���V���T���V��T��V )Q)E]E��Q���Q���Q� = P�\��P��\��P��\��\ � P KVWiPi�V��V �0���P��V��0���V��0� U �]��]��]��] U \ L P~_��_ � _7G_ � ^7G^ � Q q�7AQ _ � V��V � ^��^ � Q v��Q @ )U)�]���U���]���U���]��U���U� @ T �V���T���V���T���V��T��V @ )Q)E^E��Q���Q���Q� m P�\��P��\��\ � P~^��^ � P\V��V � Q^��^��^ � \ t P�_��_ � _L\_ � ]L\] � Q q�LVQ N _ $ V��V $ ]��] ' Q v��Q 6 ^��^ 6 ]��] : Q ~��Q � <U<�V���U���V��U���U���V � 2T2�S���T���S � <Q<X]X��Q���Q���Q� � P�\��\��\ ) *P*�]��P��]��] � Q]��]��] � \ P~^��^ � ^7G^ � V7GV � Q ~ q�7AQ � ^ e �D � ]��] � V��V � Q }��Q ! %U%�]���U���] ! ETE�V���T���V��T��V ! EQE�\���Q���\���Q���Q��\���Q� X! .P.kS��^��S��P �! P &\ +" ^ +" v� +" ��}�_ p" IUI�]���U���]��U��] p" "T"�V���T���V p" @Q@�_���Q���_��Q��_ �" Pb^bfUfg^��^��P��^ )# P +\ �" �� �# Q �# T �# P^ $ IUI�_���U���_��U��_ $ "T"�S���T���S $ @Q@�V���Q���Q��V���Q� #% 0�gVgmv�m�V �$ P^\��\��\ 9% P R@NPN[R �$ FVx�V��V B$ �0���0���^��0� k$ �� �$ P^\��\��\ �$ \ & P�] v& ] .] v& _ ._ v& Q } (Q �& ] �& IUI�V���U���V��U��V �& "T"�S���T���S �& @Q@�]���Q���Q��]���Q� �' 0��]��] G' P]\��\��\ �' P�_��P��_��_ _' E]v�]��] -' �� G' P]\��\��\ _' \ �) P �^ 5* ^ -^ 5* V -V 5* Q ~ 'Q p* ^ ( P P) ~ � $ &� P) T P) s� �* "U"�V���U��� V �* ?T?�S���T��� S �* ?Q?�]���Q���Q��]�� �Q�� � ]� � �Q� �+ 0� �]��]��0���]��] ;+ P�\��\��\�� \ �+ P�^��P��^��^��^��^ S+ q]��]�� ] �* *P*�_��_� � P� � _ !+ �� ;+ P�\��\��\�� \ S+ \ �. P�^��^ -/ ^{�^ -/ V{�V -/ Q ~ q�{�Q �/ ^ �+ 6P��P��P��P��P���� �+ =0�=�_��0���0���_��0���0���_ Z, P . ��� $ &� . T . s� (. )^��^ (. .V��V 4. Q ~"q���Q �- P 0 BUB�\���U���\��U��\��U��\ 0 T�V���T���V��T��V��T��V 0 9Q9��Q���Q���Q� �0 0� �S��S `0 P2]l�]��] 1 P �0 PvxP��P `0 P2]l�]��] `0 P �0 �D �1 FUF�V���U���V��U��V �1 T �_���T���_ �1 =Q=��Q���Q���Q� �2 0� �]��]��] 2 P1\n�\��\��\ �1 h0���0���P��S��^��S��0���S��S �2 #PExP��P��q �����P��P �1 h0���0���^��0���^��P��^��^ 2 P1\n�\��\��\ 2 P u2 �� T3 P Z4 ^��P �4 ��� $ &� �4 T �4 � �5 3U3�V���U���V �5 T�S���T���S �5 3Q3�^���Q���^ �5 3R3O\O��R� �6 0��\��\��\ �5 P]]��]��] �6 P�_��P��_��_��_ �5 E\k~\��\��\ �5 ��~h � �5 ] �7 P �_��_ s8 _m}_ s8 Vm}V s8 Q mwQ �8 _ �6 R �8 �� �8 T �8 s� @9 Ud�U� @9 T d�T� @9 Qd�Q� I9 :S;ZS �9 9U9NSNP�U�P_S �9 9T9P�T�PZTZ^U^_�T� �9 u �9 P/V0?V �9 p $ &3$u"�v $ &3$u"�)7v $ &3$s"� �9 u p $ &3$ u 8�u v $ &3$ u 8�)7s v $ &3$ s 8� �9 U �9 0� : mUm�S���U���S�< S : ETE��T���T��U���T��< �T� : Su ��s ��s -: P �V��V�< V 8: p $ &3$q "�p $ &3$u"�:v $ &3$u"���v $ &3$s"���v $ &3$s"� 8: u p $ &3$ u 8�:u v $ &3$ u 8���s v $ &3$ s 8���s v $ &3$ s 8� 8: �\��\��\�< \ : U 8: t :�T���T��t ��u 0; p##X�0.� p#X�0.� �: P �: P�< 0� �: KSuuS�< S ; P 0; p#p P�< 0� �: 1� `; tUt�S���U���S `; ]T]��T���T��U���T� �; P~V��V �; p $ &3$q "� )v $ &3$q "�)<v $ &3$u"���v $ &3$q "� �; u p $ &3$ q 8� )u v $ &3$ q 8�)<u v $ &3$ u 8���s v $ &3$ q 8� �; 8X��X �; %t %<�T��t ��u �; Q �; %1�.31� @< [U[�S���U���S @< OTO��T���T��U���T� S< /u /Hu @ ���s ]< V%v�%�\��v� d< v $ &3$q "� 7R��R d< u v $ &3$ q 8�u p 3$ q 8�!u v $ &3$ q 8�!7u u� #� $ &3$ q 8���s v $ &3$ q 8� h< �^��^ S< U d< +t +7�T��t ��u �< p #( p( �< P �< 1� = WUW�S���U���S = WTW��T���T���T���T��U���T� = u ��]��}���] $= P�V��V��V += p $ &3$u"�,v $ &3$u"���v $ &3$s"���v $ &3$s"� += u p $ &3$ u 8�,u v $ &3$ u 8���s v $ &3$ s 8���s v $ &3$ s 8� = U �= 7QmzQ W= �\��\��\ �= "QXeQ �= 1� 0> WUW�S���U���S 0> WTW��T���T���T���T��U���T� 4> u ��]��}���] T> P�V��V��V [> p $ &3$u"�,v $ &3$u"���v $ &3$s"���v $ &3$s"� [> u p $ &3$ u 8�,u v $ &3$ u 8���s v $ &3$ s 8���s v $ &3$ s 8� 4> U �> 7QmzQ �> �\��\��\ �> "QXeQ ? 1� `? U �V���U���$V `? NTN�^���T���^��T�� ^� ��T���^��R��_�� ^� � �T�� �!^�!�!�T��!�#^�#�#_�#�$^�$�$�T��$�$^ `? NQN�S���Q���S��Q�� S� ��Q���S���Q���S��#�Q��#�#S�#�$�Q��$�$S �? ���~�����}����~���P����~���T�� ��}� ���~�����}��T����}��P��T��#��}�#�#��~��#�#��}�#�#P�#�#T�#�#��} �? P '_{�P��p �����P�� ����_ D P �S��P�� S� � S� � S� ���}��S��S����} �? �0��� 0�� � ��}� �0���0���P��_����}� � P� � ��}� � 0�� � P� � ]� � 0�� �!��}�!�!]�!�"]�"�"��}�"�#0��#�#]�#�#0� XE P�_��P��_��P��_��P��_��_ �? �\��\��\�� \� �\��\��\����}� � \� � \�!�!\�"�"��}�"�"\�"�#\ G@ P��P� � P� � ��}� � P� � ^��P��^��P��^� � P� � ��}� � ��}� � ^� � ��}� �!��}�!�"��} E P� � P��P E P>_� � _��_��_��_��_ �? P��p ����P�� 3� �? p 4� ���}�4�����}�4���p 4��� ��}�4�� ���}�4�����}�4�� � ��}�4�� � ��}�4��"�#��}�4��#�#��}�4� �? M0�M���}����}��0�����}��0��� ��}� �0��� ��}� �!��}�!�!��}�"�#��}�#�#��} �? M0�M�]��]��0���]��0���P��]��0��� ]� �]��]����}� � ]� � ]�"�"��}�"�#]�#�#] �? �0��� 0�� �0���0���1�����}��]� � 0�� � 0��"�"]�"�#0��#�#0� �? �#�U� � �? \ P@ P��P P@ V��V S@ Q p��Q �B P� � P �@ P �@ ��}��0���0�����}� � 0�� � ��}��0�� � 0�� �!0� �A ��~ �G ��~� $ &� �G T �G ��} �C ��~ �C P �D P �I P HXHZ��}� � ��} kJ X� � X� � ��} kJ V� � V kJ Q xq�� � Q vP X |E S �E ��}��T����} �E V��V �E Q ��}#��Q �E S��S �E V��V �E Q s��Q bF "^��^ bF "V��V oF Q ~q���Q �G ��~ �H R �H T �H s �J P ,_,���}� � ��} �J R �S� � S �J ;1�;�^� � ^ yK Pl�P� � P L P �K | QK ��~ [K P M _ �v � M P =| �L @T@b��} �L bV 9M UH_ �M P*��} �N P�_��P��_��_��_ BN P���}����}����}��P����}����} `N P�]��]��]��] �N S �N T��T����} �N V��V �N Q t��Q �N S��S �N V��V �N Q s��Q �N ��}��P����} �N V��V O Q ��}#��Q MO \��\ MO V��V WO Q |��Q hO \��\ hO V��V hO |��| }O \ �O _��_ �O V��V �O Q ��Q �Q U �U� �Q T �T� �Q Q �Q� �Q "U"�^���U���^��U���U��� ^ �Q ?T?�V���T���T��V��T���T��� V �Q ?Q?�]���Q���Q��]���Q���]��X��]�� �Q�� � ] �Q PN\��\��\��P��\ �T _ �Q -0���0���p�����0���P��0� 1R �� ;R Q uS ] P ]��]��] uS �\��\ uS �V��V uS U�^��^ �S 0�q]��] }S P�_��_ �S PRBWP �S _]��]��] uS �0�������0�������0� }S P�_��_ �S _ �U P|S��S V S0@S V ^0@^ V Q s q�0:Q ^V S �T P��P �T _ �V 7U7?T?�V��U���U� �V T ��T���P��P��P��P��P��P��P �V P �]��T �V p $ &3$v"8 � �V v �V v p $ &3$ v #8� !W #P QW P zW #P �W P <X P eX P �X P �X P�\ �Y DUDR�U�R�U���U���U���U���U���U���U���h��U �Y ��ϓ � [ rUr�\���U���U��\���U���\���U���\���U� [ oTo�V���T���T��V [ :R:�^��xx����R���^���R���^���R���^��xx���~x����R� [ hXhzQ��Q [ zYz��Y���Y���Y� :[ D0�D_P_�_��P��_��P��0���_��_��P��_ H[ �]��]��]��]��] [[ `S��s 8!���S��s 8!� :[ ���� � :[ ��� � v[ E0���~���~���X��^ v[ =0�=@~�@EX��0���0� \ �� �^ 4] �] ��� $ &� �] X �] v� �] Q N�� �] } r � &} �� � h^ 9S /_ 4] p_ 3U3pVptUtu�U�u{U{�V �_ OSUbS t_ ~�$� � �_ QTU_T �_ UU[U[bV �_ Q tMWQ �_ p ` OUO�\��U��\��U��\��U���U���\���U��� U� � \� � U� � \�< \ ` 9T9�S���T���S�� �T�� � S� � �T�� � S� � �T�� � S�< S ` $Q$�]��P��]� � ]� � ]� � ]� � ]�< ] ` R �_���R���_���R2!���_���R2!��� _�< _ ` X�^�� �X�� � ^� � �X�� � ^�< ^ U` P �` �V��V��V��P�� V�< 0� �c 8P8�]��T��]��] ]b �S��S��S �` �0���s 0.����s 0.���� 0�� � s 0.��� � 0�� � 0��< 0� a #U#v��� � ��� � �� 3a PES� � S� � P� � S ]b �S��S��S ]b �_��_��_ ]b �V��V��V ]b �\��U��\��U��\��U��\��U��\��\ jb P"v� ��v� �b P �b BP �e P d P 5e eS��S =e P ]]��] 4f ] �f \U\�S���U���S �f PTP��T���T��U���T� �f u �f Q�\��~���\ �f q $ &3$p "�*| $ &3$p "���| $ &3$p "� �f �V��V �f *U �f `_a{_ %g P#P g _ g S 2g 1� �g zUz�S���U���S �g dTd��T���T��U���T� �g u �g PV��V �g p $ &3$y "�Mv $ &3$y "���v $ &3$y "���v $ &3$y "� �g BQv}Q}�s s� #� $ &3$ y 3&���Q �g &U �g `]ar] h P P �g ] �g S h 1� Ph zUz�S���U���S�< S Ph ]T]��T���T��U���T��< �T� Th u xh P�V��V�< V h p $ &3$q "�?v $ &3$q "���v $ &3$q "� h u p $ &3$ q 8�0u v $ &3$ q 8���s v $ &3$ q 8� Th $U �h �]��]��]�< ] Ci T&P �h �]��]��]�< ] �h $U$�S��S��S�< S �h P �h T��^��^�< 0� �i r_��_ �i �^��^�< 0� 8j P �i P �i �^��^�< 0� Si 1� � b> `j p> 6 �@ SVk�����"�"�"�# �Q ?BI A ������� � ������������ � �"�#�#�$�%�&�&�/�1�5�6�7 bA &� � � � C `� � � � ������ �C ��� ������� � � � �&�)�-�0�1�1 �C ������� � � � �'�(�/�/ hW e �W e ][ p �C �������� � �&�&�(�)�-�. D '� � �-�. !D 2X MRk �D [���"�"�+�+ �D ��� � � � � ������ � �)�* �F ���� �I Q 27W WE 4��� � kE sE �P 27X dB ���� � �������!�"�,�- F {����� � �+�, (F pM I gQ I �R I �\ ,���� ��� (] &� � c^ ������� � c^ ����� � Pd BF_ �a h Hb h �b 27h hc 27X e .:=U ne HJx�������������� �f @���� �f *-0������������ Lj &�� �j .�� �k H� � �� �l -03������������� � m ������ � � ��� �n 5���� �n �n @p h������ � � � � ���������� ep ���� �t �w DIh �p >�������� @x DI` t} KN� �} 1 �~ . � Td� � A � GO^� 0� ��� G� &�� �� ����� �� ������� � V������ � � �� ������� ^� $0: 3� ����� L� IPW y� 4���� � � �� �� {� ����� � � #���� &� � h �� h �� ��������� � � � � � � � ��� � � � � � �� ����� � �� /� �� � � ���!�! �� � � ������ �� ������ �� �� @�� � ^ 2� PUo � @� '+0 ܖ 5��� � � � � �� (� ���� � � � �� 9 � M\� њ X ̜ .14� � �������� ̢ R �� R ;� R � ����� � ?���� �� 1� � �%�% � &� � �!�" E� ;K��� � � � � � �"�"�9�:�<�= �� ����� � �9�: � �� � � ���� � � � �#�,�.�7�8�9�9�;�<�J�J�K �� ����.�. �� +�.�. G� �� > � �,�- � �,�- �� #���E�E � -15D��� �����B�C � ���� A� � #�$�$�.�. 0� !M���'�( Q� b� �� �����$�% � 5�/�0 '� �/�0 �� ���#�$ �� � � � ��� � � W����� � �!�" � ��� � �� EIU x� �� � ����� � �"�# � l�����"�# � 5R���"�# �� �� ������ �� p � Xhs������ 7� AU\���� 7� �� p `� t �� "���� � (���� �� 2:Z �� 27W X� FKX (� p��� � � � ���$�%�(�( H� P� � �$�% �� >Fb P� � p< � ����� n� � �� D� N�������� � *������ � p �� op< �= ��p< @ �� ������� � >N �� ������� �� 6F Z� ������� �� >N �� ������� B� >N � ��������� �� /: �� ������ � �� W� i��� 5� 3 �� >� b��� � . �� N������� �� &6 �� h��� �� 3 �� �������� P� � � -� � � P� "����� � � � � � � � �� F� � � � � � � � �� -03������������� � � � �� �� �� �� �� +�� v� &�� � �� 6� ���� n� ����� �� �� � x������ H -OO�������������� � /�������� e ; �������� � �� ; -T[`�� � i� � �� ( ���� � � )|��������� � � � � ������� P (�� � ���������� � � L����� v "JZ � ������ � %�� 7 o������ � o����� � $DT � �� � o����� | $DT � �� � ������ � #CS � �� � ������ � Xh $ �� 6 �� ������ } #CS � �� �# �$ ������ j& *: �' ������ )* )9 �+ ������ !/ �� �+ ����������� 0. !0���� Z4 �� �5 ! 26 ���� g8 y� �9 : ��< : N: ����< N: u�< �: HHP�< q; ! �; Aio L< = == ��� �= 3l| 4> m> ��� �> 3l| P@ �� �@ b��� � � � � �! �@ ������� � � � � � ��� � � �! �A 2 =B �C Z� � �C �C .E � � ���� _J !� � �E �� �E �� �E �� bF "�� kF �� �F nG :�� �J �J �� � �J ���� � �J 4���� ,K ?w~�� QK UK 'N ������� HN �N �� �N �� �N �� �N �� �N �� MO �� RO �� hO ���� �O �� R I���� 1R 5R hS ��� hS �S ���� V ;K �T 8�� W EW nW �W 0X YX �X h[ ��� �[ .������ @^ 0:h �_ Xb �_ S] �_ 7=E ` � �< �` �� � � � � � �< ]b ����� �b �b (e x�� �f #'* �f i�� g QY �g #& �g \p� �g DL Ph ��< Th !$ �h ����< �h ,4����< pi V�< �� ��< 2 � � � � � � 8 0 0 P6 p< �j p �~ � � �� � �� �� � @� H� ! " # � �= L �> � ! �? 6 . �\ ; �d � G �i R � @ ` � H i �� �' w � � � � � � Д I � � � � � � � �t � �t � p< � � �� k � � c �� d � T 0 `� T ? �� B U � * a @� � r � g � p� w � �� � � �� � � �� � � p� � � � � � � � � �� � �� k �� �� ! = * ` E ? � � P @ � ] 1 n @ � � � 1 � 0 � � � � + � @ ? � � � � ! ] p" � 4 $ � G �& � �* \ 0 0 � C �1 � U �5 � k �9 _ � : J � �< � `; � � @< � � = , 0> , & `? # G �Q U �Q � f �f � | �g � � Ph O � ` � �< � �< � x~ � � � �< � �< 0= @� ) �� P p= \ � � � { L� � ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' � � ' � � K � @9 d � �j � � � r `� � � � � p_ � 0~ � 2 [ h R �� [ �Y N o P� Y � �~ � @� � �� � @} � � �� } � u � 0 / C U j { � � � �V � � � � + 9 I Z n y � � � � � � � ( 2 D X o � � � � � � � ) 7 I [ k � � � � � � � & 3 D U e q } � � � � � � � � , @ W d o | � � � � � � � � ! . > J X k y " � � � � � clean_store_context known_class store_scalar store_regexp store_other store_code vtbl_storable sv_store store_blessed store_ref store_array store_hash store_tied store_tied_item network_file_header.1 file_header.0 do_store.lto_priv.0.cold retrieve_other retrieve_undef retrieve_sv_undef retrieve_sv_yes retrieve_sv_no retrieve_svundef_elem get_lstring retrieve_lscalar retrieve_scalar retrieve_utf8str retrieve_lutf8str retrieve_integer retrieve_netint retrieve_byte retrieve_double retrieve_code retrieve_regexp magic_check sv_retrieve sv_old_retrieve retrieve_idx_blessed retrieve_blessed retrieve_ref retrieve_weakref retrieve_overloaded retrieve_weakoverloaded retrieve_tied_array retrieve_tied_hash retrieve_tied_scalar retrieve_tied_key retrieve_tied_idx retrieve_vstring retrieve_lvstring retrieve_flag_hash old_retrieve_array old_retrieve_hash get_lhash.constprop.0 XS_Storable_init_perinterp XS_Storable_last_op_in_netorder XS_Storable_last_op_in_netorder.cold XS_Storable_mstore XS_Storable_pstore XS_Storable_stack_depth XS_Storable_stack_depth_hash retrieve_hook_common.constprop.0 retrieve_hook retrieve_lobject XS_Storable_pretrieve XS_Storable_mretrieve XS_Storable_dclone do_retrieve do_retrieve.cold XS_Storable_dclone.cold old_magicstr crtstuff.c deregister_tm_clones __do_global_dtors_aux completed.0 __do_global_dtors_aux_fini_array_entry frame_dummy __frame_dummy_init_array_entry __FRAME_END__ Storable.c.ba8a39ef scalar_call.lto_priv.0 storable_free.lto_priv.0 _fini allocate_context.lto_priv.0 __dso_handle free_context.isra.0 clean_retrieve_context.lto_priv.0 store_hentry.constprop.0.isra.0 _DYNAMIC sv_type.constprop.0 do_store.lto_priv.0 __GNU_EH_FRAME_HDR __TMC_END__ _GLOBAL_OFFSET_TABLE_ init_perinterp.lto_priv.0 pkg_can.lto_priv.0 clean_context.lto_priv.0 _init Perl_sortsv Perl_sv_free Perl_sv_2iv_flags Perl_sv_2bool_flags Perl_hv_iterkeysv Perl_ptr_table_store Perl_newRV_noinc Perl_sv_2uv_flags Perl_stack_grow _ITM_deregisterTMCloneTable boot_Storable Perl_call_method Perl_sv_magicext Perl_sv_derived_from Perl_av_len Perl_pop_scope PL_sv_placeholder Perl_av_shift Perl_sv_reftype Perl_newCONSTSUB Perl_warn_nocontext Perl_newSV Perl_hv_riter_set Perl_ptr_table_free strlen@GLIBC_2.2.5 __stack_chk_fail@GLIBC_2.4 Perl_sv_upgrade Perl_sv_setiv_mg Perl_gv_stashpvn Perl_av_store Perl_newSVnv Perl_sv_bless Perl_warn Perl_sv_2pv_flags Perl_xs_boot_epilog Perl_hv_iternext_flags Perl_ptr_table_new Perl_get_cv Perl_safesysmalloc Perl_bytes_from_utf8_loc Perl_gv_fetchpv __memcpy_chk@GLIBC_2.3.4 Perl_hv_ksplit __gmon_start__ Perl_croak_xs_usage Perl_newSVpvn_flags Perl_savetmps memcpy@GLIBC_2.14 Perl_sv_2nv_flags Perl_gv_stashpv Perl_load_module_nocontext Perl_Gv_AMupdate Perl_hv_eiter_set Perl_newSVpv Perl_gv_fetchmethod_autoload Perl_get_sv Perl_av_pop Perl_croak_nocontext Perl_ptr_table_fetch Perl_PerlIO_read Perl_av_fill Perl_hv_iterinit Perl_newXS_flags Perl_sv_2mortal Perl_sv_cmp Perl_mg_get Perl_hv_common Perl_safesysfree Perl_safesysrealloc Perl_call_pv Perl_av_undef Perl_sv_2io Perl_xs_handshake Perl_av_fetch Perl_hv_undef_flags Perl_free_tmps Perl_sv_rvweaken Perl_markstack_grow Perl_hv_common_key_len Perl_eval_sv Perl_newRV Perl_mg_find Perl_newSV_type Perl_PerlIO_write Perl_sv_catpv PerlIO_getc Perl_sv_magic Perl_sv_setpv_bufsize Perl_call_sv Perl_sv_free2 Perl_push_scope _ITM_registerTMCloneTable Perl_newSViv Perl_hv_iterval PerlIO_putc Perl_sv_setiv Perl_newSVsv_flags Perl_newSVpvn __cxa_finalize@GLIBC_2.2.5 Perl_sv_newmortal Perl_sv_tainted __sprintf_chk@GLIBC_2.3.4 Perl_hv_placeholders_get Perl_av_extend .symtab .strtab .shstrtab .note.gnu.property .note.gnu.build-id .gnu.hash .dynsym .dynstr .gnu.version .gnu.version_r .rela.dyn .rela.plt .init .plt.sec .text .fini .rodata .eh_frame_hdr .eh_frame .init_array .fini_array .data.rel.ro .dynamic .got .data .bss .comment .annobin.notes .gnu.build.attributes .debug_aranges .debug_info .debug_abbrev .debug_line .debug_str .debug_line_str .debug_loclists .debug_rnglists � � . � � $ A ���o � � $ K � S � � � [ ���o � � � h ���o � � P w ( � B 8 8 0 � 0 0 � 0 0 0 � P6 P6 � p< p< /. � �j �j � p p � � �~ �~ � � � � 0 � � � � �� �� � � � � � �� �� � � �� �� X � � � @ � @� @� 0 @� . 0 n� � H� �� 2 � � A �� �� M � * [ �� O� g 0 �� G r 0 �� � � �� 1� � �� 0 0� �6 % � � � �! � PK d �[c7�� � lib/Storable.pmnu ��6�$ # # Copyright (c) 1995-2001, Raphael Manfredi # Copyright (c) 2002-2014 by the Perl 5 Porters # Copyright (c) 2015-2016 cPanel Inc # Copyright (c) 2017 Reini Urban # # You may redistribute only under the same terms as Perl 5, as specified # in the README file that comes with the distribution. # BEGIN { require XSLoader } require Exporter; package Storable; our @ISA = qw(Exporter); our @EXPORT = qw(store retrieve); our @EXPORT_OK = qw( nstore store_fd nstore_fd fd_retrieve freeze nfreeze thaw dclone retrieve_fd lock_store lock_nstore lock_retrieve file_magic read_magic BLESS_OK TIE_OK FLAGS_COMPAT stack_depth stack_depth_hash ); our ($canonical, $forgive_me); BEGIN { our $VERSION = '3.25'; } our $recursion_limit; our $recursion_limit_hash; $recursion_limit = 512 unless defined $recursion_limit; $recursion_limit_hash = 256 unless defined $recursion_limit_hash; use Carp; BEGIN { if (eval { local $SIG{__DIE__}; local @INC = @INC; pop @INC if $INC[-1] eq '.'; require Log::Agent; 1; }) { Log::Agent->import; } # # Use of Log::Agent is optional. If it hasn't imported these subs then # provide a fallback implementation. # unless ($Storable::{logcroak} && *{$Storable::{logcroak}}{CODE}) { *logcroak = \&Carp::croak; } else { # Log::Agent's logcroak always adds a newline to the error it is # given. This breaks refs getting thrown. We can just discard what # it throws (but keep whatever logging it does) and throw the original # args. no warnings 'redefine'; my $logcroak = \&logcroak; *logcroak = sub { my @args = @_; eval { &$logcroak }; Carp::croak(@args); }; } unless ($Storable::{logcarp} && *{$Storable::{logcarp}}{CODE}) { *logcarp = \&Carp::carp; } } # # They might miss :flock in Fcntl # BEGIN { if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) { Fcntl->import(':flock'); } else { eval q{ sub LOCK_SH () { 1 } sub LOCK_EX () { 2 } }; } } sub CLONE { # clone context under threads Storable::init_perinterp(); } sub BLESS_OK () { 2 } sub TIE_OK () { 4 } sub FLAGS_COMPAT () { BLESS_OK | TIE_OK } # By default restricted hashes are downgraded on earlier perls. $Storable::flags = FLAGS_COMPAT; $Storable::downgrade_restricted = 1; $Storable::accept_future_minor = 1; BEGIN { XSLoader::load('Storable') }; # # Determine whether locking is possible, but only when needed. # sub show_file_magic { print <<EOM; # # To recognize the data files of the Perl module Storable, # the following lines need to be added to the local magic(5) file, # usually either /usr/share/misc/magic or /etc/magic. # 0 string perl-store perl Storable(v0.6) data >4 byte >0 (net-order %d) >>4 byte &01 (network-ordered) >>4 byte =3 (major 1) >>4 byte =2 (major 1) 0 string pst0 perl Storable(v0.7) data >4 byte >0 >>4 byte &01 (network-ordered) >>4 byte =5 (major 2) >>4 byte =4 (major 2) >>5 byte >0 (minor %d) EOM } sub file_magic { require IO::File; my $file = shift; my $fh = IO::File->new; open($fh, "<", $file) || die "Can't open '$file': $!"; binmode($fh); defined(sysread($fh, my $buf, 32)) || die "Can't read from '$file': $!"; close($fh); $file = "./$file" unless $file; # ensure TRUE value return read_magic($buf, $file); } sub read_magic { my($buf, $file) = @_; my %info; my $buflen = length($buf); my $magic; if ($buf =~ s/^(pst0|perl-store)//) { $magic = $1; $info{file} = $file || 1; } else { return undef if $file; $magic = ""; } return undef unless length($buf); my $net_order; if ($magic eq "perl-store" && ord(substr($buf, 0, 1)) > 1) { $info{version} = -1; $net_order = 0; } else { $buf =~ s/(.)//s; my $major = (ord $1) >> 1; return undef if $major > 4; # sanity (assuming we never go that high) $info{major} = $major; $net_order = (ord $1) & 0x01; if ($major > 1) { return undef unless $buf =~ s/(.)//s; my $minor = ord $1; $info{minor} = $minor; $info{version} = "$major.$minor"; $info{version_nv} = sprintf "%d.%03d", $major, $minor; } else { $info{version} = $major; } } $info{version_nv} ||= $info{version}; $info{netorder} = $net_order; unless ($net_order) { return undef unless $buf =~ s/(.)//s; my $len = ord $1; return undef unless length($buf) >= $len; return undef unless $len == 4 || $len == 8; # sanity @info{qw(byteorder intsize longsize ptrsize)} = unpack "a${len}CCC", $buf; (substr $buf, 0, $len + 3) = ''; if ($info{version_nv} >= 2.002) { return undef unless $buf =~ s/(.)//s; $info{nvsize} = ord $1; } } $info{hdrsize} = $buflen - length($buf); return \%info; } sub BIN_VERSION_NV { sprintf "%d.%03d", BIN_MAJOR(), BIN_MINOR(); } sub BIN_WRITE_VERSION_NV { sprintf "%d.%03d", BIN_MAJOR(), BIN_WRITE_MINOR(); } # # store # # Store target object hierarchy, identified by a reference to its root. # The stored object tree may later be retrieved to memory via retrieve. # Returns undef if an I/O error occurred, in which case the file is # removed. # sub store { return _store(\&pstore, @_, 0); } # # nstore # # Same as store, but in network order. # sub nstore { return _store(\&net_pstore, @_, 0); } # # lock_store # # Same as store, but flock the file first (advisory locking). # sub lock_store { return _store(\&pstore, @_, 1); } # # lock_nstore # # Same as nstore, but flock the file first (advisory locking). # sub lock_nstore { return _store(\&net_pstore, @_, 1); } # Internal store to file routine sub _store { my $xsptr = shift; my $self = shift; my ($file, $use_locking) = @_; logcroak "not a reference" unless ref($self); logcroak "wrong argument number" unless @_ == 2; # No @foo in arglist local *FILE; if ($use_locking) { open(FILE, ">>", $file) || logcroak "can't write into $file: $!"; unless (CAN_FLOCK) { logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O"; return undef; } flock(FILE, LOCK_EX) || logcroak "can't get exclusive lock on $file: $!"; truncate FILE, 0; # Unlocking will happen when FILE is closed } else { open(FILE, ">", $file) || logcroak "can't create $file: $!"; } binmode FILE; # Archaic systems... my $da = $@; # Don't mess if called from exception handler my $ret; # Call C routine nstore or pstore, depending on network order eval { $ret = &$xsptr(*FILE, $self) }; # close will return true on success, so the or short-circuits, the () # expression is true, and for that case the block will only be entered # if $@ is true (ie eval failed) # if close fails, it returns false, $ret is altered, *that* is (also) # false, so the () expression is false, !() is true, and the block is # entered. if (!(close(FILE) or undef $ret) || $@) { unlink($file) or warn "Can't unlink $file: $!\n"; } if ($@) { $@ =~ s/\.?\n$/,/ unless ref $@; logcroak $@; } $@ = $da; return $ret; } # # store_fd # # Same as store, but perform on an already opened file descriptor instead. # Returns undef if an I/O error occurred. # sub store_fd { return _store_fd(\&pstore, @_); } # # nstore_fd # # Same as store_fd, but in network order. # sub nstore_fd { my ($self, $file) = @_; return _store_fd(\&net_pstore, @_); } # Internal store routine on opened file descriptor sub _store_fd { my $xsptr = shift; my $self = shift; my ($file) = @_; logcroak "not a reference" unless ref($self); logcroak "too many arguments" unless @_ == 1; # No @foo in arglist my $fd = fileno($file); logcroak "not a valid file descriptor" unless defined $fd; my $da = $@; # Don't mess if called from exception handler my $ret; # Call C routine nstore or pstore, depending on network order eval { $ret = &$xsptr($file, $self) }; logcroak $@ if $@ =~ s/\.?\n$/,/; local $\; print $file ''; # Autoflush the file if wanted $@ = $da; return $ret; } # # freeze # # Store object and its hierarchy in memory and return a scalar # containing the result. # sub freeze { _freeze(\&mstore, @_); } # # nfreeze # # Same as freeze but in network order. # sub nfreeze { _freeze(\&net_mstore, @_); } # Internal freeze routine sub _freeze { my $xsptr = shift; my $self = shift; logcroak "not a reference" unless ref($self); logcroak "too many arguments" unless @_ == 0; # No @foo in arglist my $da = $@; # Don't mess if called from exception handler my $ret; # Call C routine mstore or net_mstore, depending on network order eval { $ret = &$xsptr($self) }; if ($@) { $@ =~ s/\.?\n$/,/ unless ref $@; logcroak $@; } $@ = $da; return $ret ? $ret : undef; } # # retrieve # # Retrieve object hierarchy from disk, returning a reference to the root # object of that tree. # # retrieve(file, flags) # flags include by default BLESS_OK=2 | TIE_OK=4 # with flags=0 or the global $Storable::flags set to 0, no resulting object # will be blessed nor tied. # sub retrieve { _retrieve(shift, 0, @_); } # # lock_retrieve # # Same as retrieve, but with advisory locking. # sub lock_retrieve { _retrieve(shift, 1, @_); } # Internal retrieve routine sub _retrieve { my ($file, $use_locking, $flags) = @_; $flags = $Storable::flags unless defined $flags; my $FILE; open($FILE, "<", $file) || logcroak "can't open $file: $!"; binmode $FILE; # Archaic systems... my $self; my $da = $@; # Could be from exception handler if ($use_locking) { unless (CAN_FLOCK) { logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O"; return undef; } flock($FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!"; # Unlocking will happen when FILE is closed } eval { $self = pretrieve($FILE, $flags) }; # Call C routine close($FILE); if ($@) { $@ =~ s/\.?\n$/,/ unless ref $@; logcroak $@; } $@ = $da; return $self; } # # fd_retrieve # # Same as retrieve, but perform from an already opened file descriptor instead. # sub fd_retrieve { my ($file, $flags) = @_; $flags = $Storable::flags unless defined $flags; my $fd = fileno($file); logcroak "not a valid file descriptor" unless defined $fd; my $self; my $da = $@; # Could be from exception handler eval { $self = pretrieve($file, $flags) }; # Call C routine if ($@) { $@ =~ s/\.?\n$/,/ unless ref $@; logcroak $@; } $@ = $da; return $self; } sub retrieve_fd { &fd_retrieve } # Backward compatibility # # thaw # # Recreate objects in memory from an existing frozen image created # by freeze. If the frozen image passed is undef, return undef. # # thaw(frozen_obj, flags) # flags include by default BLESS_OK=2 | TIE_OK=4 # with flags=0 or the global $Storable::flags set to 0, no resulting object # will be blessed nor tied. # sub thaw { my ($frozen, $flags) = @_; $flags = $Storable::flags unless defined $flags; return undef unless defined $frozen; my $self; my $da = $@; # Could be from exception handler eval { $self = mretrieve($frozen, $flags) };# Call C routine if ($@) { $@ =~ s/\.?\n$/,/ unless ref $@; logcroak $@; } $@ = $da; return $self; } # # _make_re($re, $flags) # # Internal function used to thaw a regular expression. # my $re_flags; BEGIN { if ($] < 5.010) { $re_flags = qr/\A[imsx]*\z/; } elsif ($] < 5.014) { $re_flags = qr/\A[msixp]*\z/; } elsif ($] < 5.022) { $re_flags = qr/\A[msixpdual]*\z/; } else { $re_flags = qr/\A[msixpdualn]*\z/; } } sub _make_re { my ($re, $flags) = @_; $flags =~ $re_flags or die "regexp flags invalid"; my $qr = eval "qr/\$re/$flags"; die $@ if $@; $qr; } if ($] < 5.012) { eval <<'EOS' sub _regexp_pattern { my $re = "" . shift; $re =~ /\A\(\?([xism]*)(?:-[xism]*)?:(.*)\)\z/s or die "Cannot parse regexp /$re/"; return ($2, $1); } 1 EOS or die "Cannot define _regexp_pattern: $@"; } 1; __END__ =head1 NAME Storable - persistence for Perl data structures =head1 SYNOPSIS use Storable; store \%table, 'file'; $hashref = retrieve('file'); use Storable qw(nstore store_fd nstore_fd freeze thaw dclone); # Network order nstore \%table, 'file'; $hashref = retrieve('file'); # There is NO nretrieve() # Storing to and retrieving from an already opened file store_fd \@array, \*STDOUT; nstore_fd \%table, \*STDOUT; $aryref = fd_retrieve(\*SOCKET); $hashref = fd_retrieve(\*SOCKET); # Serializing to memory $serialized = freeze \%table; %table_clone = %{ thaw($serialized) }; # Deep (recursive) cloning $cloneref = dclone($ref); # Advisory locking use Storable qw(lock_store lock_nstore lock_retrieve) lock_store \%table, 'file'; lock_nstore \%table, 'file'; $hashref = lock_retrieve('file'); =head1 DESCRIPTION The Storable package brings persistence to your Perl data structures containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be conveniently stored to disk and retrieved at a later time. It can be used in the regular procedural way by calling C<store> with a reference to the object to be stored, along with the file name where the image should be written. The routine returns C<undef> for I/O problems or other internal error, a true value otherwise. Serious errors are propagated as a C<die> exception. To retrieve data stored to disk, use C<retrieve> with a file name. The objects stored into that file are recreated into memory for you, and a I<reference> to the root object is returned. In case an I/O error occurs while reading, C<undef> is returned instead. Other serious errors are propagated via C<die>. Since storage is performed recursively, you might want to stuff references to objects that share a lot of common data into a single array or hash table, and then store that object. That way, when you retrieve back the whole thing, the objects will continue to share what they originally shared. At the cost of a slight header overhead, you may store to an already opened file descriptor using the C<store_fd> routine, and retrieve from a file via C<fd_retrieve>. Those names aren't imported by default, so you will have to do that explicitly if you need those routines. The file descriptor you supply must be already opened, for read if you're going to retrieve and for write if you wish to store. store_fd(\%table, *STDOUT) || die "can't store to stdout\n"; $hashref = fd_retrieve(*STDIN); You can also store data in network order to allow easy sharing across multiple platforms, or when storing on a socket known to be remotely connected. The routines to call have an initial C<n> prefix for I<network>, as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be correctly restored so you don't have to know whether you're restoring from native or network ordered data. Double values are stored stringified to ensure portability as well, at the slight risk of loosing some precision in the last decimals. When using C<fd_retrieve>, objects are retrieved in sequence, one object (i.e. one recursive tree) per associated C<store_fd>. If you're more from the object-oriented camp, you can inherit from Storable and directly store your objects by invoking C<store> as a method. The fact that the root of the to-be-stored tree is a blessed reference (i.e. an object) is special-cased so that the retrieve does not provide a reference to that object but rather the blessed object reference itself. (Otherwise, you'd get a reference to that blessed object). =head1 MEMORY STORE The Storable engine can also store data into a Perl scalar instead, to later retrieve them. This is mainly used to freeze a complex structure in some safe compact memory place (where it can possibly be sent to another process via some IPC, since freezing the structure also serializes it in effect). Later on, and maybe somewhere else, you can thaw the Perl scalar out and recreate the original complex structure in memory. Surprisingly, the routines to be called are named C<freeze> and C<thaw>. If you wish to send out the frozen scalar to another machine, use C<nfreeze> instead to get a portable image. Note that freezing an object structure and immediately thawing it actually achieves a deep cloning of that structure: dclone(.) = thaw(freeze(.)) Storable provides you with a C<dclone> interface which does not create that intermediary scalar but instead freezes the structure in some internal memory space and then immediately thaws it out. =head1 ADVISORY LOCKING The C<lock_store> and C<lock_nstore> routine are equivalent to C<store> and C<nstore>, except that they get an exclusive lock on the file before writing. Likewise, C<lock_retrieve> does the same as C<retrieve>, but also gets a shared lock on the file before reading. As with any advisory locking scheme, the protection only works if you systematically use C<lock_store> and C<lock_retrieve>. If one side of your application uses C<store> whilst the other uses C<lock_retrieve>, you will get no protection at all. The internal advisory locking is implemented using Perl's flock() routine. If your system does not support any form of flock(), or if you share your files across NFS, you might wish to use other forms of locking by using modules such as LockFile::Simple which lock a file using a filesystem entry, instead of locking the file descriptor. =head1 SPEED The heart of Storable is written in C for decent speed. Extra low-level optimizations have been made when manipulating perl internals, to sacrifice encapsulation for the benefit of greater speed. =head1 CANONICAL REPRESENTATION Normally, Storable stores elements of hashes in the order they are stored internally by Perl, i.e. pseudo-randomly. If you set C<$Storable::canonical> to some C<TRUE> value, Storable will store hashes with the elements sorted by their key. This allows you to compare data structures by comparing their frozen representations (or even the compressed frozen representations), which can be useful for creating lookup tables for complicated queries. Canonical order does not imply network order; those are two orthogonal settings. =head1 CODE REFERENCES Since Storable version 2.05, CODE references may be serialized with the help of L<B::Deparse>. To enable this feature, set C<$Storable::Deparse> to a true value. To enable deserialization, C<$Storable::Eval> should be set to a true value. Be aware that deserialization is done through C<eval>, which is dangerous if the Storable file contains malicious data. You can set C<$Storable::Eval> to a subroutine reference which would be used instead of C<eval>. See below for an example using a L<Safe> compartment for deserialization of CODE references. If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false values, then the value of C<$Storable::forgive_me> (see below) is respected while serializing and deserializing. =head1 FORWARD COMPATIBILITY This release of Storable can be used on a newer version of Perl to serialize data which is not supported by earlier Perls. By default, Storable will attempt to do the right thing, by C<croak()>ing if it encounters data that it cannot deserialize. However, the defaults can be changed as follows: =over 4 =item utf8 data Perl 5.6 added support for Unicode characters with code points > 255, and Perl 5.8 has full support for Unicode characters in hash keys. Perl internally encodes strings with these characters using utf8, and Storable serializes them as utf8. By default, if an older version of Perl encounters a utf8 value it cannot represent, it will C<croak()>. To change this behaviour so that Storable deserializes utf8 encoded values as the string of bytes (effectively dropping the I<is_utf8> flag) set C<$Storable::drop_utf8> to some C<TRUE> value. This is a form of data loss, because with C<$drop_utf8> true, it becomes impossible to tell whether the original data was the Unicode string, or a series of bytes that happen to be valid utf8. =item restricted hashes Perl 5.8 adds support for restricted hashes, which have keys restricted to a given set, and can have values locked to be read only. By default, when Storable encounters a restricted hash on a perl that doesn't support them, it will deserialize it as a normal hash, silently discarding any placeholder keys and leaving the keys and all values unlocked. To make Storable C<croak()> instead, set C<$Storable::downgrade_restricted> to a C<FALSE> value. To restore the default set it back to some C<TRUE> value. The cperl PERL_PERTURB_KEYS_TOP hash strategy has a known problem with restricted hashes. =item huge objects On 64bit systems some data structures may exceed the 2G (i.e. I32_MAX) limit. On 32bit systems also strings between I32 and U32 (2G-4G). Since Storable 3.00 (not in perl5 core) we are able to store and retrieve these objects, even if perl5 itself is not able to handle them. These are strings longer then 4G, arrays with more then 2G elements and hashes with more then 2G elements. cperl forbids hashes with more than 2G elements, but this fail in cperl then. perl5 itself at least until 5.26 allows it, but cannot iterate over them. Note that creating those objects might cause out of memory exceptions by the operating system before perl has a chance to abort. =item files from future versions of Storable Earlier versions of Storable would immediately croak if they encountered a file with a higher internal version number than the reading Storable knew about. Internal version numbers are increased each time new data types (such as restricted hashes) are added to the vocabulary of the file format. This meant that a newer Storable module had no way of writing a file readable by an older Storable, even if the writer didn't store newer data types. This version of Storable will defer croaking until it encounters a data type in the file that it does not recognize. This means that it will continue to read files generated by newer Storable modules which are careful in what they write out, making it easier to upgrade Storable modules in a mixed environment. The old behaviour of immediate croaking can be re-instated by setting C<$Storable::accept_future_minor> to some C<FALSE> value. =back All these variables have no effect on a newer Perl which supports the relevant feature. =head1 ERROR REPORTING Storable uses the "exception" paradigm, in that it does not try to workaround failures: if something bad happens, an exception is generated from the caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap those exceptions. When Storable croaks, it tries to report the error via the C<logcroak()> routine from the C<Log::Agent> package, if it is available. Normal errors are reported by having store() or retrieve() return C<undef>. Such errors are usually I/O errors (or truncated stream errors at retrieval). When Storable throws the "Max. recursion depth with nested structures exceeded" error we are already out of stack space. Unfortunately on some earlier perl versions cleaning up a recursive data structure recurses into the free calls, which will lead to stack overflows in the cleanup. This data structure is not properly cleaned up then, it will only be destroyed during global destruction. =head1 WIZARDS ONLY =head2 Hooks Any class may define hooks that will be called during the serialization and deserialization process on objects that are instances of that class. Those hooks can redefine the way serialization is performed (and therefore, how the symmetrical deserialization should be conducted). Since we said earlier: dclone(.) = thaw(freeze(.)) everything we say about hooks should also hold for deep cloning. However, hooks get to know whether the operation is a mere serialization, or a cloning. Therefore, when serializing hooks are involved, dclone(.) <> thaw(freeze(.)) Well, you could keep them in sync, but there's no guarantee it will always hold on classes somebody else wrote. Besides, there is little to gain in doing so: a serializing hook could keep only one attribute of an object, which is probably not what should happen during a deep cloning of that same object. Here is the hooking interface: =over 4 =item C<STORABLE_freeze> I<obj>, I<cloning> The serializing hook, called on the object during serialization. It can be inherited, or defined in the class itself, like any other method. Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating whether we're in a dclone() or a regular serialization via store() or freeze(). Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized is the serialized form to be used, and the optional $ref1, $ref2, etc... are extra references that you wish to let the Storable engine serialize. At deserialization time, you will be given back the same LIST, but all the extra references will be pointing into the deserialized structure. The B<first time> the hook is hit in a serialization flow, you may have it return an empty list. That will signal the Storable engine to further discard that hook for this class and to therefore revert to the default serialization of the underlying Perl data. The hook will again be normally processed in the next serialization. Unless you know better, serializing hook should always say: sub STORABLE_freeze { my ($self, $cloning) = @_; return if $cloning; # Regular default serialization .... } in order to keep reasonable dclone() semantics. =item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ... The deserializing hook called on the object during deserialization. But wait: if we're deserializing, there's no object yet... right? Wrong: the Storable engine creates an empty one for you. If you know Eiffel, you can view C<STORABLE_thaw> as an alternate creation routine. This means the hook can be inherited like any other method, and that I<obj> is your blessed reference for this particular instance. The other arguments should look familiar if you know C<STORABLE_freeze>: I<cloning> is true when we're part of a deep clone operation, I<serialized> is the serialized string you returned to the engine in C<STORABLE_freeze>, and there may be an optional list of references, in the same order you gave them at serialization time, pointing to the deserialized objects (which have been processed courtesy of the Storable engine). When the Storable engine does not find any C<STORABLE_thaw> hook routine, it tries to load the class by requiring the package dynamically (using the blessed package name), and then re-attempts the lookup. If at that time the hook cannot be located, the engine croaks. Note that this mechanism will fail if you define several classes in the same file, but L<perlmod> warned you. It is up to you to use this information to populate I<obj> the way you want. Returned value: none. =item C<STORABLE_attach> I<class>, I<cloning>, I<serialized> While C<STORABLE_freeze> and C<STORABLE_thaw> are useful for classes where each instance is independent, this mechanism has difficulty (or is incompatible) with objects that exist as common process-level or system-level resources, such as singleton objects, database pools, caches or memoized objects. The alternative C<STORABLE_attach> method provides a solution for these shared objects. Instead of C<STORABLE_freeze> --E<gt> C<STORABLE_thaw>, you implement C<STORABLE_freeze> --E<gt> C<STORABLE_attach> instead. Arguments: I<class> is the class we are attaching to, I<cloning> is a flag indicating whether we're in a dclone() or a regular de-serialization via thaw(), and I<serialized> is the stored string for the resource object. Because these resource objects are considered to be owned by the entire process/system, and not the "property" of whatever is being serialized, no references underneath the object should be included in the serialized string. Thus, in any class that implements C<STORABLE_attach>, the C<STORABLE_freeze> method cannot return any references, and C<Storable> will throw an error if C<STORABLE_freeze> tries to return references. All information required to "attach" back to the shared resource object B<must> be contained B<only> in the C<STORABLE_freeze> return string. Otherwise, C<STORABLE_freeze> behaves as normal for C<STORABLE_attach> classes. Because C<STORABLE_attach> is passed the class (rather than an object), it also returns the object directly, rather than modifying the passed object. Returned value: object of type C<class> =back =head2 Predicates Predicates are not exportable. They must be called by explicitly prefixing them with the Storable package name. =over 4 =item C<Storable::last_op_in_netorder> The C<Storable::last_op_in_netorder()> predicate will tell you whether network order was used in the last store or retrieve operation. If you don't know how to use this, just forget about it. =item C<Storable::is_storing> Returns true if within a store operation (via STORABLE_freeze hook). =item C<Storable::is_retrieving> Returns true if within a retrieve operation (via STORABLE_thaw hook). =back =head2 Recursion With hooks comes the ability to recurse back to the Storable engine. Indeed, hooks are regular Perl code, and Storable is convenient when it comes to serializing and deserializing things, so why not use it to handle the serialization string? There are a few things you need to know, however: =over 4 =item * From Storable 3.05 to 3.13 we probed for the stack recursion limit for references, arrays and hashes to a maximal depth of ~1200-35000, otherwise we might fall into a stack-overflow. On JSON::XS this limit is 512 btw. With references not immediately referencing each other there's no such limit yet, so you might fall into such a stack-overflow segfault. This probing and the checks we performed have some limitations: =over =item * the stack size at build time might be different at run time, eg. the stack size may have been modified with ulimit(1). If it's larger at run time Storable may fail the freeze() or thaw() unnecessarily. If it's larger at build time Storable may segmentation fault when processing a deep structure at run time. =item * the stack size might be different in a thread. =item * array and hash recursion limits are checked separately against the same recursion depth, a frozen structure with a large sequence of nested arrays within many nested hashes may exhaust the processor stack without triggering Storable's recursion protection. =back So these now have simple defaults rather than probing at build-time. You can control the maximum array and hash recursion depths by modifying C<$Storable::recursion_limit> and C<$Storable::recursion_limit_hash> respectively. Either can be set to C<-1> to prevent any depth checks, though this isn't recommended. If you want to test what the limits are, the F<stacksize> tool is included in the C<Storable> distribution. =item * You can create endless loops if the things you serialize via freeze() (for instance) point back to the object we're trying to serialize in the hook. =item * Shared references among objects will not stay shared: if we're serializing the list of object [A, C] where both object A and C refer to the SAME object B, and if there is a serializing hook in A that says freeze(B), then when deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D, a deep clone of B'. The topology was not preserved. =item * The maximal stack recursion limit for your system is returned by C<stack_depth()> and C<stack_depth_hash()>. The hash limit is usually half the size of the array and ref limit, as the Perl hash API is not optimal. =back That's why C<STORABLE_freeze> lets you provide a list of references to serialize. The engine guarantees that those will be serialized in the same context as the other objects, and therefore that shared objects will stay shared. In the above [A, C] example, the C<STORABLE_freeze> hook could return: ("something", $self->{B}) and the B part would be serialized by the engine. In C<STORABLE_thaw>, you would get back the reference to the B' object, deserialized for you. Therefore, recursion should normally be avoided, but is nonetheless supported. =head2 Deep Cloning There is a Clone module available on CPAN which implements deep cloning natively, i.e. without freezing to memory and thawing the result. It is aimed to replace Storable's dclone() some day. However, it does not currently support Storable hooks to redefine the way deep cloning is performed. =head1 Storable magic Yes, there's a lot of that :-) But more precisely, in UNIX systems there's a utility called C<file>, which recognizes data files based on their contents (usually their first few bytes). For this to work, a certain file called F<magic> needs to taught about the I<signature> of the data. Where that configuration file lives depends on the UNIX flavour; often it's something like F</usr/share/misc/magic> or F</etc/magic>. Your system administrator needs to do the updating of the F<magic> file. The necessary signature information is output to STDOUT by invoking Storable::show_file_magic(). Note that the GNU implementation of the C<file> utility, version 3.38 or later, is expected to contain support for recognising Storable files out-of-the-box, in addition to other kinds of Perl files. You can also use the following functions to extract the file header information from Storable images: =over =item $info = Storable::file_magic( $filename ) If the given file is a Storable image return a hash describing it. If the file is readable, but not a Storable image return C<undef>. If the file does not exist or is unreadable then croak. The hash returned has the following elements: =over =item C<version> This returns the file format version. It is a string like "2.7". Note that this version number is not the same as the version number of the Storable module itself. For instance Storable v0.7 create files in format v2.0 and Storable v2.15 create files in format v2.7. The file format version number only increment when additional features that would confuse older versions of the module are added. Files older than v2.0 will have the one of the version numbers "-1", "0" or "1". No minor number was used at that time. =item C<version_nv> This returns the file format version as number. It is a string like "2.007". This value is suitable for numeric comparisons. The constant function C<Storable::BIN_VERSION_NV> returns a comparable number that represents the highest file version number that this version of Storable fully supports (but see discussion of C<$Storable::accept_future_minor> above). The constant C<Storable::BIN_WRITE_VERSION_NV> function returns what file version is written and might be less than C<Storable::BIN_VERSION_NV> in some configurations. =item C<major>, C<minor> This also returns the file format version. If the version is "2.7" then major would be 2 and minor would be 7. The minor element is missing for when major is less than 2. =item C<hdrsize> The is the number of bytes that the Storable header occupies. =item C<netorder> This is TRUE if the image store data in network order. This means that it was created with nstore() or similar. =item C<byteorder> This is only present when C<netorder> is FALSE. It is the $Config{byteorder} string of the perl that created this image. It is a string like "1234" (32 bit little endian) or "87654321" (64 bit big endian). This must match the current perl for the image to be readable by Storable. =item C<intsize>, C<longsize>, C<ptrsize>, C<nvsize> These are only present when C<netorder> is FALSE. These are the sizes of various C datatypes of the perl that created this image. These must match the current perl for the image to be readable by Storable. The C<nvsize> element is only present for file format v2.2 and higher. =item C<file> The name of the file. =back =item $info = Storable::read_magic( $buffer ) =item $info = Storable::read_magic( $buffer, $must_be_file ) The $buffer should be a Storable image or the first few bytes of it. If $buffer starts with a Storable header, then a hash describing the image is returned, otherwise C<undef> is returned. The hash has the same structure as the one returned by Storable::file_magic(). The C<file> element is true if the image is a file image. If the $must_be_file argument is provided and is TRUE, then return C<undef> unless the image looks like it belongs to a file dump. The maximum size of a Storable header is currently 21 bytes. If the provided $buffer is only the first part of a Storable image it should at least be this long to ensure that read_magic() will recognize it as such. =back =head1 EXAMPLES Here are some code samples showing a possible usage of Storable: use Storable qw(store retrieve freeze thaw dclone); %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1); store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n"; $colref = retrieve('mycolors'); die "Unable to retrieve from mycolors!\n" unless defined $colref; printf "Blue is still %lf\n", $colref->{'Blue'}; $colref2 = dclone(\%color); $str = freeze(\%color); printf "Serialization of %%color is %d bytes long.\n", length($str); $colref3 = thaw($str); which prints (on my machine): Blue is still 0.100000 Serialization of %color is 102 bytes long. Serialization of CODE references and deserialization in a safe compartment: =for example begin use Storable qw(freeze thaw); use Safe; use strict; my $safe = new Safe; # because of opcodes used in "use strict": $safe->permit(qw(:default require)); local $Storable::Deparse = 1; local $Storable::Eval = sub { $safe->reval($_[0]) }; my $serialized = freeze(sub { 42 }); my $code = thaw($serialized); $code->() == 42; =for example end =for example_testing is( $code->(), 42 ); =head1 SECURITY WARNING B<Do not accept Storable documents from untrusted sources!> Some features of Storable can lead to security vulnerabilities if you accept Storable documents from untrusted sources with the default flags. Most obviously, the optional (off by default) CODE reference serialization feature allows transfer of code to the deserializing process. Furthermore, any serialized object will cause Storable to helpfully load the module corresponding to the class of the object in the deserializing module. For manipulated module names, this can load almost arbitrary code. Finally, the deserialized object's destructors will be invoked when the objects get destroyed in the deserializing process. Maliciously crafted Storable documents may put such objects in the value of a hash key that is overridden by another key/value pair in the same hash, thus causing immediate destructor execution. To disable blessing objects while thawing/retrieving remove the flag C<BLESS_OK> = 2 from C<$Storable::flags> or set the 2nd argument for thaw/retrieve to 0. To disable tieing data while thawing/retrieving remove the flag C<TIE_OK> = 4 from C<$Storable::flags> or set the 2nd argument for thaw/retrieve to 0. With the default setting of C<$Storable::flags> = 6, creating or destroying random objects, even renamed objects can be controlled by an attacker. See CVE-2015-1592 and its metasploit module. If your application requires accepting data from untrusted sources, you are best off with a less powerful and more-likely safe serialization format and implementation. If your data is sufficiently simple, L<Cpanel::JSON::XS>, L<Data::MessagePack> or L<Sereal> are the best choices and offer maximum interoperability, but note that Sereal is L<unsafe by default|Sereal::Decoder/ROBUSTNESS>. =head1 WARNING If you're using references as keys within your hash tables, you're bound to be disappointed when retrieving your data. Indeed, Perl stringifies references used as hash table keys. If you later wish to access the items via another reference stringification (i.e. using the same reference that was used for the key originally to record the value into the hash table), it will work because both references stringify to the same string. It won't work across a sequence of C<store> and C<retrieve> operations, however, because the addresses in the retrieved objects, which are part of the stringified references, will probably differ from the original addresses. The topology of your structure is preserved, but not hidden semantics like those. On platforms where it matters, be sure to call C<binmode()> on the descriptors that you pass to Storable functions. Storing data canonically that contains large hashes can be significantly slower than storing the same data normally, as temporary arrays to hold the keys for each hash have to be allocated, populated, sorted and freed. Some tests have shown a halving of the speed of storing -- the exact penalty will depend on the complexity of your data. There is no slowdown on retrieval. =head1 REGULAR EXPRESSIONS Storable now has experimental support for storing regular expressions, but there are significant limitations: =over =item * perl 5.8 or later is required. =item * regular expressions with code blocks, ie C</(?{ ... })/> or C</(??{ ... })/> will throw an exception when thawed. =item * regular expression syntax and flags have changed over the history of perl, so a regular expression that you freeze in one version of perl may fail to thaw or behave differently in another version of perl. =item * depending on the version of perl, regular expressions can change in behaviour depending on the context, but later perls will bake that behaviour into the regexp. =back Storable will throw an exception if a frozen regular expression cannot be thawed. =head1 BUGS You can't store GLOB, FORMLINE, etc.... If you can define semantics for those operations, feel free to enhance Storable so that it can deal with them. The store functions will C<croak> if they run into such references unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that case, the fatal message is converted to a warning and some meaningless string is stored instead. Setting C<$Storable::canonical> may not yield frozen strings that compare equal due to possible stringification of numbers. When the string version of a scalar exists, it is the form stored; therefore, if you happen to use your numbers as strings between two freezing operations on the same data structures, you will get different results. When storing doubles in network order, their value is stored as text. However, you should also not expect non-numeric floating-point values such as infinity and "not a number" to pass successfully through a nstore()/retrieve() pair. As Storable neither knows nor cares about character sets (although it does know that characters may be more than eight bits wide), any difference in the interpretation of character codes between a host and a target system is your problem. In particular, if host and target use different code points to represent the characters used in the text representation of floating-point numbers, you will not be able be able to exchange floating-point data, even with nstore(). C<Storable::drop_utf8> is a blunt tool. There is no facility either to return B<all> strings as utf8 sequences, or to attempt to convert utf8 data back to 8 bit and C<croak()> if the conversion fails. Prior to Storable 2.01, no distinction was made between signed and unsigned integers on storing. By default Storable prefers to store a scalars string representation (if it has one) so this would only cause problems when storing large unsigned integers that had never been converted to string or floating point. In other words values that had been generated by integer operations such as logic ops and then not used in any string or arithmetic context before storing. =head2 64 bit data in perl 5.6.0 and 5.6.1 This section only applies to you if you have existing data written out by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which has been configured with 64 bit integer support (not the default) If you got a precompiled perl, rather than running Configure to build your own perl from source, then it almost certainly does not affect you, and you can stop reading now (unless you're curious). If you're using perl on Windows it does not affect you. Storable writes a file header which contains the sizes of various C language types for the C compiler that built Storable (when not writing in network order), and will refuse to load files written by a Storable not on the same (or compatible) architecture. This check and a check on machine byteorder is needed because the size of various fields in the file are given by the sizes of the C language types, and so files written on different architectures are incompatible. This is done for increased speed. (When writing in network order, all fields are written out as standard lengths, which allows full interworking, but takes longer to read and write) Perl 5.6.x introduced the ability to optional configure the perl interpreter to use C's C<long long> type to allow scalars to store 64 bit integers on 32 bit systems. However, due to the way the Perl configuration system generated the C configuration files on non-Windows platforms, and the way Storable generates its header, nothing in the Storable file header reflected whether the perl writing was using 32 or 64 bit integers, despite the fact that Storable was storing some data differently in the file. Hence Storable running on perl with 64 bit integers will read the header from a file written by a 32 bit perl, not realise that the data is actually in a subtly incompatible format, and then go horribly wrong (possibly crashing) if it encountered a stored integer. This is a design failure. Storable has now been changed to write out and read in a file header with information about the size of integers. It's impossible to detect whether an old file being read in was written with 32 or 64 bit integers (they have the same header) so it's impossible to automatically switch to a correct backwards compatibility mode. Hence this Storable defaults to the new, correct behaviour. What this means is that if you have data written by Storable 1.x running on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux then by default this Storable will refuse to read it, giving the error I<Byte order is not compatible>. If you have such data then you should set C<$Storable::interwork_56_64bit> to a true value to make this Storable read and write files with the old header. You should also migrate your data, or any older perl you are communicating with, to this current version of Storable. If you don't have data written with specific configuration of perl described above, then you do not and should not do anything. Don't set the flag - not only will Storable on an identically configured perl refuse to load them, but Storable a differently configured perl will load them believing them to be correct for it, and then may well fail or crash part way through reading them. =head1 CREDITS Thank you to (in chronological order): Jarkko Hietaniemi <jhi@iki.fi> Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de> Benjamin A. Holzman <bholzman@earthlink.net> Andrew Ford <A.Ford@ford-mason.co.uk> Gisle Aas <gisle@aas.no> Jeff Gresham <gresham_jeffrey@jpmorgan.com> Murray Nesbitt <murray@activestate.com> Marc Lehmann <pcg@opengroup.org> Justin Banks <justinb@wamnet.com> Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!) Salvador Ortiz Garcia <sog@msg.com.mx> Dominic Dunlop <domo@computer.org> Erik Haugan <erik@solbors.no> Benjamin A. Holzman <ben.holzman@grantstreet.com> Reini Urban <rurban@cpan.org> Todd Rinaldo <toddr@cpanel.net> Aaron Crane <arc@cpan.org> for their bug reports, suggestions and contributions. Benjamin Holzman contributed the tied variable support, Andrew Ford contributed the canonical order for hashes, and Gisle Aas fixed a few misunderstandings of mine regarding the perl internals, and optimized the emission of "tags" in the output streams by simply counting the objects instead of tagging them (leading to a binary incompatibility for the Storable image starting at version 0.6--older images are, of course, still properly understood). Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading and references to tied items support. Benjamin Holzman added a performance improvement for overloaded classes; thanks to Grant Street Group for footing the bill. Reini Urban took over maintenance from p5p, and added security fixes and huge object support. =head1 AUTHOR Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>> Maintenance is now done by cperl L<http://perl11.org/cperl> Please e-mail us with problems, bug fixes, comments and complaints, although if you have compliments you should send them to Raphael. Please don't e-mail Raphael with problems, as he no longer works on Storable, and your message will be delayed while he forwards it to us. =head1 SEE ALSO L<Clone>. =cut PK d �[ lib/.existsnu �[��� PK d �[ lib/auto/Storable/.existsnu �[��� PK � �[� .� man3/Test::Needs.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Needs 3" .TH Test::Needs 3 "2023-01-22" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Needs \- Skip tests when modules not available .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # need one module \& use Test::Needs \*(AqSome::Module\*(Aq; \& \& # need multiple modules \& use Test::Needs \*(AqSome::Module\*(Aq, \*(AqSome::Other::Module\*(Aq; \& \& # need a given version of a module \& use Test::Needs { \& \*(AqSome::Module\*(Aq => \*(Aq1.005\*(Aq, \& }; \& \& # check later \& use Test::Needs; \& test_needs \*(AqSome::Module\*(Aq; \& \& # skips remainder of subtest \& use Test::More; \& use Test::Needs; \& subtest \*(Aqmy subtest\*(Aq => sub { \& test_needs \*(AqSome::Module\*(Aq; \& ... \& }; \& \& # check perl version \& use Test::Needs { perl => 5.020 }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Skip test scripts if modules are not available. The requested modules will be loaded, and optionally have their versions checked. If the module is missing, the test script will be skipped. Modules that are found but fail to compile will exit with an error rather than skip. .PP If used in a subtest, the remainder of the subtest will be skipped. .PP Skipping will work even if some tests have already been run, or if a plan has been declared. .PP Versions are checked via a \f(CW\*(C`$module\->VERSION($wanted_version)\*(C'\fR call. Versions must be provided in a format that will be accepted. No extra processing is done on them. .PP If \f(CW\*(C`perl\*(C'\fR is used as a module, the version is checked against the running perl version ($]). The version can be specified as a number, dotted-decimal string, v\-string, or version object. .PP If the \f(CW\*(C`RELEASE_TESTING\*(C'\fR environment variable is set, the tests will fail rather than skip. Subtests will be aborted, but the test script will continue running after that point. .SH "EXPORTS" .IX Header "EXPORTS" .SS "test_needs" .IX Subsection "test_needs" Has the same interface as when using Test::Needs in a \f(CW\*(C`use\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Test::Requires" 4 .IX Item "Test::Requires" A similar module, with some important differences. Test::Requires will act as a \f(CW\*(C`use\*(C'\fR statement (despite its name), calling the import sub. Under \&\f(CW\*(C`RELEASE_TESTING\*(C'\fR, it will \s-1BAIL_OUT\s0 if a module fails to load rather than using a normal test fail. It also doesn't distinguish between missing modules and broken modules. .IP "Test2::Require::Module" 4 .IX Item "Test2::Require::Module" Part of the Test2 ecosystem. Only supports running as a \f(CW\*(C`use\*(C'\fR command to skip an entire plan. .IP "Test2::Require::Perl" 4 .IX Item "Test2::Require::Perl" Part of the Test2 ecosystem. Only supports running as a \f(CW\*(C`use\*(C'\fR command to skip an entire plan. Checks perl versions. .IP "Test::If" 4 .IX Item "Test::If" Acts as a \f(CW\*(C`use\*(C'\fR statement. Only supports running as a \f(CW\*(C`use\*(C'\fR command to skip an entire plan. Can skip based on subref results. .SH "AUTHORS" .IX Header "AUTHORS" haarg \- Graham Knop (cpan:HAARG) <haarg@haarg.org> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" None so far. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2016 the Test::Needs \*(L"\s-1AUTHORS\*(R"\s0 and \*(L"\s-1CONTRIBUTORS\*(R"\s0 as listed above. .PP This library is free software and may be distributed under the same terms as perl itself. See <http://dev.perl.org/licenses/>. PK � �[ arch/auto/Test/Needs/.existsnu �[��� PK � �[P��Y�! �! lib/Test/Needs.pmnu ��6�$ package Test::Needs; use strict; use warnings; no warnings 'once'; our $VERSION = '0.002010'; $VERSION =~ tr/_//d; BEGIN { *_WORK_AROUND_HINT_LEAKAGE = "$]" < 5.011 && !("$]" >= 5.009004 && "$]" < 5.010001) ? sub(){1} : sub(){0}; *_WORK_AROUND_BROKEN_MODULE_STATE = "$]" < 5.009 ? sub(){1} : sub(){0}; # this allows regexes to match wide characters in vstrings if ("$]" >= 5.006001 && "$]" <= 5.006002) { require utf8; utf8->import; } } our @EXPORT = qw(test_needs); our $Level = 0; sub _try_require { local %^H if _WORK_AROUND_HINT_LEAKAGE; my ($module) = @_; (my $file = "$module.pm") =~ s{::|'}{/}g; my $err; { local $@; eval { require $file } or $err = $@; } if (defined $err) { delete $INC{$file} if _WORK_AROUND_BROKEN_MODULE_STATE; die $err unless $err =~ /\ACan't locate \Q$file\E/; return !1; } !0; } sub _croak { my $message = join '', @_; my $i = 1; while (my ($p, $f, $l) = caller($i++)) { next if $p =~ /\ATest::Needs(?:::|\z)/; die "$message at $f line $l.\n"; } die $message; } sub _try_version { my ($module, $version) = @_; local $@; !!eval { $module->VERSION($version); 1 }; } sub _numify_version { for ($_[0]) { return !$_ ? 0 : /^[0-9]+(?:\.[0-9]+)?$/ ? sprintf('%.6f', $_) : /^v?([0-9]+(?:\.[0-9]+)*)$/ ? sprintf('%d.%03d%03d', ((split /\./, $1), 0, 0)[0..2]) : /^([\x05-\x07])(.*)$/s ? sprintf('%d.%03d%03d', ((map ord, /(.)/gs), 0, 0)[0..2]) : _croak qq{version "$_" does not look like a number}; } } sub _find_missing { my @bad = map { my ($module, $version) = @$_; $module eq 'perl' ? do { $version = _numify_version($version); "$]" < $version ? (sprintf "perl %s (have %.6f)", $version, $]) : () } : $module =~ /^\d|[^\w:]|:::|[^:]:[^:]|^:|:$/ ? _croak sprintf qq{"%s" does not look like a module name}, $module : _try_require($module) ? ( defined $version && !_try_version($module, $version) ? "$module $version (have ".(defined $module->VERSION ? $module->VERSION : 'undef').')' : () ) : $version ? "$module $version" : $module; } _pairs(@_); @bad ? "Need " . join(', ', @bad) : undef; } sub import { my $class = shift; my $target = caller; if (@_) { local $Level = $Level + 1; test_needs(@_); } no strict 'refs'; *{"${target}::$_"} = \&{"${class}::$_"} for @{"${class}::EXPORT"}; } sub test_needs { my $missing = _find_missing(@_); local $Level = $Level + 1; if ($missing) { if ($ENV{RELEASE_TESTING}) { _fail("$missing due to RELEASE_TESTING"); } else { _skip($missing); } } return 1; } sub _skip { local $Level = $Level + 1; _fail_or_skip($_[0], 0) } sub _fail { local $Level = $Level + 1; _fail_or_skip($_[0], 1) } sub _pairs { map +( ref eq 'HASH' ? do { my $arg = $_; map [ $_ => $arg->{$_} ], sort keys %$arg; } : ref eq 'ARRAY' ? do { my $arg = $_; map [ @{$arg}[$_*2,$_*2+1] ], 0 .. int($#$arg / 2); } : [ $_ ] ), @_; } sub _fail_or_skip { my ($message, $fail) = @_; if ($INC{'Test2/API.pm'}) { my $ctx = Test2::API::context(level => $Level); my $hub = $ctx->hub; if ($fail) { $ctx->ok(0, "Test::Needs modules available", [$message]); } else { my $plan = $hub->plan; my $tests = $hub->count; if ($plan || $tests) { my $skips = $plan && $plan ne 'NO PLAN' ? $plan - $tests : 1; $ctx->skip("Test::Needs modules not available") for 1 .. $skips; $ctx->note($message); } else { $ctx->plan(0, 'SKIP', $message); } } $ctx->done_testing; $ctx->release if $Test2::API::VERSION < 1.302053; $ctx->send_event('+'._t2_terminate_event()); } elsif ($INC{'Test/Builder.pm'}) { local $Test::Builder::Level = $Test::Builder::Level + $Level; my $tb = Test::Builder->new; my $has_plan = Test::Builder->can('has_plan') ? 'has_plan' : sub { $_[0]->expected_tests || eval { $_[0]->current_test($_[0]->current_test); 'no_plan' } }; my $tests = $tb->current_test; if ($fail) { $tb->plan(tests => 1) unless $tb->$has_plan; $tests++; $tb->ok(0, "Test::Needs modules available"); $tb->diag($message); } else { my $plan = $tb->$has_plan; if ($plan || $tests) { my $skips = $plan && $plan ne 'no_plan' ? $plan - $tests : 1; $tb->skip("Test::Needs modules not available") for 1 .. $skips; $tests += $skips; Test::Builder->can('note') ? $tb->note($message) : print "# $message\n"; } else { $tb->skip_all($message); } } $tb->done_testing($tests) if Test::Builder->can('done_testing'); die bless {} => 'Test::Builder::Exception' if Test::Builder->can('parent') && $tb->parent; } else { if ($fail) { print "1..1\n"; print "not ok 1 - Test::Needs modules available\n"; print STDERR "# $message\n"; exit 1; } else { print "1..0 # SKIP $message\n"; } } exit 0; } my $terminate_event; sub _t2_terminate_event () { return $terminate_event if $terminate_event; local $@; $terminate_event = eval sprintf <<'END_CODE', __LINE__+2, __FILE__ or die "$@"; #line %d "%s" package # hide Test::Needs::Event::Terminate; use Test2::Event (); our @ISA = qw(Test2::Event); sub no_display { 1 } sub terminate { 0 } __PACKAGE__; END_CODE (my $pm = "$terminate_event.pm") =~ s{::}{/}g; $INC{$pm} = __FILE__; $terminate_event; } 1; __END__ =pod =encoding utf-8 =head1 NAME Test::Needs - Skip tests when modules not available =head1 SYNOPSIS # need one module use Test::Needs 'Some::Module'; # need multiple modules use Test::Needs 'Some::Module', 'Some::Other::Module'; # need a given version of a module use Test::Needs { 'Some::Module' => '1.005', }; # check later use Test::Needs; test_needs 'Some::Module'; # skips remainder of subtest use Test::More; use Test::Needs; subtest 'my subtest' => sub { test_needs 'Some::Module'; ... }; # check perl version use Test::Needs { perl => 5.020 }; =head1 DESCRIPTION Skip test scripts if modules are not available. The requested modules will be loaded, and optionally have their versions checked. If the module is missing, the test script will be skipped. Modules that are found but fail to compile will exit with an error rather than skip. If used in a subtest, the remainder of the subtest will be skipped. Skipping will work even if some tests have already been run, or if a plan has been declared. Versions are checked via a C<< $module->VERSION($wanted_version) >> call. Versions must be provided in a format that will be accepted. No extra processing is done on them. If C<perl> is used as a module, the version is checked against the running perl version (L<$]|perlvar/$]>). The version can be specified as a number, dotted-decimal string, v-string, or version object. If the C<RELEASE_TESTING> environment variable is set, the tests will fail rather than skip. Subtests will be aborted, but the test script will continue running after that point. =head1 EXPORTS =head2 test_needs Has the same interface as when using Test::Needs in a C<use>. =head1 SEE ALSO =over 4 =item L<Test::Requires> A similar module, with some important differences. L<Test::Requires> will act as a C<use> statement (despite its name), calling the import sub. Under C<RELEASE_TESTING>, it will BAIL_OUT if a module fails to load rather than using a normal test fail. It also doesn't distinguish between missing modules and broken modules. =item L<Test2::Require::Module> Part of the L<Test2> ecosystem. Only supports running as a C<use> command to skip an entire plan. =item L<Test2::Require::Perl> Part of the L<Test2> ecosystem. Only supports running as a C<use> command to skip an entire plan. Checks perl versions. =item L<Test::If> Acts as a C<use> statement. Only supports running as a C<use> command to skip an entire plan. Can skip based on subref results. =back =head1 AUTHORS haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org> =head1 CONTRIBUTORS None so far. =head1 COPYRIGHT AND LICENSE Copyright (c) 2016 the Test::Needs L</AUTHORS> and L</CONTRIBUTORS> as listed above. This library is free software and may be distributed under the same terms as perl itself. See L<http://dev.perl.org/licenses/>. =cut PK � �[ lib/auto/Test/Needs/.existsnu �[��� PK � �[��q� � man3/Template::Plugin::Math.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Math 3" .TH Template::Plugin::Math 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Math \- Plugin providing mathematical functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE Math %] \& \& [% Math.sqrt(9) %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Math plugin provides numerous mathematical functions for use within templates. .SH "METHODS" .IX Header "METHODS" \&\f(CW\*(C`Template::Plugin::Math\*(C'\fR makes available the following functions from the Perl core: .IP "abs" 4 .IX Item "abs" .PD 0 .IP "atan2" 4 .IX Item "atan2" .IP "cos" 4 .IX Item "cos" .IP "exp" 4 .IX Item "exp" .IP "hex" 4 .IX Item "hex" .IP "int" 4 .IX Item "int" .IP "log" 4 .IX Item "log" .IP "oct" 4 .IX Item "oct" .IP "rand" 4 .IX Item "rand" .IP "sin" 4 .IX Item "sin" .IP "sqrt" 4 .IX Item "sqrt" .IP "srand" 4 .IX Item "srand" .PD .PP In addition, if the Math::Trig module can be loaded, the following functions are also available: .IP "pi" 4 .IX Item "pi" .PD 0 .IP "tan" 4 .IX Item "tan" .IP "csc" 4 .IX Item "csc" .IP "cosec" 4 .IX Item "cosec" .IP "sec" 4 .IX Item "sec" .IP "cot" 4 .IX Item "cot" .IP "cotan" 4 .IX Item "cotan" .IP "asin" 4 .IX Item "asin" .IP "acos" 4 .IX Item "acos" .IP "atan" 4 .IX Item "atan" .IP "acsc" 4 .IX Item "acsc" .IP "acosec" 4 .IX Item "acosec" .IP "asec" 4 .IX Item "asec" .IP "acot" 4 .IX Item "acot" .IP "acotan" 4 .IX Item "acotan" .IP "sinh" 4 .IX Item "sinh" .IP "cosh" 4 .IX Item "cosh" .IP "tanh" 4 .IX Item "tanh" .IP "csch" 4 .IX Item "csch" .IP "cosech" 4 .IX Item "cosech" .IP "sech" 4 .IX Item "sech" .IP "coth" 4 .IX Item "coth" .IP "cotanh" 4 .IX Item "cotanh" .IP "asinh" 4 .IX Item "asinh" .IP "acosh" 4 .IX Item "acosh" .IP "atanh" 4 .IX Item "atanh" .IP "acsch" 4 .IX Item "acsch" .IP "acosech" 4 .IX Item "acosech" .IP "asech" 4 .IX Item "asech" .IP "acoth" 4 .IX Item "acoth" .IP "acotanh" 4 .IX Item "acotanh" .IP "rad2deg" 4 .IX Item "rad2deg" .IP "rad2grad" 4 .IX Item "rad2grad" .IP "deg2rad" 4 .IX Item "deg2rad" .IP "deg2grad" 4 .IX Item "deg2grad" .IP "grad2rad" 4 .IX Item "grad2rad" .IP "grad2deg" 4 .IX Item "grad2deg" .PD .PP If the Math::TrulyRandom module is available, and you've got the time to wait, the \f(CW\*(C`truly_random_number\*(C'\fR method is available: .PP .Vb 1 \& [% Math.truly_random_number %] .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[ �#��2 �2 man3/Template::Service.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Service 3" .TH Template::Service 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Service \- General purpose template processing service .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Service; \& \& my $service = Template::Service\->new({ \& PRE_PROCESS => [ \*(Aqconfig\*(Aq, \*(Aqheader\*(Aq ], \& POST_PROCESS => \*(Aqfooter\*(Aq, \& ERROR => { \& user => \*(Aquser/index.html\*(Aq, \& dbi => \*(Aqerror/database\*(Aq, \& default => \*(Aqerror/default\*(Aq, \& }, \& }); \& \& my $output = $service\->process($template_name, \e%replace) \& || die $service\->error(), "\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Service\*(C'\fR module implements an object class for providing a consistent template processing service. .PP Standard header (\s-1PRE_PROCESS\s0) and footer (\s-1POST_PROCESS\s0) templates may be specified which are prepended and appended to all templates processed by the service (but not any other templates or blocks \f(CW\*(C`INCLUDE\*(C'\fRd or \f(CW\*(C`PROCESS\*(C'\fRed from within). An \&\s-1ERROR\s0 hash may be specified which redirects the service to an alternate template file in the case of uncaught exceptions being thrown. This allows errors to be automatically handled by the service and a guaranteed valid response to be generated regardless of any processing problems encountered. .PP A default \f(CW\*(C`Template::Service\*(C'\fR object is created by the Template module. Any \f(CW\*(C`Template::Service\*(C'\fR options may be passed to the Template \&\fBnew()\fR constructor method and will be forwarded to the Template::Service constructor. .PP .Vb 1 \& use Template; \& \& my $template = Template\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }); .Ve .PP Similarly, the \f(CW\*(C`Template::Service\*(C'\fR constructor will forward all configuration parameters onto other default objects (e.g. Template::Context) that it may need to instantiate. .PP A \f(CW\*(C`Template::Service\*(C'\fR object (or subclass) can be explicitly instantiated and passed to the Template \fBnew()\fR constructor method as the \&\s-1SERVICE\s0 item. .PP .Vb 2 \& use Template; \& use Template::Service; \& \& my $service = Template::Service\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }); \& \& my $template = Template\->new({ \& SERVICE => $service, \& }); .Ve .PP The \f(CW\*(C`Template::Service\*(C'\fR module can be sub-classed to create custom service handlers. .PP .Vb 2 \& use Template; \& use MyOrg::Template::Service; \& \& my $service = MyOrg::Template::Service\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& COOL_OPTION => \*(Aqenabled in spades\*(Aq, \& }); \& \& my $template = Template\->new({ \& SERVICE => $service, \& }); .Ve .PP The Template module uses the Template::Config \&\fBservice()\fR factory method to create a default service object when required. The \f(CW$Template::Config::SERVICE\fR package variable may be set to specify an alternate service module. This will be loaded automatically and its \fBnew()\fR constructor method called by the \&\fBservice()\fR factory method when a default service object is required. Thus the previous example could be written as: .PP .Vb 1 \& use Template; \& \& $Template::Config::SERVICE = \*(AqMyOrg::Template::Service\*(Aq; \& \& my $template = Template\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& COOL_OPTION => \*(Aqenabled in spades\*(Aq, \& }); .Ve .SH "METHODS" .IX Header "METHODS" .SS "new(\e%config)" .IX Subsection "new(%config)" The \f(CW\*(C`new()\*(C'\fR constructor method is called to instantiate a \f(CW\*(C`Template::Service\*(C'\fR object. Configuration parameters may be specified as a \s-1HASH\s0 reference or as a list of \f(CW\*(C`name => value\*(C'\fR pairs. .PP .Vb 4 \& my $service1 = Template::Service\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }); \& \& my $service2 = Template::Service\->new( ERROR => \*(Aqerror.html\*(Aq ); .Ve .PP The \f(CW\*(C`new()\*(C'\fR method returns a \f(CW\*(C`Template::Service\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR on error. In the latter case, a relevant error message can be retrieved by the \&\fBerror()\fR class method or directly from the \&\f(CW$Template::Service::ERROR\fR package variable. .PP .Vb 2 \& my $service = Template::Service\->new(\e%config) \& || die Template::Service\->error(); \& \& my $service = Template::Service\->new(\e%config) \& || die $Template::Service::ERROR; .Ve .SS "process($input, \e%replace)" .IX Subsection "process($input, %replace)" The \f(CW\*(C`process()\*(C'\fR method is called to process a template specified as the first parameter, \f(CW$input\fR. This may be a file name, file handle (e.g. \f(CW\*(C`GLOB\*(C'\fR or \&\f(CW\*(C`IO::Handle\*(C'\fR) or a reference to a text string containing the template text. An additional hash reference may be passed containing template variable definitions. .PP The method processes the template, adding any \&\s-1PRE_PROCESS\s0 or \&\s-1POST_PROCESS\s0 templates defined, and returns the output text. An uncaught exception thrown by the template will be handled by a relevant \s-1ERROR\s0 handler if defined. Errors that occur in the \&\s-1PRE_PROCESS\s0 or \&\s-1POST_PROCESS\s0 templates, or those that occur in the main input template and aren't handled, cause the method to return \f(CW\*(C`undef\*(C'\fR to indicate failure. The appropriate error message can be retrieved via the \&\fBerror()\fR method. .PP .Vb 2 \& $service\->process(\*(Aqmyfile.html\*(Aq, { title => \*(AqMy Test File\*(Aq }) \& || die $service\->error(); .Ve .SS "\fBcontext()\fP" .IX Subsection "context()" Returns a reference to the internal context object which is, by default, an instance of the Template::Context class. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" The following list summarises the configuration options that can be provided to the \f(CW\*(C`Template::Service\*(C'\fR \fBnew()\fR constructor. Please consult Template::Manual::Config for further details and examples of each configuration option in use. .SS "\s-1PRE_PROCESS, POST_PROCESS\s0" .IX Subsection "PRE_PROCESS, POST_PROCESS" The \s-1PRE_PROCESS\s0 and \&\s-1POST_PROCESS\s0 options may be set to contain the name(s) of template files which should be processed immediately before and/or after each template. These do not get added to templates processed into a document via directives such as \f(CW\*(C`INCLUDE\*(C'\fR \&\f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`WRAPPER\*(C'\fR, etc. .PP .Vb 4 \& my $service = Template::Service\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }; .Ve .PP Multiple templates may be specified as a reference to a list. Each is processed in the order defined. .PP .Vb 4 \& my $service = Template::Service\->new({ \& PRE_PROCESS => [ \*(Aqconfig\*(Aq, \*(Aqheader\*(Aq ], \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }; .Ve .SS "\s-1PROCESS\s0" .IX Subsection "PROCESS" The \s-1PROCESS\s0 option may be set to contain the name(s) of template files which should be processed instead of the main template passed to the \f(CW\*(C`Template::Service\*(C'\fR \fBprocess()\fR method. This can be used to apply consistent wrappers around all templates, similar to the use of \&\s-1PRE_PROCESS\s0 and \&\s-1POST_PROCESS\s0 templates. .PP .Vb 3 \& my $service = Template::Service\->new({ \& PROCESS => \*(Aqcontent\*(Aq, \& }; \& \& # processes \*(Aqcontent\*(Aq instead of \*(Aqfoo.html\*(Aq \& $service\->process(\*(Aqfoo.html\*(Aq); .Ve .PP A reference to the original template is available in the \f(CW\*(C`template\*(C'\fR variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by \&'\f(CW\*(C`$\*(C'\fR') to an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive. .PP Example \f(CW\*(C`PROCESS\*(C'\fR template: .PP .Vb 8 \& <html> \& <head> \& <title>[% template.title %]</title> \& </head> \& <body> \& [% PROCESS $template %] \& </body> \& </html> .Ve .SS "\s-1ERROR\s0" .IX Subsection "ERROR" The \s-1ERROR\s0 (or \f(CW\*(C`ERRORS\*(C'\fR if you prefer) configuration item can be used to name a single template or specify a hash array mapping exception types to templates which should be used for error handling. If an uncaught exception is raised from within a template then the appropriate error template will instead be processed. .PP If specified as a single value then that template will be processed for all uncaught exceptions. .PP .Vb 3 \& my $service = Template::Service\->new({ \& ERROR => \*(Aqerror.html\*(Aq \& }); .Ve .PP If the \s-1ERROR\s0 or \s-1ERRORS\s0 item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A \f(CW\*(C`default\*(C'\fR template may be provided for the general case. .PP .Vb 7 \& my $service = Template::Service\->new({ \& ERRORS => { \& user => \*(Aquser/index.html\*(Aq, \& dbi => \*(Aqerror/database\*(Aq, \& default => \*(Aqerror/default\*(Aq, \& }, \& }); .Ve .SS "\s-1AUTO_RESET\s0" .IX Subsection "AUTO_RESET" The \s-1AUTO_RESET\s0 option is set by default and causes the local \f(CW\*(C`BLOCKS\*(C'\fR cache for the Template::Context object to be reset on each call to the Template \fBprocess()\fR method. This ensures that any \f(CW\*(C`BLOCK\*(C'\fRs defined within a template will only persist until that template is finished processing. .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \s-1DEBUG\s0 option can be used to enable debugging messages from the \f(CW\*(C`Template::Service\*(C'\fR module by setting it to include the \f(CW\*(C`DEBUG_SERVICE\*(C'\fR value. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_SERVICE, \& }); .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Context PK � �[�+��z z man3/Template::Plugin::URL.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::URL 3" .TH Template::Plugin::URL 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::URL \- Plugin to construct complex URLs .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE url(\*(Aq/cgi\-bin/foo.pl\*(Aq) %] \& \& [% url(debug = 1, id = 123) %] \& # ==> /cgi/bin/foo.pl?debug=1&id=123 \& \& [% USE mycgi = url(\*(Aq/cgi\-bin/bar.pl\*(Aq, mode=\*(Aqbrowse\*(Aq, debug=1) %] \& \& [% mycgi %] \& # ==> /cgi/bin/bar.pl?mode=browse&debug=1 \& \& [% mycgi(mode=\*(Aqsubmit\*(Aq) %] \& # ==> /cgi/bin/bar.pl?mode=submit&debug=1 \& \& [% mycgi(debug=\*(Aqd2 p0\*(Aq, id=\*(AqD4\-2k[4]\*(Aq) %] \& # ==> /cgi\-bin/bar.pl?mode=browse&debug=d2%20p0&id=D4\-2k%5B4%5D .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`URL\*(C'\fR plugin can be used to construct complex URLs from a base stem and a hash array of additional query parameters. .PP The constructor should be passed a base \s-1URL\s0 and optionally, a hash array reference of default parameters and values. Used from with a template, it would look something like the following: .PP .Vb 3 \& [% USE url(\*(Aqhttp://www.somewhere.com/cgi\-bin/foo.pl\*(Aq) %] \& [% USE url(\*(Aq/cgi\-bin/bar.pl\*(Aq, mode=\*(Aqbrowse\*(Aq) %] \& [% USE url(\*(Aq/cgi\-bin/baz.pl\*(Aq, mode=\*(Aqbrowse\*(Aq, debug=1) %] .Ve .PP When the plugin is then called without any arguments, the default base and parameters are returned as a formatted query string. .PP .Vb 1 \& [% url %] .Ve .PP For the above three examples, these will produce the following outputs: .PP .Vb 3 \& http://www.somewhere.com/cgi\-bin/foo.pl \& /cgi\-bin/bar.pl?mode=browse \& /cgi\-bin/baz.pl?mode=browse&debug=1 .Ve .PP Note that additional parameters are separated by '\f(CW\*(C`&\*(C'\fR' rather than simply '\f(CW\*(C`&\*(C'\fR'. This is the correct behaviour for \s-1HTML\s0 pages but is, unfortunately, incorrect when creating URLs that do not need to be encoded safely for \s-1HTML.\s0 This is likely to be corrected in a future version of the plugin (most probably with \s-1TT3\s0). In the mean time, you can set \f(CW$Template::Plugin::URL::JOINT\fR to \f(CW\*(C`&\*(C'\fR to get the correct behaviour. .PP Additional parameters may be also be specified to the \s-1URL:\s0 .PP .Vb 1 \& [% url(mode=\*(Aqsubmit\*(Aq, id=\*(Aqwiz\*(Aq) %] .Ve .PP Which, for the same three examples, produces: .PP .Vb 3 \& http://www.somewhere.com/cgi\-bin/foo.pl?mode=submit&id=wiz \& /cgi\-bin/bar.pl?mode=browse&id=wiz \& /cgi\-bin/baz.pl?mode=browse&debug=1&id=wiz .Ve .PP A new base \s-1URL\s0 may also be specified as the first option: .PP .Vb 1 \& [% url(\*(Aq/cgi\-bin/waz.pl\*(Aq, test=1) %] .Ve .PP producing .PP .Vb 3 \& /cgi\-bin/waz.pl?test=1 \& /cgi\-bin/waz.pl?mode=browse&test=1 \& /cgi\-bin/waz.pl?mode=browse&debug=1&test=1 .Ve .PP The ordering of the parameters is non-deterministic due to fact that Perl's hashes themselves are unordered. This isn't a problem as the ordering of \s-1CGI\s0 parameters is insignificant (to the best of my knowledge). All values will be properly escaped thanks to some code borrowed from Lincoln Stein's \f(CW\*(C`CGI\*(C'\fR module. e.g. .PP .Vb 2 \& [% USE url(\*(Aq/cgi\-bin/woz.pl\*(Aq) %] \& [% url(name="Elrich von Benjy d\*(AqWeiro") %] .Ve .PP Here the space and "\f(CW\*(C`\*(Aq\*(C'\fR" single quote characters are escaped in the output: .PP .Vb 1 \& /cgi\-bin/woz.pl?name=Elrich%20von%20Benjy%20d%27Weiro .Ve .PP An alternate name may be provided for the plugin at construction time as per regular Template Toolkit syntax. .PP .Vb 2 \& [% USE mycgi = url(\*(Aqcgi\-bin/min.pl\*(Aq) %] \& [% mycgi(debug=1) %] .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[�:'�-T -T $ man3/Template::Manual::Internals.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Internals 3" .TH Template::Manual::Internals 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Internals \- Template Toolkit internals .SH "Introduction" .IX Header "Introduction" This section of the documentation is aimed at developers wishing to know more about how the Template Toolkit works on the inside in order to extend or adapt it to their own needs. .PP If that doesn't sound like you then you probably don't need to read this. There is no test afterwards. .SH "Outside Looking In" .IX Header "Outside Looking In" The Template module is simply a front end module which creates and uses a Template::Service and pipes the output wherever you want it to go (\f(CW\*(C`STDOUT\*(C'\fR by default, or maybe a file, scalar, etc). The \&\f(CW\*(C`Apache::Template\*(C'\fR module (available separately from \s-1CPAN\s0) is another front end. That creates a \f(CW\*(C`Template::Service::Apache\*(C'\fR object, calls on it as required and sends the output back to the relevant \&\f(CW\*(C`Apache::Request\*(C'\fR object. .PP These front-end modules are really only there to handle any specifics of the environment in which they're being used. The \f(CW\*(C`Apache::Template\*(C'\fR front end, for example, handles \f(CW\*(C`Apache::Request\*(C'\fR specifics and configuration via the \fIhttpd.conf\fR. The regular Template front-end deals with \f(CW\*(C`STDOUT\*(C'\fR, variable refs, etc. Otherwise it is Template::Service (or subclass) which does all the work. .PP The Template::Service module provides a high-quality template delivery service, with bells, whistles, signed up service level agreement and a 30\-day no quibble money back guarantee. \*(L"Have a good time, all the time\*(R", that's our motto. .PP Within the lower levels of the Template Toolkit, there are lots of messy details that we generally don't want to have to worry about most of the time. Things like templates not being found, or failing to parse correctly, uncaught exceptions being thrown, missing plugin modules or dependencies, and so on. Template::Service hides that all away and makes everything look simple to the outsider. It provides extra features, like \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR and \&\f(CW\*(C`POST_PROCESS\*(C'\fR, and also provides the error recovery mechanism via \f(CW\*(C`ERROR\*(C'\fR. You ask it to process a template and it takes care of everything for you. The \&\f(CW\*(C`Template::Service::Apache\*(C'\fR module goes a little bit further, adding some extra headers to the Apache::Request, setting a few extra template variables, and so on. .PP For the most part, the job of a service is really just one of scheduling and dispatching. It receives a request in the form of a call to its \&\fBprocess()\fR method and schedules the named template specified as an argument, and possibly several other templates (\f(CW\*(C`PRE_PROCESS\*(C'\fR, etc) to be processed in order. It doesn't actually process the templates itself, but instead makes a \&\fBprocess()\fR call against a Template::Context object. .PP Template::Context is the runtime engine for the Template Toolkit \- the module that hangs everything together in the lower levels of the Template Toolkit and that one that does most of the real work, albeit by crafty delegation to various other friendly helper modules. .PP Given a template name (or perhaps a reference to a scalar or file handle) the context \fBprocess()\fR method must load and compile, or fetch a cached copy of a previously compiled template, corresponding to that name. It does this by calling on a list of one or more Template::Provider objects (the \f(CW\*(C`LOAD_TEMPLATES\*(C'\fR posse) who themselves might get involved with a Template::Parser to help turn source templates into executable Perl code (but more on that later). .PP Thankfully, all of this complexity is hidden away behind a simple \&\fBtemplate()\fR method. You call it passing a template name as an argument, and it returns a compiled template in the form of a Template::Document object, or otherwise raises an exception. .PP A Template::Document is a thin object wrapper around a compiled template subroutine. The object implements a \fBprocess()\fR method which performs a little bit of housekeeping and then calls the template subroutine. The object also defines template metadata (defined in \f(CW\*(C`[% META \&... %]\*(C'\fR directives) and has a \fBblock()\fR method which returns a hash of any additional \f(CW\*(C`[% BLOCK xxxx %]\*(C'\fR definitions found in the template source. .PP So the context fetches a compiled document via its own \&\fBtemplate()\fR method and then gets ready to process it. It first updates the stash (the place where template variables get defined \- more on that shortly) to set any template variable definitions specified as the second argument by reference to hash array. Then, it calls the document \fBprocess()\fR method, passing a reference to itself, the context object, as an argument. In doing this, it provides itself as an object against which template code can make callbacks to access runtime resources and Template Toolkit functionality. .PP What we're trying to say here is this: not only does the Template::Context object receive calls from the \fIoutside\fR, i.e. those originating in user code calling the \fBprocess()\fR method on a Template object, but it also receives calls from the \fIinside\fR, i.e. those originating in template directives of the form \f(CW\*(C`[% PROCESS template %]\*(C'\fR. .PP Before we move on to that, here's a simple structure diagram showing the outer layers of the Template Toolkit heading inwards, with pseudo code annotations showing a typical invocation sequence. .PP .Vb 10 \& ,\-\-\-\-\-\-\-\-. \& | Caller | use Template; \& \`\-\-\-\-\-\-\-\-\*(Aq my $tt = Template\->new( ... ); \& | $tt\->process($template, \e%vars); \& | Outside \& \- \- \- | \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- T T \& | package Template; Inside \& V \& +\-\-\-\-\-\-\-\-\-\-+ sub process($template, \e%vars) { \& | Template | $out = $self\->SERVICE\->process($template, $vars); \& +\-\-\-\-\-\-\-\-\-\-+ print $out or send it to $self\->OUTPUT; \& | } \& | \& | package Template::Service; \& | \& | sub process($template, \e%vars) { \& | try { \& +\-\-\-\-\-\-\-\-\-\-+ foreach $p in @self\->PRE_PROCESS \& | Service | $self\->CONTEXT\->process($p, $vars); \& +\-\-\-\-\-\-\-\-\-\-+ \& | $self\->CONTEXT\->process($template, $vars); \& | \& | foreach $p @self\->POST_PROCESS \& | $self\->CONTEXT\->process($p, $vars); \& | } \& | catch { \& | $self\->CONTEXT\->process($self\->ERROR); \& | } \& | } \& | \& V package Template::Context; \& +\-\-\-\-\-\-\-\-\-\-+ \& | Context | sub process($template, \e%vars) { \& +\-\-\-\-\-\-\-\-\-\-+ # fetch compiled template \& | $template = $self\->template($template) \& | # update stash \& | $self\->STASH\->update($vars); \& | # process template \& | $template\->process($self) \& | } \& V \& +\-\-\-\-\-\-\-\-\-\-+ package Template::Document; \& | Document | \& +\-\-\-\-\-\-\-\-\-\-+ sub process($context) { \& $output = &{ $self\->BLOCK }($context); \& } .Ve .SH "Inside Looking Out" .IX Header "Inside Looking Out" To understand more about what's going on in these lower levels, we need to look at what a compiled template looks like. In fact, a compiled template is just a regular Perl sub-routine. Here's a very simple one. .PP .Vb 3 \& sub my_compiled_template { \& return "This is a compiled template.\en"; \& } .Ve .PP You're unlikely to see a compiled template this simple unless you wrote it yourself but it is entirely valid. All a template subroutine is obliged to do is return some output (which may be an empty of course). If it can't for some reason, then it should raise an error via \f(CW\*(C`die()\*(C'\fR. .PP .Vb 3 \& sub my_todo_template { \& die "This template not yet implemented\en"; \& } .Ve .PP If it wants to get fancy, it can raise an error as a Template::Exception object. An exception object is really just a convenient wrapper for the '\f(CW\*(C`type\*(C'\fR' and '\f(CW\*(C`info\*(C'\fR' fields. .PP .Vb 3 \& sub my_solilique_template { \& die (Template::Exception\->new(\*(Aqyorrick\*(Aq, \*(AqFellow of infinite jest\*(Aq)); \& } .Ve .PP Templates generally need to do a lot more than just generate static output or raise errors. They may want to inspect variable values, process another template, load a plugin, run a filter, and so on. Whenever a template subroutine is called, it gets passed a reference to a Template::Context object. It is through this context object that template code can access the features of the Template Toolkit. .PP We described earlier how the Template::Service object calls on Template::Context to handle a \fBprocess()\fR request from the \fIoutside\fR. We can make a similar request on a context to process a template, but from within the code of another template. This is a call from the \fIinside\fR. .PP .Vb 6 \& sub my_process_template { \& my $context = shift; \& my $output = $context\->process(\*(Aqheader\*(Aq, { title => \*(AqHello World\*(Aq }) \& . "\ensome content\en" \& . $context\->process(\*(Aqfooter\*(Aq); \& } .Ve .PP This is then roughly equivalent to a source template something like this: .PP .Vb 5 \& [% PROCESS header \& title = \*(AqHello World\*(Aq \& %] \& some content \& [% PROCESS footer %] .Ve .PP Template variables are stored in, and managed by a Template::Stash object. This is a blessed hash array in which template variables are defined. The object wrapper provides \fBget()\fR and \&\fBset()\fR method which implement all the \&\fImagical.variable.features\fR of the Template Toolkit. .PP Each context object has its own stash, a reference to which can be returned by the appropriately named \fBstash()\fR method. So to print the value of some template variable, or for example, to represent the following source template: .PP .Vb 1 \& <title>[% title %]</title> .Ve .PP we might have a subroutine definition something like this: .PP .Vb 5 \& sub { \& my $context = shift; \& my $stash = $context\->stash(); \& return \*(Aq<title>\*(Aq . $stash\->get(\*(Aqtitle\*(Aq) . \*(Aq</title>\*(Aq; \& } .Ve .PP The stash \fBget()\fR method hides the details of the underlying variable types, automatically calling code references, checking return values, and performing other such tricks. If '\f(CW\*(C`title\*(C'\fR' happens to be bound to a subroutine then we can specify additional parameters as a list reference passed as the second argument to \fBget()\fR. .PP .Vb 1 \& [% title(\*(AqThe Cat Sat on the Mat\*(Aq) %] .Ve .PP This translates to the stash call: .PP .Vb 1 \& $stash\->get([ \*(Aqtitle\*(Aq, [\*(AqThe Cat Sat on the Mat\*(Aq] ]); .Ve .PP Dotted compound variables can be requested by passing a single list reference to the \f(CW\*(C`get()\*(C'\fR method in place of the variable name. Each pair of elements in the list should correspond to the variable name and reference to a list of arguments for each dot-delimited element of the variable. .PP .Vb 1 \& [% foo(1, 2).bar(3, 4).baz(5) %] .Ve .PP is thus equivalent to .PP .Vb 1 \& $stash\->get([ foo => [1,2], bar => [3,4], baz => [5] ]); .Ve .PP If there aren't any arguments for an element, you can specify an empty, zero or null argument list. .PP .Vb 2 \& [% foo.bar %] \& $stash\->get([ \*(Aqfoo\*(Aq, 0, \*(Aqbar\*(Aq, 0 ]); .Ve .PP The \fBset()\fR method works in a similar way. It takes a variable name and a variable value which should be assigned to it. .PP .Vb 2 \& [% x = 10 %] \& $stash\->set(\*(Aqx\*(Aq, 10); \& \& [% x.y = 10 %] \& $stash\->set([ \*(Aqx\*(Aq, 0, \*(Aqy\*(Aq, 0 ], 10); .Ve .PP So the stash gives us access to template variables and the context provides the higher level functionality. .PP Alongside the \fBprocess()\fR method lies the \&\fBinclude()\fR method. Just as with the \f(CW\*(C`PROCESS\*(C'\fR / \&\f(CW\*(C`INCLUDE\*(C'\fR directives, the key difference is in variable localisation. Before processing a template, the \f(CW\*(C`process()\*(C'\fR method simply updates the stash to set any new variable definitions, overwriting any existing values. In contrast, the \f(CW\*(C`include()\*(C'\fR method creates a copy of the existing stash, in a process known as \fIcloning\fR the stash, and then uses that as a temporary variable store. Any previously existing variables are still defined, but any changes made to variables, including setting the new variable values passed aas arguments will affect only the local copy of the stash (although note that it's only a shallow copy, so it's not foolproof). When the template has been processed, the \f(CW\*(C`include()\*(C'\fR method restores the previous variable state by \fIdecloning\fR the stash. .PP The context also provides an \fBinsert()\fR method to implement the \f(CW\*(C`INSERT\*(C'\fR directive, but no \f(CW\*(C`wrapper()\*(C'\fR method. This functionality can be implemented by rewriting the Perl code and calling \f(CW\*(C`include()\*(C'\fR. .PP .Vb 3 \& [% WRAPPER foo \-%] \& blah blah [% x %] \& [%\- END %] \& \& $context\->include(\*(Aqfoo\*(Aq, { \& content => \*(Aqblah blah \*(Aq . $stash\->get(\*(Aqx\*(Aq), \& }); .Ve .PP Other than the template processing methods \f(CW\*(C`process()\*(C'\fR, \f(CW\*(C`include()\*(C'\fR and \&\f(CW\*(C`insert()\*(C'\fR, the context defines methods for fetching plugin objects, \&\fBplugin()\fR, and filters, \&\fBfilter()\fR. .PP .Vb 2 \& # TT USE directive \& [% USE foo = Bar(10) %] \& \& # equivalent Perl \& $stash\->set(\*(Aqfoo\*(Aq, $context\->plugin(\*(AqBar\*(Aq, [10])); \& \& # TT FILTER block \& [% FILTER bar(20) %] \& blah blah blah \& [% END %] \& \& # equivalent Perl \& my $filter = $context\->filter(\*(Aqbar\*(Aq, [20]); \& &$filter(\*(Aqblah blah blah\*(Aq); .Ve .PP Pretty much everything else you might want to do in a template can be done in Perl code. Things like \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR, \f(CW\*(C`FOREACH\*(C'\fR and so on all have direct counterparts in Perl. .PP .Vb 4 \& # TT IF directive \& [% IF msg %] \& Message: [% msg %] \& [% END %]; \& \& # equivalent Perl \& if ($stash\->get(\*(Aqmsg\*(Aq)) { \& $output .= \*(AqMessage: \*(Aq; \& $output .= $stash\->get(\*(Aqmsg\*(Aq); \& } .Ve .PP The best way to get a better understanding of what's going on underneath the hood is to set the \f(CW$Template::Parser::DEBUG\fR flag to a true value and start processing templates. This will cause the parser to print the generated Perl code for each template it compiles to \f(CW\*(C`STDERR\*(C'\fR. You'll probably also want to set the \f(CW$Template::Directive::PRETTY\fR option to have the Perl pretty-printed for human consumption. .PP .Vb 3 \& use Template; \& use Template::Parser; \& use Template::Directive; \& \& $Template::Parser::DEBUG = 1; \& $Template::Directive::PRETTY = 1; \& \& my $template = Template\->new(); \& $template\->process(\e*DATA, { cat => \*(Aqdog\*(Aq, mat => \*(Aqlog\*(Aq }); \& \& _\|_DATA_\|_ \& The [% cat %] sat on the [% mat %] .Ve .PP The output sent to \f(CW\*(C`STDOUT\*(C'\fR remains as you would expect: .PP .Vb 1 \& The dog sat on the log .Ve .PP The output sent to \f(CW\*(C`STDERR\*(C'\fR would look something like this: .PP .Vb 6 \& compiled main template document block: \& sub { \& my $context = shift || die "template sub called without context\en"; \& my $stash = $context\->stash; \& my $output = \*(Aq\*(Aq; \& my $error; \& \& eval { BLOCK: { \& $output .= "The "; \& $output .= $stash\->get(\*(Aqcat\*(Aq); \& $output .= " sat on the "; \& $output .= $stash\->get(\*(Aqmat\*(Aq); \& $output .= "\en"; \& } }; \& if ($@) { \& $error = $context\->catch($@, \e$output); \& die $error unless $error\->type eq \*(Aqreturn\*(Aq; \& } \& \& return $output; \& } .Ve .SH "Hacking on the Template Toolkit" .IX Header "Hacking on the Template Toolkit" Please feel free to hack on the Template Toolkit. If you find a bug that needs fixing, if you have an idea for something that's missing, or you feel inclined to tackle something on the \s-1TODO\s0 list, then by all means go ahead and do it! .PP If you're contemplating something non-trivial then you'll probably want to bring it up on the mailing list first to get an idea about the current state of play, find out if anyone's already working on it, and so on. .PP The source code repository for the Template Toolkit is hosted at Github. .PP .Vb 1 \& https://github.com/abw/Template2 .Ve .PP Clone the repository, make your changes, commit them, then send a pull request. .PP Once you've made your changes, please remember to update the test suite by adding extra tests to one of the existing test scripts in the \f(CW\*(C`t\*(C'\fR sub-directory, or by adding a new test script of your own. And of course, run \f(CW\*(C`make test\*(C'\fR to ensure that all the tests pass with your new code. .PP Don't forget that any files you do add will need to be added to the \&\s-1MANIFEST.\s0 Running \f(CW\*(C`make manifest\*(C'\fR will do this for you, but you need to make sure you haven't got any other temporary files lying around that might also get added to it. .PP Documentation is often something that gets overlooked but it's just as important as the code. If you're adding a new module, a plugin module, for example, then it's \s-1OK\s0 to include the \s-1POD\s0 documentation in with the module, but \&\fIplease\fR write it all in one piece at the end of the file, \fIafter\fR the code (just look at any other \f(CW\*(C`Template::*\*(C'\fR module for an example). It's a religious issue, I know, but I have a strong distaste for \s-1POD\s0 documentation interspersed throughout the code. In my not-so-humble opinion, it makes both the code and the documentation harder to read (same kinda problem as embedding Perl in \s-1HTML\s0). .PP Then add a line to the Changes file giving a very brief description of what you've done. There's no need to go into detail here (save that for the commit message, comments in code or docuemtation where appropriate). .PP Please also make sure you add your name to the lib/Template/Manual/Credits.pod file (if it isn't already there). .PP Then commit your changes and send a pull request. PK � �[��cUp p man3/Template::Plugin::HTML.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::HTML 3" .TH Template::Plugin::HTML 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::HTML \- Plugin to create HTML elements .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE HTML %] \& \& [% HTML.escape("if (a < b && c > d) ..." %] \& \& [% HTML.element(table => { border => 1, cellpadding => 2 }) %] \& \& [% HTML.attributes(border => 1, cellpadding => 2) %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`HTML\*(C'\fR plugin is a very basic plugin, implementing a few useful methods for generating \s-1HTML.\s0 .SH "METHODS" .IX Header "METHODS" .SS "escape(text)" .IX Subsection "escape(text)" Returns the source text with any \s-1HTML\s0 reserved characters such as \&\f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, etc., correctly escaped to their entity equivalents. .SS "attributes(hash)" .IX Subsection "attributes(hash)" Returns the elements of the hash array passed by reference correctly formatted (e.g. values quoted and correctly escaped) as attributes for an \s-1HTML\s0 element. .SS "add_attribute(attributes)" .IX Subsection "add_attribute(attributes)" This provides a way to incrementally add attributes to the object. The values passed in are stored in the object. Calling element with just a tag or attributes without an parameters will used the saved attributes. .PP .Vb 4 \& USE tag = HTML; \& tag.add_attributes( { class => \*(Aqnavbar\*(Aq } ); \& tag.add_attributes( { id => \*(Aqfoo\*(Aq } ); \& tag.add_attributes( { class => \*(Aqactive\*(Aq } ); \& \& tag.element( \*(Aqli\*(Aq ); # <li class="navbar active" id="foo"> .Ve .PP This method has two aliases: \fBadd_attribute()\fR and \fBadd()\fR. .SS "replace_attribute(attributes)" .IX Subsection "replace_attribute(attributes)" This will replace an attribute value instead of add to existing. .PP .Vb 4 \& USE tag = HTML; \& tag.add_attributes( { class => \*(Aqnavbar\*(Aq } ); \& tag.add_attributes( { id => \*(Aqfoo\*(Aq } ); \& tag.replace_attributes( { class => \*(Aqactive\*(Aq } ); \& \& tag.element( \*(Aqli\*(Aq ); # <li class="active" id="foo"> .Ve .PP This method has two aliases: \fBreplace_attribute()\fR and \fBreplace()\fR. .SS "clear_attributes" .IX Subsection "clear_attributes" Clears any saved attributes .SS "element(type, attributes)" .IX Subsection "element(type, attributes)" Generates an \s-1HTML\s0 element of the specified type and with the attributes provided as an optional hash array reference as the second argument or as named arguments. .PP .Vb 3 \& [% HTML.element(table => { border => 1, cellpadding => 2 }) %] \& [% HTML.element(\*(Aqtable\*(Aq, border=1, cellpadding=2) %] \& [% HTML.element(table => attribs) %] .Ve .SH "DEBUGGING" .IX Header "DEBUGGING" The \s-1HTML\s0 plugin accepts a \f(CW\*(C`sorted\*(C'\fR option as a constructor argument which, when set to any true value, causes the attributes generated by the \f(CW\*(C`attributes()\*(C'\fR method (either directly or via \f(CW\*(C`element()\*(C'\fR) to be returned in sorted order. Order of attributes isn't important in \&\s-1HTML,\s0 but this is provided mainly for the purposes of debugging where it is useful to have attributes generated in a deterministic order rather than whatever order the hash happened to feel like returning the keys in. .PP .Vb 2 \& [% USE HTML(sorted=1) %] \& [% HTML.element( foo => { charlie => 1, bravo => 2, alpha => 3 } ) %] .Ve .PP generates: .PP .Vb 1 \& <foo alpha="3" bravo="2" charlie="1"> .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[E���j �j # man3/Template::Manual::VMethods.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::VMethods 3" .TH Template::Manual::VMethods 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::VMethods \- Virtual Methods .SH "Scalar Virtual Methods" .IX Header "Scalar Virtual Methods" .SS "chunk(size)" .IX Subsection "chunk(size)" Splits the value into a list of chunks of a certain size. .PP .Vb 3 \& [% ccard_no = "1234567824683579"; \& ccard_no.chunk(4).join \& %] .Ve .PP Output: .PP .Vb 1 \& 1234 5678 2468 3579 .Ve .PP If the size is specified as a negative number then the text will be chunked from right-to-left. This gives the correct grouping for numbers, for example. .PP .Vb 3 \& [% number = 1234567; \& number.chunk(\-3).join(\*(Aq,\*(Aq) \& %] .Ve .PP Output: .PP .Vb 1 \& 1,234,567 .Ve .SS "collapse" .IX Subsection "collapse" Returns the text with any leading and trailing whitespace removed and any internal sequences of whitespace converted to a single space .PP .Vb 2 \& [% text = " The bird\en is the word" %] \& [% text.collapse %] # The bird is the word .Ve .SS "defined" .IX Subsection "defined" Returns true if the value is defined. .PP .Vb 1 \& [% user = get_user(uid) IF uid.defined %] .Ve .SS "dquote" .IX Subsection "dquote" Returns the text with any double quote characters escaped with a backslash prefix. Any newline characters in the text will be replaced with \*(L"\en\*(R". .PP .Vb 2 \& [% quote = \*(AqHe said "Oh really?"\*(Aq %] \& [% quote.dquote %] # He said \e"Oh really?\e" .Ve .SS "hash" .IX Subsection "hash" Return the value as a hash reference containing a single entry with the key \f(CW\*(C`value\*(C'\fR indicating the original scalar value. As with the \&\f(CW\*(C`list\*(C'\fR virtual method, this is generally used to help massage data into different formats. .SS "lcfirst" .IX Subsection "lcfirst" Returns the text with the first letter converted to lower case. .PP .Vb 2 \& [% word = \*(AqBIRD\*(Aq %] \& [% word.lcfirst %] # bIRD .Ve .SS "length" .IX Subsection "length" Returns the length of the string representation of the item: .PP .Vb 3 \& [% IF password.length < 8 %] \& Password too short, dumbass! \& [% END %] .Ve .SS "empty" .IX Subsection "empty" Returns true if the string is empty: .PP .Vb 3 \& [% IF details.empty %] \& No details specified \& [% END %] .Ve .SS "list" .IX Subsection "list" Return the value as a single element list. This can be useful if you have a variable which may contain a single item or a list and you want to treat them equally. The \f(CW\*(C`list\*(C'\fR method can be called against a list reference and will simply return the original reference, effectively a no-op. .PP .Vb 1 \& [% thing.list.size %] # thing can be a scalar or a list .Ve .SS "lower" .IX Subsection "lower" Returns the text in lower case. .PP .Vb 2 \& [% word = \*(AqBIRD\*(Aq %] \& [% word.lower %] # bird .Ve .SS "match(pattern, global)" .IX Subsection "match(pattern, global)" Performs a regular expression match on the string using the pattern passed as an argument. If the pattern matches the string then the method returns a reference to a list of any strings captured within parenthesis in the pattern. .PP .Vb 3 \& [% name = \*(AqLarry Wall\*(Aq %] \& [% matches = name.match(\*(Aq(\ew+) (\ew+)\*(Aq) %] \& [% matches.1 %], [% matches.0 %] # Wall, Larry .Ve .PP If the pattern does not match then the method returns false, rather than returning an empty list which Perl and the Template Toolkit both consider to be a true value. This allows you to write expression like this. .PP .Vb 1 \& [% "We\*(Aqre not worthy!" IF name.match(\*(AqLarry Wall\*(Aq) %] \& \& [% IF (matches = name.match(\*(Aq(\ew+) (\ew+)\*(Aq)) %] \& pattern matches: [% matches.join(\*(Aq, \*(Aq) %] \& [% ELSE %] \& pattern does not match \& [% END %] .Ve .PP Any regex modifiers, like \f(CW\*(C`/s\*(C'\fR, should be added in the regex using the \f(CW\*(C`(?s)\*(C'\fR syntax. For example, to modify the regex to disregard whitespace (the \f(CW\*(C`/x\*(C'\fR switch), use: .PP .Vb 7 \& [% re = \*(Aq(?x) \& (\ew+) \& [ ] \& (\ew+) \& \*(Aq; \& matches = name.match(re); \& %] .Ve .PP To perform a global search to match the pattern as many times as it appears in the source string, provide a true value for the \f(CW\*(C`global\*(C'\fR argument following the pattern. .PP .Vb 3 \& [% text = \*(Aqbandanna\*(Aq; \& text.match(\*(Aqan+\*(Aq, 1).join(\*(Aq, \*(Aq) # an, ann \& %] .Ve .SS "repeat(n)" .IX Subsection "repeat(n)" Repeat the string a specified number of times. .PP .Vb 2 \& [% name = \*(Aqfoo\*(Aq %] \& [% name.repeat(3) %] # foofoofoo .Ve .SS "replace(search, replace)" .IX Subsection "replace(search, replace)" Outputs the string with all instances of the first argument (specified as a Perl regular expression) with the second. .PP .Vb 2 \& [% name = \*(Aqfoo, bar & baz\*(Aq %] \& [% name.replace(\*(Aq\eW+\*(Aq, \*(Aq_\*(Aq) %] # foo_bar_baz .Ve .PP You can use \f(CW$1\fR, \f(CW$2\fR, etc., to reference captured parts (in parentheses) in the regular expression. Just be careful to \fIsingle\fR quote the replacement string. If you use \fIdouble\fR quotes then \s-1TT\s0 will try and interpolate the variables before passing the string to the \f(CW\*(C`replace\*(C'\fR vmethod. .PP .Vb 2 \& [% name = \*(AqFooBarBaz\*(Aq %] \& [% name.replace(\*(Aq([A\-Z])\*(Aq, \*(Aq $1\*(Aq) %] # Foo Bar Baz .Ve .SS "remove(pattern)" .IX Subsection "remove(pattern)" Outputs the string with all instances of the pattern (specified as a Perl regular expression) removed. .PP .Vb 2 \& [% name = \*(Aqfoo, bar & baz\*(Aq %] \& [% name.remove(\*(Aq\eW+\*(Aq) %] # foobarbaz .Ve .SS "search(pattern)" .IX Subsection "search(pattern)" Performs a similar function to match but simply returns true if the string matches the regular expression pattern passed as an argument. .PP .Vb 2 \& [% name = \*(Aqfoo bar baz\*(Aq %] \& [% name.search(\*(Aqbar\*(Aq) ? \*(Aqbar\*(Aq : \*(Aqno bar\*(Aq %] # bar .Ve .PP This virtual method is now deprecated in favour of match. Move along now, there's nothing more to see here. .SS "size" .IX Subsection "size" Always returns 1 for scalar values. This method is provided for consistency with the hash and list size methods. .SS "split(pattern)" .IX Subsection "split(pattern)" Calls Perl's \f(CW\*(C`split()\*(C'\fR function to split a string into a list of strings. .PP .Vb 3 \& [% FOREACH dir IN mypath.split(\*(Aq:\*(Aq) %] \& [% dir %] \& [% END %] .Ve .SS "substr(offset, length, replacement)" .IX Subsection "substr(offset, length, replacement)" Returns a substring starting at \f(CW\*(C`offset\*(C'\fR, for \f(CW\*(C`length\*(C'\fR characters. .PP .Vb 2 \& [% str \*(Aqfoo bar baz wiz waz woz\*(Aq) %] \& [% str.substr(4, 3) %] # bar .Ve .PP If \f(CW\*(C`length\*(C'\fR is not specified then it returns everything from the \&\f(CW\*(C`offset\*(C'\fR to the end of the string. .PP .Vb 1 \& [% str.substr(12) %] # wiz waz woz .Ve .PP If both \f(CW\*(C`length\*(C'\fR and \f(CW\*(C`replacement\*(C'\fR are specified, then the method replaces everything from \f(CW\*(C`offset\*(C'\fR for \f(CW\*(C`length\*(C'\fR characters with \&\f(CW$replacement\fR. The substring removed from the string is then returned. .PP .Vb 2 \& [% str.substr(0, 11, \*(AqFOO\*(Aq) %] # foo bar baz \& [% str %] # FOO wiz waz woz .Ve .SS "squote" .IX Subsection "squote" Returns the text with any single quote characters escaped with a backslash prefix. .PP .Vb 2 \& [% tim = "Tim O\*(AqReilly" %] \& [% tim.squote %] # Tim O\e\*(AqReilly .Ve .SS "trim" .IX Subsection "trim" Returns the text with any leading and trailing whitespace removed. .PP .Vb 2 \& [% text = \*(Aq hello world \*(Aq %] \& [% text.trim %] # hello world .Ve .SS "ucfirst" .IX Subsection "ucfirst" Returns the text with the first letter converted to upper case. .PP .Vb 2 \& [% word = \*(Aqbird\*(Aq %] \& [% word.ucfirst %] # Bird .Ve .SS "upper" .IX Subsection "upper" Returns the text in upper case. .PP .Vb 2 \& [% word = \*(Aqbird\*(Aq %] \& [% word.upper %] # BIRD .Ve .SH "Hash Virtual Methods" .IX Header "Hash Virtual Methods" .SS "keys" .IX Subsection "keys" Returns a list of keys in the hash. They are not returned in any particular order, but the order is the same as for the corresponding values method. .PP .Vb 3 \& [% FOREACH key IN hash.keys %] \& * [% key %] \& [% END %] .Ve .PP If you want the keys in sorted order, use the list \f(CW\*(C`sort\*(C'\fR method. .PP .Vb 3 \& [% FOREACH key IN hash.keys.sort %] \& * [% key %] \& [% END %] .Ve .PP Having got the keys in sorted order, you can then use variable interpolation to fetch the value. This is shown in the following example by the use of \f(CW$key\fR to fetch the item from \f(CW\*(C`hash\*(C'\fR whose key is stored in the \f(CW\*(C`key\*(C'\fR variable. .PP .Vb 3 \& [% FOREACH key IN hash.keys.sort %] \& * [% key %] = [% hash.$key %] \& [% END %] .Ve .PP Alternately, you can use the \f(CW\*(C`pairs\*(C'\fR method to get a list of key/value pairs in sorted order. .SS "values" .IX Subsection "values" Returns a list of the values in the hash. As with the \f(CW\*(C`keys\*(C'\fR method, they are not returned in any particular order, although it is the same order that the keys are returned in. .PP .Vb 1 \& [% hash.values.join(\*(Aq, \*(Aq) %] .Ve .SS "items" .IX Subsection "items" Returns a list of both the keys and the values expanded into a single list. .PP .Vb 4 \& [% hash = { \& a = 10 \& b = 20 \& }; \& \& hash.items.join(\*(Aq, \*(Aq) # a, 10, b, 20 \& %] .Ve .SS "each" .IX Subsection "each" This method currently returns the same thing as the \f(CW\*(C`items\*(C'\fR method. .PP However, please note that this method will change in the next major version of the Template Toolkit (v3) to return the same thing as the \&\f(CW\*(C`pairs\*(C'\fR method. This will be done in an effort to make these virtual method more consistent with each other and how Perl works. .PP In anticipation of this, we recommend that you stop using \f(CW\*(C`hash.each\*(C'\fR and instead use \f(CW\*(C`hash.items\*(C'\fR. .SS "pairs" .IX Subsection "pairs" This method returns a list of key/value pairs. They are returned in sorted order according to the keys. .PP .Vb 3 \& [% FOREACH pair IN product.pairs %] \& * [% pair.key %] is [% pair.value %] \& [% END %] .Ve .SS "list" .IX Subsection "list" Returns the contents of the hash in list form. An argument can be passed to indicate the desired items required in the list: \f(CW\*(C`keys\*(C'\fR to return a list of the keys (same as \f(CW\*(C`hash.keys\*(C'\fR), \f(CW\*(C`values\*(C'\fR to return a list of the values (same as \f(CW\*(C`hash.values\*(C'\fR), \f(CW\*(C`each\*(C'\fR to return as list of key and values (same as \f(CW\*(C`hash.each\*(C'\fR), or \f(CW\*(C`pairs\*(C'\fR to return a list of key/value pairs (same as \f(CW\*(C`hash.pairs\*(C'\fR). .PP .Vb 4 \& [% keys = hash.list(\*(Aqkeys\*(Aq) %] \& [% values = hash.list(\*(Aqvalues\*(Aq) %] \& [% items = hash.list(\*(Aqeach\*(Aq) %] \& [% pairs = hash.list(\*(Aqpairs\*(Aq) %] .Ve .PP When called without an argument it currently returns the same thing as the \f(CW\*(C`pairs\*(C'\fR method. However, please note that this method will change in the next major version of the Template Toolkit (v3) to return a reference to a list containing the single hash reference (as per the scalar list method). .PP In anticipation of this, we recommend that you stop using \f(CW\*(C`hash.list\*(C'\fR and instead use \f(CW\*(C`hash.pairs\*(C'\fR. .SS "sort, nsort" .IX Subsection "sort, nsort" Return a list of the keys, sorted alphabetically (\f(CW\*(C`sort\*(C'\fR) or numerically (\f(CW\*(C`nsort\*(C'\fR) according to the corresponding values in the hash. .PP .Vb 3 \& [% FOREACH n IN phones.sort %] \& [% phones.$n %] is [% n %], \& [% END %] .Ve .SS "import" .IX Subsection "import" The \f(CW\*(C`import\*(C'\fR method can be called on a hash array to import the contents of another hash array. .PP .Vb 9 \& [% hash1 = { \& foo = \*(AqFoo\*(Aq \& bar = \*(AqBar\*(Aq \& } \& hash2 = { \& wiz = \*(AqWiz\*(Aq \& woz = \*(AqWoz\*(Aq \& } \& %] \& \& [% hash1.import(hash2) %] \& [% hash1.wiz %] # Wiz .Ve .PP You can also call the \f(CW\*(C`import()\*(C'\fR method by itself to import a hash array into the current namespace hash. .PP .Vb 3 \& [% user = { id => \*(Aqlwall\*(Aq, name => \*(AqLarry Wall\*(Aq } %] \& [% import(user) %] \& [% id %]: [% name %] # lwall: Larry Wall .Ve .SS "defined, exists" .IX Subsection "defined, exists" Returns a true or false value if an item in the hash denoted by the key passed as an argument is defined or exists, respectively. .PP .Vb 2 \& [% hash.defined(\*(Aqsomekey\*(Aq) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq %] \& [% hash.exists(\*(Aqsomekey\*(Aq) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq %] .Ve .PP When called without any argument, \f(CW\*(C`hash.defined\*(C'\fR returns true if the hash itself is defined (e.g. the same effect as \f(CW\*(C`scalar.defined\*(C'\fR). .SS "delete" .IX Subsection "delete" Delete one or more items from the hash. .PP .Vb 1 \& [% hash.delete(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq) %] .Ve .SS "size" .IX Subsection "size" Returns the number of key/value pairs in the hash. .SS "empty" .IX Subsection "empty" Returns true if the hash is empty: .PP .Vb 3 \& [% IF config.empty %] \& No configuration available \& [% END %] .Ve .SS "item" .IX Subsection "item" Returns an item from the hash using a key passed as an argument. .PP .Vb 1 \& [% hash.item(\*(Aqfoo\*(Aq) %] # same as hash.foo .Ve .SH "List Virtual Methods" .IX Header "List Virtual Methods" .SS "first, last" .IX Subsection "first, last" Returns the first/last item in the list. The item is not removed from the list. .PP .Vb 1 \& [% results.first %] to [% results.last %] .Ve .PP If either is given a numeric argument \f(CW\*(C`n\*(C'\fR, they return the first or last \f(CW\*(C`n\*(C'\fR elements: .PP .Vb 1 \& The first 5 results are [% results.first(5).join(", ") %]. .Ve .SS "size, max" .IX Subsection "size, max" Returns the size of a list (number of elements) and the maximum index number (size \- 1), respectively. .PP .Vb 1 \& [% results.size %] search results matched your query .Ve .SS "empty" .IX Subsection "empty" Returns true if the list is empty: .PP .Vb 3 \& [% IF results.empty %] \& No results found \& [% END %] .Ve .SS "defined" .IX Subsection "defined" Returns a true or false value if the item in the list denoted by the argument is defined. .PP .Vb 1 \& [% list.defined(3) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq %] .Ve .PP When called without any argument, \f(CW\*(C`list.defined\*(C'\fR returns true if the list itself is defined (e.g. the same effect as \f(CW\*(C`scalar.defined\*(C'\fR). .SS "reverse" .IX Subsection "reverse" Returns the items of the list in reverse order. .PP .Vb 3 \& [% FOREACH s IN scores.reverse %] \& ... \& [% END %] .Ve .SS "join" .IX Subsection "join" Joins the items in the list into a single string, using Perl's \f(CW\*(C`join()\*(C'\fR function. .PP .Vb 1 \& [% items.join(\*(Aq, \*(Aq) %] .Ve .SS "grep" .IX Subsection "grep" Returns a list of the items in the list that match a regular expression pattern. .PP .Vb 3 \& [% FOREACH directory.files.grep(\*(Aq\e.txt$\*(Aq) %] \& ... \& [% END %] .Ve .SS "sort, nsort" .IX Subsection "sort, nsort" Returns the items in alpha (\f(CW\*(C`sort\*(C'\fR) or numerical (\f(CW\*(C`nsort\*(C'\fR) order. .PP .Vb 1 \& [% library = books.sort %] .Ve .PP An argument can be provided to specify a search key. Where an item in the list is a hash reference, the search key will be used to retrieve a value from the hash which will then be used as the comparison value. Where an item is an object which implements a method of that name, the method will be called to return a comparison value. .PP .Vb 1 \& [% library = books.sort(\*(Aqauthor\*(Aq) %] .Ve .PP In the example, the \f(CW\*(C`books\*(C'\fR list can contains hash references with an \f(CW\*(C`author\*(C'\fR key or objects with an \f(CW\*(C`author\*(C'\fR method. .PP You can also specify multiple sort keys. .PP .Vb 1 \& [% library = books.sort(\*(Aqauthor\*(Aq, \*(Aqtitle\*(Aq) %] .Ve .PP In this case the books will be sorted primarily by author. If two or more books have authors with the same name then they will be sorted by title. .SS "unshift(item), push(item)" .IX Subsection "unshift(item), push(item)" The \f(CW\*(C`push()\*(C'\fR method adds an item or items to the end of list. .PP .Vb 2 \& [% mylist.push(foo) %] \& [% mylist.push(foo, bar) %] .Ve .PP The \f(CW\*(C`unshift()\*(C'\fR method adds an item or items to the start of a list. .PP .Vb 2 \& [% mylist.unshift(foo) %] \& [% mylist.push(foo, bar) %] .Ve .SS "shift, pop" .IX Subsection "shift, pop" Removes the first/last item from the list and returns it. .PP .Vb 2 \& [% first = mylist.shift %] \& [% last = mylist.pop %] .Ve .SS "unique" .IX Subsection "unique" Returns a list of the unique elements in a list, in the same order as in the list itself. .PP .Vb 2 \& [% mylist = [ 1, 2, 3, 2, 3, 4, 1, 4, 3, 4, 5 ] %] \& [% numbers = mylist.unique %] .Ve .PP While this can be explicitly sorted, it is not required that the list be sorted before the unique elements are pulled out (unlike the Unix command line utility). .PP .Vb 1 \& [% numbers = mylist.unique.sort %] .Ve .SS "import" .IX Subsection "import" Appends the contents of one or more other lists to the end of the current list. .PP .Vb 6 \& [% one = [ 1 2 3 ]; \& two = [ 4 5 6 ]; \& three = [ 7 8 9 ]; \& one.import(two, three); \& one.join(\*(Aq, \*(Aq); # 1, 2, 3, 4, 5, 6, 7, 8, 9 \& %] .Ve .PP Import also allows chaining. The below syntax is equivalent. .PP .Vb 6 \& [% one = [ 1 2 3 ]; \& two = [ 4 5 6 ]; \& three = [ 7 8 9 ]; \& one.import(two, three).join(\*(Aq, \*(Aq); # 1, 2, 3, 4, 5, 6, 7, 8, 9 \&# or: one.import(two).import(three).join(\*(Aq, \*(Aq); # 1, 2, 3, 4, 5, 6, 7, 8, 9 \& %] .Ve .SS "merge" .IX Subsection "merge" Returns a list composed of zero or more other lists: .PP .Vb 5 \& [% list_one = [ 1 2 3 ]; \& list_two = [ 4 5 6 ]; \& list_three = [ 7 8 9 ]; \& list_four = list_one.merge(list_two, list_three); \& %] .Ve .PP The original lists are not modified. .SS "slice(from, to)" .IX Subsection "slice(from, to)" Returns a slice of items in the list between the bounds passed as arguments. If the second argument, \f(CW\*(C`to\*(C'\fR, isn't specified, then it defaults to the last item in the list. The original list is not modified. .PP .Vb 2 \& [% first_three = list.slice(0,2) %] \& [% last_three = list.slice(\-3, \-1) %] .Ve .SS "splice(offset, length, list)" .IX Subsection "splice(offset, length, list)" Behaves just like Perl's \f(CW\*(C`splice()\*(C'\fR function allowing you to selectively remove and/or replace elements in a list. It removes \f(CW\*(C`length\*(C'\fR items from the list, starting at \f(CW\*(C`offset\*(C'\fR and replaces them with the items in \f(CW\*(C`list\*(C'\fR. .PP .Vb 6 \& [% play_game = [ \*(Aqplay\*(Aq, \*(Aqscrabble\*(Aq ]; \& ping_pong = [ \*(Aqping\*(Aq, \*(Aqpong\*(Aq ]; \& redundant = play_game.splice(1, 1, ping_pong); \& redundant.join; # scrabble \& play_game.join; # play ping pong \& %] .Ve .PP The method returns a list of the items removed by the splice. You can use the \f(CW\*(C`CALL\*(C'\fR directive to ignore the output if you're not planning to do anything with it. .PP .Vb 1 \& [% CALL play_game.splice(1, 1, ping_pong) %] .Ve .PP As well as providing a reference to a list of replacement values, you can pass in a list of items. .PP .Vb 1 \& [% CALL list.splice(\-1, 0, \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq) %] .Ve .PP Be careful about passing just one item in as a replacement value. If it is a reference to a list then the contents of the list will be used. If it's not a list, then it will be treated as a single value. You can use square brackets around a single item if you need to be explicit: .PP .Vb 2 \& [% # push a single item, an_item \& CALL list.splice(\-1, 0, an_item); \& \& # push the items from another_list \& CALL list.splice(\-1, 0, another_list); \& \& # push a reference to another_list \& CALL list.splice(\-1, 0, [ another_list ]); \& %] .Ve .SS "hash" .IX Subsection "hash" Returns a reference to a hash array comprised of the elements in the list. The even-numbered elements (0, 2, 4, etc) become the keys and the odd-numbered elements (1, 3, 5, etc) the values. .PP .Vb 4 \& [% list = [\*(Aqpi\*(Aq, 3.14, \*(Aqe\*(Aq, 2.718] %] \& [% hash = list.hash %] \& [% hash.pi %] # 3.14 \& [% hash.e %] # 2.718 .Ve .PP If a numerical argument is provided then the hash returned will have keys generated for each item starting at the number specified. .PP .Vb 4 \& [% list = [\*(Aqbeer\*(Aq, \*(Aqpeanuts\*(Aq] %] \& [% hash = list.hash(1) %] \& [% hash.1 %] # beer \& [% hash.2 %] # peanuts .Ve .SS "item" .IX Subsection "item" Returns an item from the list using an index passed as an argument. .PP .Vb 1 \& [% list.item(0) %] # same as list.0 .Ve .SH "Automagic Promotion of Scalar to List for Virtual Methods" .IX Header "Automagic Promotion of Scalar to List for Virtual Methods" In addition to the scalar virtual methods listed in the previous section, you can also call any list virtual method against a scalar. The item will be automagically promoted to a single element list and the appropriate list virtual method will be called. .PP One particular benefit of this comes when calling subroutines or object methods that return a list of items, rather than the preferred reference to a list of items. In this case, the Template Toolkit automatically folds the items returned into a list. .PP The upshot is that you can continue to use existing Perl modules or code that returns lists of items, without having to refactor it just to keep the Template Toolkit happy (by returning references to list). \f(CW\*(C`Class::DBI\*(C'\fR module is just one example of a particularly useful module which returns values this way. .PP If only a single item is returned from a subroutine then the Template Toolkit assumes it meant to return a single item (rather than a list of 1 item) and leaves it well alone, returning the single value as it is. If you're executing a database query, for example, you might get 1 item returned, or perhaps many items which are then folded into a list. .PP The \f(CW\*(C`FOREACH\*(C'\fR directive will happily accept either a list or a single item which it will treat as a list. So it's safe to write directives like this, where we assume that the \f(CW\*(C`something\*(C'\fR variable is bound to a subroutine which may return one or more items: .PP .Vb 3 \& [% FOREACH item IN something %] \& ... \& [% END %] .Ve .PP The automagic promotion of scalars to single item lists means that you can also use list virtual methods safely, even if you only get one item returned. For example: .PP .Vb 3 \& [% something.first %] \& [% something.join %] \& [% something.reverse.join(\*(Aq, \*(Aq) %] .Ve .PP Note that this is very much a last-ditch behaviour. If the single item return is an object with a \f(CW\*(C`first\*(C'\fR method, for example, then that will be called, as expected, in preference to the list virtual method. .SH "Defining Custom Virtual Methods" .IX Header "Defining Custom Virtual Methods" You can define your own virtual methods for scalars, lists and hash arrays. The Template::Stash package variables \f(CW$SCALAR_OPS\fR, \f(CW$LIST_OPS\fR and \&\f(CW$HASH_OPS\fR are references to hash arrays that define these virtual methods. \&\f(CW\*(C`HASH_OPS\*(C'\fR and \f(CW\*(C`LIST_OPS\*(C'\fR methods are subroutines that accept a hash/list reference as the first item. \f(CW\*(C`SCALAR_OPS\*(C'\fR are subroutines that accept a scalar value as the first item. Any other arguments specified when the method is called will be passed to the subroutine. .PP .Vb 2 \& # load Template::Stash to make method tables visible \& use Template::Stash; \& \& # define list method to return new list of odd numbers only \& $Template::Stash::LIST_OPS\->{ odd } = sub { \& my $list = shift; \& return [ grep { $_ % 2 } @$list ]; \& }; .Ve .PP Example template: .PP .Vb 2 \& [% primes = [ 2, 3, 5, 7, 9 ] %] \& [% primes.odd.join(\*(Aq, \*(Aq) %] # 3, 5, 7, 9 .Ve .PP \&\s-1TODO:\s0 document the \fBdefine_vmethod()\fR method which makes this even easier PK � �[�� �] �] man3/Template::Manual::Views.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Views 3" .TH Template::Manual::Views 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Views \- Template Toolkit views (experimental) .SH "Overview" .IX Header "Overview" A view is effectively a collection of templates and/or variable definitions which can be passed around as a self-contained unit. This then represents a particular interface or presentation style for other objects or items of data. .PP You can use views to implement custom \*(L"skins\*(R" for an application or content set. You can use them to help simplify the presentation of common objects or data types. You can even use then to automate the presentation of complex data structures such as that generated in an \&\f(CW\*(C`XML::DOM\*(C'\fR tree or similar. You let an iterator do the walking, and the view does the talking (or in this case, the presenting). Voila \- you have view independent, structure shy traversal using templates. .PP In general, views can be used in a number of different ways to achieve several different things. They elegantly solve some problems which were otherwise difficult or complicated, and make easy some things that were previously hard. .PP At the moment, they're still very experimental. The directive syntax and underlying \s-1API\s0 are likely to change quite considerably over the next version or two. Please be very wary about building your multi-million dollar e\-commerce solutions based around this feature. .SH "Views as Template Collectors/Providers" .IX Header "Views as Template Collectors/Providers" The \f(CW\*(C`VIEW\*(C'\fR directive starts a view definition and includes a name by which the view can be referenced. The view definition continues up to the matching \f(CW\*(C`END\*(C'\fR directive. .PP .Vb 3 \& [% VIEW myview %] \& ... \& [% END %] .Ve .PP The first role of a view is to act as a collector and provider of templates. The \f(CW\*(C`include()\*(C'\fR method can be called on a view to effectively do the same thing as the \f(CW\*(C`INCLUDE\*(C'\fR directive. The template name is passed as the first argument, followed by any local variable definitions for the template. .PP .Vb 1 \& [% myview.include(\*(Aqheader\*(Aq, title=\*(AqThe Title\*(Aq) %] \& \& # equivalent to \& [% INCLUDE header title=\*(AqThe Title\*(Aq %] .Ve .PP Views accept a number of configuration options which can be used to control different aspects of their behaviour. The '\f(CW\*(C`prefix\*(C'\fR' and '\f(CW\*(C`suffix\*(C'\fR' options can be specified to add a fixed prefix and/or suffix to the name of each template. .PP .Vb 5 \& [% VIEW myview \& prefix = \*(Aqmy/\*(Aq \& suffix = \*(Aq.tt2\*(Aq ; \& END \& %] .Ve .PP Now the call .PP .Vb 1 \& [% myview.include(\*(Aqheader\*(Aq, title=\*(AqThe Title\*(Aq) %] .Ve .PP is equivalent to .PP .Vb 1 \& [% INCLUDE my/header.tt2 title=\*(AqThe Title\*(Aq %] .Ve .PP Views provide an \f(CW\*(C`AUTOLOAD\*(C'\fR method which maps method names to the \&\f(CW\*(C`include()\*(C'\fR method. Thus, the following are all equivalent: .PP .Vb 3 \& [% myview.include(\*(Aqheader\*(Aq, title=\*(AqHello World\*(Aq) %] \& [% myview.include_header(title=\*(AqHello World\*(Aq) %] \& [% myview.header(title=\*(AqHello World\*(Aq) %] .Ve .SH "Local BLOCK Definitions" .IX Header "Local BLOCK Definitions" A \f(CW\*(C`VIEW\*(C'\fR definition can include \f(CW\*(C`BLOCK\*(C'\fR definitions which remain local to the view. A request for a particular template will return a \f(CW\*(C`BLOCK\*(C'\fR, if defined, in preference to any other template of the same name. .PP .Vb 3 \& [% BLOCK foo %] \& public foo block \& [% END %] \& \& [% VIEW plain %] \& [% BLOCK foo %] \& plain foo block \& [% END %] \& [% END %] \& \& [% VIEW fancy %] \& [% BLOCK foo %] \& fancy foo block \& [% END %] \& [% END %] \& \& [% INCLUDE foo %] # public foo block \& [% plain.foo %] # plain foo block \& [% fancy.foo %] # fancy foo block .Ve .PP In addition to \f(CW\*(C`BLOCK\*(C'\fR definitions, a \f(CW\*(C`VIEW\*(C'\fR can contain any other template directives. The entire \f(CW\*(C`VIEW\*(C'\fR definition block is processed to initialise the view but no output is generated (this may change \s-1RSN\s0 \- and get stored as '\f(CW\*(C`output\*(C'\fR' item, subsequently accessible as \f(CW\*(C`[% view.output %]\*(C'\fR). However, directives that have side-effects, such as those that update a variable, will have noticeable consequences. .SH "Preserving Variable State within Views" .IX Header "Preserving Variable State within Views" Views can also be used to save the values of any existing variables, or to create new ones at the point at which the view is defined. Unlike simple template metadata (\f(CW\*(C`META\*(C'\fR) which can only contain static string values, the view initialisation block can contain any template directives and generate any kind of dynamic output and/or data items. .PP .Vb 5 \& [% VIEW my_web_site %] \& [% view.title = title or \*(AqMy Cool Web Site\*(Aq %] \& [% view.author = "$abw.name, $abw.email" %] \& [% view.sidebar = INCLUDE my/sidebar.tt2 %] \& [% END %] .Ve .PP Note that additional data items can be specified as arguments to the \f(CW\*(C`VIEW\*(C'\fR directive. Anything that doesn't look like a configuration parameter is assumed to be a data item. This can be a little hazardous, of course, because you never know when a new configuration item might get added which interferes with your data. .PP .Vb 10 \& [% VIEW my_web_site \& # config options \& prefix = \*(Aqmy/\*(Aq \& # misc data \& title = title or \*(AqMy Cool Web Site\*(Aq \& author = "$abw.name, $abw.email" \& sidebar = INCLUDE my/sidebar.tt2 \& %] \& ... \& [% END %] .Ve .PP Outside of the view definition you can access the view variables as, for example: .PP .Vb 1 \& [% my_web_site.title %] .Ve .PP One important feature is the equivalence of simple variables and templates. You can implement the view item '\f(CW\*(C`title\*(C'\fR' as a simple variable, a template defined in an external file, possibly with a prefix/suffix automatically appended, or as a local \f(CW\*(C`BLOCK\*(C'\fR definition within the \f(CW\*(C`[% VIEW %] ... [% END %]\*(C'\fR definition. If you use the syntax above then the view will Do The Right Thing to return the appropriate output. .PP At the \f(CW\*(C`END\*(C'\fR of the \f(CW\*(C`VIEW\*(C'\fR definition the view is \*(L"sealed\*(R" to prevent you from accidentally updating any variable values. If you attempt to change the value of a variable after the \f(CW\*(C`END\*(C'\fR of the \f(CW\*(C`VIEW\*(C'\fR definition block then a \f(CW\*(C`view\*(C'\fR error will be thrown. .PP .Vb 6 \& [% TRY; \& my_web_site.title = \*(AqNew Title\*(Aq; \& CATCH; \& error; \& END \& %] .Ve .PP The error above will be reported as: .PP .Vb 1 \& view error \- cannot update item in sealed view: title .Ve .PP The same is true if you pass a parameter to a view variable. This is interpreted as an attempt to update the variable and will raise the same warning. .PP .Vb 1 \& [% my_web_site.title(\*(AqNew Title\*(Aq) %] # view error! .Ve .PP You can set the \f(CW\*(C`silent\*(C'\fR parameter to have the view ignore these parameters and simply return the variable value. .PP .Vb 6 \& [% VIEW my_web_site \& silent = 1 \& title = title or \*(AqMy Cool Web Site\*(Aq \& # ... ; \& END \& %] \& \& [% my_web_site.title(\*(AqBlah Blah\*(Aq) %] # My Cool Web Site .Ve .PP Alternately, you can specify that a view is unsealed allowing existing variables to be updated and new variables defined. .PP .Vb 6 \& [% VIEW my_web_site \& sealed = 0 \& title = title or \*(AqMy Cool Web Site\*(Aq \& # ... ; \& END \& %] \& \& [% my_web_site.title(\*(AqBlah Blah\*(Aq) %] # Blah Blah \& [% my_web_site.title %] # Blah Blah .Ve .SS "Inheritance, Delegation and Reuse" .IX Subsection "Inheritance, Delegation and Reuse" Views can be inherited from previously defined views by use of the \f(CW\*(C`base\*(C'\fR parameter. This example shows how a base class view is defined which applies a \f(CW\*(C`view/default/\*(C'\fR prefix to all template names. .PP .Vb 4 \& [% VIEW my.view.default \& prefix = \*(Aqview/default/\*(Aq; \& END \& %] .Ve .PP Thus the directive: .PP .Vb 1 \& [% my.view.default.header(title=\*(AqHello World\*(Aq) %] .Ve .PP is now equivalent to: .PP .Vb 1 \& [% INCLUDE view/default/header title=\*(AqHello World\*(Aq %] .Ve .PP A second view can be defined which specifies the default view as a base. .PP .Vb 5 \& [% VIEW my.view.fancy \& base = my.view.default \& prefix = \*(Aqview/fancy/\*(Aq; \& END \& %] .Ve .PP Now the directive: .PP .Vb 1 \& [% my.view.fancy.header(title=\*(AqHello World\*(Aq) %] .Ve .PP will resolve to: .PP .Vb 1 \& [% INCLUDE view/fancy/header title=\*(AqHello World\*(Aq %] .Ve .PP or if that doesn't exist, it will be handled by the base view as: .PP .Vb 1 \& [% INCLUDE view/default/header title=\*(AqHello World\*(Aq %] .Ve .PP When a parent view is specified via the \f(CW\*(C`base\*(C'\fR parameter, the delegation of a view to its parent for fetching templates and accessing user defined variables is automatic. You can also implement your own inheritance, delegation or other reuse patterns by explicitly delegating to other views. .PP .Vb 3 \& [% BLOCK foo %] \& public foo block \& [% END %] \& \& [% VIEW plain %] \& [% BLOCK foo %] \& <plain>[% PROCESS foo %]</plain> \& [% END %] \& [% END %] \& \& [% VIEW fancy %] \& [% BLOCK foo %] \& [% plain.foo | replace(\*(Aqplain\*(Aq, \*(Aqfancy\*(Aq) %] \& [% END %] \& [% END %] \& \& [% plain.foo %] # <plain>public foo block</plain> \& [% fancy.foo %] # <fancy>public foo block</fancy> .Ve .PP Note that the regular \f(CW\*(C`INCLUDE/PROCESS/WRAPPER\*(C'\fR directives work entirely independently of views and will always get the original, unaltered template name rather than any local per-view definition. .SS "Self-Reference" .IX Subsection "Self-Reference" A reference to the view object under definition is available with the \&\f(CW\*(C`VIEW ... END\*(C'\fR block by its specified name and also by the special name \&'\f(CW\*(C`view\*(C'\fR' (similar to the \f(CW\*(C`my $self = shift;\*(C'\fR in a Perl method or the \&'\f(CW\*(C`this\*(C'\fR' pointer in \*(C+, etc). The view is initially unsealed allowing any data items to be defined and updated within the \f(CW\*(C`VIEW ... END\*(C'\fR block. The view is automatically sealed at the end of the definition block, preventing any view data from being subsequently changed. .PP (\s-1NOTE:\s0 sealing should be optional. As well as sealing a view to prevent updates (\f(CW\*(C`SEALED\*(C'\fR), it should be possible to set an option in the view to allow external contexts to update existing variables (\f(CW\*(C`UPDATE\*(C'\fR) or even create totally new view variables (\f(CW\*(C`CREATE\*(C'\fR)). .PP .Vb 5 \& [% VIEW fancy %] \& [% fancy.title = \*(AqMy Fancy Title\*(Aq %] \& [% fancy.author = \*(AqFrank Open\*(Aq %] \& [% fancy.col = { bg => \*(Aq#ffffff\*(Aq, bar => \*(Aq#a0a0ff\*(Aq } %] \& [% END %] .Ve .PP or .PP .Vb 5 \& [% VIEW fancy %] \& [% view.title = \*(AqMy Fancy Title\*(Aq %] \& [% view.author = \*(AqFrank Open\*(Aq %] \& [% view.col = { bg => \*(Aq#ffffff\*(Aq, bar => \*(Aq#a0a0ff\*(Aq } %] \& [% END %] .Ve .PP It makes no real difference in this case if you refer to the view by its name, '\f(CW\*(C`fancy\*(C'\fR', or by the general name, '\f(CW\*(C`view\*(C'\fR'. Outside of the view block, however, you should always use the given name, '\f(CW\*(C`fancy\*(C'\fR': .PP .Vb 3 \& [% fancy.title %] \& [% fancy.author %] \& [% fancy.col.bg %] .Ve .PP The choice of given name or '\f(CW\*(C`view\*(C'\fR' is much more important when it comes to \f(CW\*(C`BLOCK\*(C'\fR definitions within a \f(CW\*(C`VIEW\*(C'\fR. It is generally recommended that you use '\f(CW\*(C`view\*(C'\fR' inside a \f(CW\*(C`VIEW\*(C'\fR definition because this is guaranteed to be correctly defined at any point in the future when the block gets called. The original name of the view might have long since been changed or reused but the self-reference via '\f(CW\*(C`view\*(C'\fR' should always be intact and valid. .PP Take the following \s-1VIEW\s0 as an example: .PP .Vb 6 \& [% VIEW foo %] \& [% view.title = \*(AqHello World\*(Aq %] \& [% BLOCK header %] \& Title: [% view.title %] \& [% END %] \& [% END %] .Ve .PP Even if we rename the view, or create a new \f(CW\*(C`foo\*(C'\fR variable, the header block still correctly accesses the \f(CW\*(C`title\*(C'\fR attribute of the view to which it belongs. Whenever a view \f(CW\*(C`BLOCK\*(C'\fR is processed, the \f(CW\*(C`view\*(C'\fR variable is always updated to contain the correct reference to the view object to which it belongs. .PP .Vb 3 \& [% bar = foo %] \& [% foo = { title => "New Foo" } %] # no problem \& [% bar.header %] # => Title: Hello World .Ve .SS "Saving References to External Views" .IX Subsection "Saving References to External Views" When it comes to view inheritance, it's always a good idea to take a local copy of a parent or delegate view and store it as an attribute within the view for later use. This ensures that the correct view reference is always available, even if the external name of a view has been changed. .PP .Vb 3 \& [% VIEW plain %] \& ... \& [% END %] \& \& [% VIEW fancy %] \& [% view.plain = plain %] \& [% BLOCK foo %] \& [% view.plain.foo | replace(\*(Aqplain\*(Aq, \*(Aqfancy\*(Aq) %] \& [% END %] \& [% END %] \& \& [% plain.foo %] # => <plain>public foo block</plain> \& [% plain = \*(Aqblah\*(Aq %] # no problem \& [% fancy.foo %] # => <fancy>public foo block</fancy> .Ve .SS "Views as Data Presenters" .IX Subsection "Views as Data Presenters" Another key role of a view is to act as a dispatcher to automatically apply the correct template to present a particular object or data item. This is handled via the \f(CW\*(C`print()\*(C'\fR method. .PP Here's an example: .PP .Vb 1 \& [% VIEW foo %] \& \& [% BLOCK text %] \& Some text: [% item %] \& [% END %] \& \& [% BLOCK hash %] \& a hash: \& [% FOREACH key = item.keys.sort \-%] \& [% key %] => [% item.$key %] \& [% END \-%] \& [% END %] \& \& [% BLOCK list %] \& a list: [% item.sort.join(\*(Aq, \*(Aq) %] \& [% END %] \& \& [% END %] .Ve .PP We can now use the view to print text, hashes or lists. The \f(CW\*(C`print()\*(C'\fR method includes the right template depending on the typing of the argument (or arguments) passed. .PP .Vb 3 \& [% some_text = \*(AqI read the news today, oh boy.\*(Aq %] \& [% a_hash = { house => \*(AqLords\*(Aq, hall => \*(AqAlbert\*(Aq } %] \& [% a_list = [ \*(Aqsure\*(Aq, \*(AqNobody\*(Aq, \*(Aqreally\*(Aq ] %] \& \& [% view.print(some_text) %] \& # Some text: I read the news today, oh boy. \& \& [% view.print(a_hash) %] \& # a hash: \& hall => Albert \& house => Lords \& [% view.print(a_list) %] \& # a list: Nobody, really, sure .Ve .PP You can also provide templates to print objects of any other class. The class name is mapped to a template name with all non-word character sequences such as '\f(CW\*(C`::\*(C'\fR' converted to a single '\f(CW\*(C`_\*(C'\fR'. .PP .Vb 7 \& [% VIEW foo %] \& [% BLOCK Foo_Bar %] \& a Foo::Bar object: \& thingies: [% view.print(item.thingies) %] \& doodahs: [% view.print(item.doodahs) %] \& [% END %] \& [% END %] \& \& [% USE fubar = Foo::Bar(...) %] \& \& [% foo.print(fubar) %] .Ve .PP Note how we use the view object to display various items within the objects ('\f(CW\*(C`thingies\*(C'\fR' and '\f(CW\*(C`doodahs\*(C'\fR'). We don't need to worry what kind of data these represent (text, list, hash, etc) because we can let the view worry about it, automatically mapping the data type to the correct template. .PP Views may define their own type => template map. .PP .Vb 11 \& [% VIEW foo \& map = { TEXT => \*(Aqplain_text\*(Aq, \& ARRAY => \*(Aqshow_list\*(Aq, \& HASH => \*(Aqshow_hash\*(Aq, \& My::Module => \*(Aqtemplate_name\*(Aq \& default => \*(Aqany_old_data\*(Aq \& } \& %] \& [% BLOCK plain_text %] \& ... \& [% END %] \& \& ... \& [% END %] .Ve .PP They can also provide a \f(CW\*(C`default\*(C'\fR map entry, specified as part of the \f(CW\*(C`map\*(C'\fR hash or as a parameter by itself. .PP .Vb 6 \& [% VIEW foo \& map = { ... }, \& default = \*(Aqwhatever\*(Aq \& %] \& ... \& [% END %] .Ve .PP or .PP .Vb 6 \& [% VIEW foo %] \& [% view.map = { ... } \& view.default = \*(Aqwhatever\*(Aq \& %] \& ... \& [% END %] .Ve .PP The \f(CW\*(C`print()\*(C'\fR method provides one more piece of magic. If you pass it a reference to an object which provides a \f(CW\*(C`present()\*(C'\fR method, then the method will be called passing the view as an argument. This then gives any object a chance to determine how it should be presented via the view. .PP .Vb 8 \& package Foo::Bar; \& ... \& sub present { \& my ($self, $view) = @_; \& return "a Foo::Bar object:\en" \& . "thingies: " . $view\->print($self\->{ _THINGIES }) . "\en" \& . "doodahs: " . $view\->print($self\->{ _DOODAHS }) . "\en"; \& } .Ve .PP The object is free to delve deeply into its innards and mess around with its own private data, before presenting the relevant data via the view. In a more complex example, a \f(CW\*(C`present()\*(C'\fR method might walk part of a tree making calls back against the view to present different nodes within the tree. We may not want to expose the internal structure of the tree (because that would break encapsulation and make our presentation code dependant on it) but we want to have some way of walking the tree and presenting items found in a particular manner. .PP This is known as \fIStructure Shy Traversal\fR. Our view object doesn't require prior knowledge about the internal structure of any data set to be able to traverse it and present the data contained therein. The data items themselves, via the \f(CW\*(C`present()\*(C'\fR method, can implement the internal iterators to guide the view along the right path to presentation happiness. .PP The upshot is that you can use views to greatly simplify the display of data structures like \f(CW\*(C`XML::DOM\*(C'\fR trees. The documentation for the \&\f(CW\*(C`Template::Plugin::XML::DOM\*(C'\fR module contains an example of this. In essence, it looks something like this: .PP \&\s-1XML\s0 source: .PP .Vb 4 \& <user name="Andy Wardley"> \& <project id="iCan" title="iCan, but theyCan\*(Aqt"/> \& <project id="p45" title="iDid, but theyDidn\*(Aqt"/> \& </user> .Ve .PP \&\s-1TT\s0 View: .PP .Vb 5 \& [% VIEW fancy %] \& [% BLOCK user %] \& User: [% item.name %] \& [% item.content(myview) %] \& [% END %] \& \& [% BLOCK project %] \& Project: [% project.id %] \- [% project.name %] \& [% END %] \& [% END %] .Ve .PP Generate view: .PP .Vb 2 \& [% USE dom = XML.DOM %] \& [% fancy.print(dom.parse(xml_source)) %] .Ve .PP Output: .PP .Vb 3 \& User: Andy Wardley \& Project: iCan \- iCan, but theyCan\*(Aqt \& Project: p45 \- iDid, but theyDidn\*(Aqt .Ve .PP The same approach can be applied to many other areas. Here's an example from the \f(CW\*(C`File\*(C'\fR/\f(CW\*(C`Directory\*(C'\fR plugins. .PP .Vb 4 \& [% VIEW myview %] \& [% BLOCK file %] \& \- [% item.name %] \& [% END %] \& \& [% BLOCK directory %] \& * [% item.name %] \& [% item.content(myview) FILTER indent %] \& [% END %] \& [% END %] \& \& [% USE dir = Directory(dirpath) %] \& [% myview.print(dir) %] .Ve .PP And here's the same approach use to convert \s-1POD\s0 documentation to any other format via template. .PP .Vb 3 \& [% # load Pod plugin and parse source file into Pod Object Model \& USE Pod; \& pom = Pod.parse_file(my_pod_file); \& \& # define view to map all Pod elements to "pod/html/xxx" templates \& VIEW pod2html \& prefix=\*(Aqpod/html\*(Aq; \& END; \& \& # now print document via view (i.e. as HTML) \& pod2html.print(pom) \& %] .Ve .PP Here we simply define a template prefix for the view which causes the view to look for \f(CW\*(C`pod/html/head1\*(C'\fR, \f(CW\*(C`pod/html/head2\*(C'\fR, \f(CW\*(C`pod/html/over\*(C'\fR as templates to present the different sections of the parsed Pod document. .PP There are some examples in the Template Toolkit test suite: \fIt/pod.t\fR and \&\fIt/view.t\fR which may shed some more light on this. See the distribution sub-directory \fIexamples/pod/html\fR for examples of Pod \-> \s-1HTML\s0 templates. PK � �[�s�sy y man3/Template::Tools.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Tools 3" .TH Template::Tools 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tools \- Command Line Tools for the Template Toolkit .SH "Template Tools" .IX Header "Template Tools" The Template Toolkit includes the following command line tools for processing templates. .SS "tpage" .IX Subsection "tpage" The tpage script can be used to process a single template using the Template Toolkit. .PP .Vb 1 \& $ tpage \-\-define msg="Hello World" greeting.tt2 .Ve .PP Use the \f(CW\*(C`\-h\*(C'\fR option to get a summary of options: .PP .Vb 1 \& $ tpage \-h .Ve .PP See the Template::Tools::tpage documentation for further information and examples of use. .SS "ttree" .IX Subsection "ttree" The ttree script can be used to process an entire directory of templates. .PP .Vb 1 \& $ ttree \-\-src /path/to/templates \-\-dest /path/to/output .Ve .PP Use the \f(CW\*(C`\-h\*(C'\fR option to get a summary of options: .PP .Vb 1 \& $ ttree \-h .Ve .PP See the Template::Tools::ttree documentation for further information and examples of use. PK � �[�I��7 7 ! man3/Template::Plugin::Assert.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Assert 3" .TH Template::Plugin::Assert 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Assert \- trap undefined values .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE assert %] \& \& # throws error if any undefined values are returned \& [% object.assert.method %] \& [% hash.assert.key %] \& [% list.assert.item %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin defines the \f(CW\*(C`assert\*(C'\fR virtual method that can be used to automatically throw errors when undefined values are used. .PP For example, consider this dotop: .PP .Vb 1 \& [% user.name %] .Ve .PP If \f(CW\*(C`user.name\*(C'\fR is an undefined value then \s-1TT\s0 will silently ignore the fact and print nothing. If you \f(CW\*(C`USE\*(C'\fR the \f(CW\*(C`assert\*(C'\fR plugin then you can add the \f(CW\*(C`assert\*(C'\fR vmethod between the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`name\*(C'\fR elements, like so: .PP .Vb 1 \& [% user.assert.name %] .Ve .PP Now, if \f(CW\*(C`user.name\*(C'\fR is an undefined value, an exception will be thrown: .PP .Vb 1 \& assert error \- undefined value for name .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2008\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[��n�+ �+ man3/Template::Plugin::File.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::File 3" .TH Template::Plugin::File 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::File \- Plugin providing information about files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& [% USE File(filepath) %] \& [% File.path %] # full path \& [% File.name %] # filename \& [% File.dir %] # directory .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin provides an abstraction of a file. It can be used to fetch details about files from the file system, or to represent abstract files (e.g. when creating an index page) that may or may not exist on a file system. .PP A file name or path should be specified as a constructor argument. e.g. .PP .Vb 3 \& [% USE File(\*(Aqfoo.html\*(Aq) %] \& [% USE File(\*(Aqfoo/bar/baz.html\*(Aq) %] \& [% USE File(\*(Aq/foo/bar/baz.html\*(Aq) %] .Ve .PP The file should exist on the current file system (unless \f(CW\*(C`nostat\*(C'\fR option set, see below) as an absolute file when specified with as leading '\f(CW\*(C`/\*(C'\fR' as per '\f(CW\*(C`/foo/bar/baz.html\*(C'\fR', or otherwise as one relative to the current working directory. The constructor performs a \f(CW\*(C`stat()\*(C'\fR on the file and makes the 13 elements returned available as the plugin items: .PP .Vb 2 \& dev ino mode nlink uid gid rdev size \& atime mtime ctime blksize blocks .Ve .PP e.g. .PP .Vb 1 \& [% USE File(\*(Aq/foo/bar/baz.html\*(Aq) %] \& \& [% File.mtime %] \& [% File.mode %] \& ... .Ve .PP In addition, the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`group\*(C'\fR items are set to contain the user and group names as returned by calls to \f(CW\*(C`getpwuid()\*(C'\fR and \f(CW\*(C`getgrgid()\*(C'\fR for the file \f(CW\*(C`uid\*(C'\fR and \f(CW\*(C`gid\*(C'\fR elements, respectively. On Win32 platforms on which \f(CW\*(C`getpwuid()\*(C'\fR and \f(CW\*(C`getgrid()\*(C'\fR are not available, these values are undefined. .PP .Vb 3 \& [% USE File(\*(Aq/tmp/foo.html\*(Aq) %] \& [% File.uid %] # e.g. 500 \& [% File.user %] # e.g. abw .Ve .PP This user/group lookup can be disabled by setting the \f(CW\*(C`noid\*(C'\fR option. .PP .Vb 3 \& [% USE File(\*(Aq/tmp/foo.html\*(Aq, noid=1) %] \& [% File.uid %] # e.g. 500 \& [% File.user %] # nothing .Ve .PP The \f(CW\*(C`isdir\*(C'\fR flag will be set if the file is a directory. .PP .Vb 2 \& [% USE File(\*(Aq/tmp\*(Aq) %] \& [% File.isdir %] # 1 .Ve .PP If the \f(CW\*(C`stat()\*(C'\fR on the file fails (e.g. file doesn't exists, bad permission, etc) then the constructor will throw a \f(CW\*(C`File\*(C'\fR exception. This can be caught within a \f(CW\*(C`TRY...CATCH\*(C'\fR block. .PP .Vb 6 \& [% TRY %] \& [% USE File(\*(Aq/tmp/myfile\*(Aq) %] \& File exists! \& [% CATCH File %] \& File error: [% error.info %] \& [% END %] .Ve .PP Note the capitalisation of the exception type, '\f(CW\*(C`File\*(C'\fR', to indicate an error thrown by the \f(CW\*(C`File\*(C'\fR plugin, to distinguish it from a regular \&\f(CW\*(C`file\*(C'\fR exception thrown by the Template Toolkit. .PP Note that the \f(CW\*(C`File\*(C'\fR plugin can also be referenced by the lower case name '\f(CW\*(C`file\*(C'\fR'. However, exceptions are always thrown of the \f(CW\*(C`File\*(C'\fR type, regardless of the capitalisation of the plugin named used. .PP .Vb 2 \& [% USE file(\*(Aqfoo.html\*(Aq) %] \& [% file.mtime %] .Ve .PP As with any other Template Toolkit plugin, an alternate name can be specified for the object created. .PP .Vb 2 \& [% USE foo = file(\*(Aqfoo.html\*(Aq) %] \& [% foo.mtime %] .Ve .PP The \f(CW\*(C`nostat\*(C'\fR option can be specified to prevent the plugin constructor from performing a \f(CW\*(C`stat()\*(C'\fR on the file specified. In this case, the file does not have to exist in the file system, no attempt will be made to verify that it does, and no error will be thrown if it doesn't. The entries for the items usually returned by \f(CW\*(C`stat()\*(C'\fR will be set empty. .PP .Vb 2 \& [% USE file(\*(Aq/some/where/over/the/rainbow.html\*(Aq, nostat=1) \& [% file.mtime %] # nothing .Ve .SH "METHODS" .IX Header "METHODS" All \f(CW\*(C`File\*(C'\fR plugins, regardless of the \f(CW\*(C`nostat\*(C'\fR option, have set a number of items relating to the original path specified. .SS "path" .IX Subsection "path" The full, original file path specified to the constructor. .PP .Vb 2 \& [% USE file(\*(Aq/foo/bar.html\*(Aq) %] \& [% file.path %] # /foo/bar.html .Ve .SS "name" .IX Subsection "name" The name of the file without any leading directories. .PP .Vb 2 \& [% USE file(\*(Aq/foo/bar.html\*(Aq) %] \& [% file.name %] # bar.html .Ve .SS "dir" .IX Subsection "dir" The directory element of the path with the filename removed. .PP .Vb 2 \& [% USE file(\*(Aq/foo/bar.html\*(Aq) %] \& [% file.name %] # /foo .Ve .SS "ext" .IX Subsection "ext" The file extension, if any, appearing at the end of the path following a '\f(CW\*(C`.\*(C'\fR' (not included in the extension). .PP .Vb 2 \& [% USE file(\*(Aq/foo/bar.html\*(Aq) %] \& [% file.ext %] # html .Ve .SS "home" .IX Subsection "home" This contains a string of the form '\f(CW\*(C`../..\*(C'\fR' to represent the upward path from a file to its root directory. .PP .Vb 2 \& [% USE file(\*(Aqbar.html\*(Aq) %] \& [% file.home %] # nothing \& \& [% USE file(\*(Aqfoo/bar.html\*(Aq) %] \& [% file.home %] # .. \& \& [% USE file(\*(Aqfoo/bar/baz.html\*(Aq) %] \& [% file.home %] # ../.. .Ve .SS "root" .IX Subsection "root" The \f(CW\*(C`root\*(C'\fR item can be specified as a constructor argument, indicating a root directory in which the named file resides. This is otherwise set empty. .PP .Vb 2 \& [% USE file(\*(Aqfoo/bar.html\*(Aq, root=\*(Aq/tmp\*(Aq) %] \& [% file.root %] # /tmp .Ve .SS "abs" .IX Subsection "abs" This returns the absolute file path by constructing a path from the \&\f(CW\*(C`root\*(C'\fR and \f(CW\*(C`path\*(C'\fR options. .PP .Vb 4 \& [% USE file(\*(Aqfoo/bar.html\*(Aq, root=\*(Aq/tmp\*(Aq) %] \& [% file.path %] # foo/bar.html \& [% file.root %] # /tmp \& [% file.abs %] # /tmp/foo/bar.html .Ve .SS "rel(path)" .IX Subsection "rel(path)" This returns a relative path from the current file to another path specified as an argument. It is constructed by appending the path to the '\f(CW\*(C`home\*(C'\fR' item. .PP .Vb 2 \& [% USE file(\*(Aqfoo/bar/baz.html\*(Aq) %] \& [% file.rel(\*(Aqwiz/waz.html\*(Aq) %] # ../../wiz/waz.html .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" .Vb 1 \& [% USE file(\*(Aq/foo/bar/baz.html\*(Aq) %] \& \& [% file.path %] # /foo/bar/baz.html \& [% file.dir %] # /foo/bar \& [% file.name %] # baz.html \& [% file.home %] # ../.. \& [% file.root %] # \*(Aq\*(Aq \& [% file.abs %] # /foo/bar/baz.html \& [% file.ext %] # html \& [% file.mtime %] # 987654321 \& [% file.atime %] # 987654321 \& [% file.uid %] # 500 \& [% file.user %] # abw \& \& [% USE file(\*(Aqfoo.html\*(Aq) %] \& \& [% file.path %] # foo.html \& [% file.dir %] # \*(Aq\*(Aq \& [% file.name %] # foo.html \& [% file.root %] # \*(Aq\*(Aq \& [% file.home %] # \*(Aq\*(Aq \& [% file.abs %] # foo.html \& \& [% USE file(\*(Aqfoo/bar/baz.html\*(Aq) %] \& \& [% file.path %] # foo/bar/baz.html \& [% file.dir %] # foo/bar \& [% file.name %] # baz.html \& [% file.root %] # \*(Aq\*(Aq \& [% file.home %] # ../.. \& [% file.abs %] # foo/bar/baz.html \& \& [% USE file(\*(Aqfoo/bar/baz.html\*(Aq, root=\*(Aq/tmp\*(Aq) %] \& \& [% file.path %] # foo/bar/baz.html \& [% file.dir %] # foo/bar \& [% file.name %] # baz.html \& [% file.root %] # /tmp \& [% file.home %] # ../.. \& [% file.abs %] # /tmp/foo/bar/baz.html \& \& # calculate other file paths relative to this file and its root \& [% USE file(\*(Aqfoo/bar/baz.html\*(Aq, root => \*(Aq/tmp/tt2\*(Aq) %] \& \& [% file.path(\*(Aqbaz/qux.html\*(Aq) %] # ../../baz/qux.html \& [% file.dir(\*(Aqwiz/woz.html\*(Aq) %] # ../../wiz/woz.html .Ve .SH "AUTHORS" .IX Header "AUTHORS" Michael Stevens wrote the original \f(CW\*(C`Directory\*(C'\fR plugin on which this is based. Andy Wardley split it into separate \f(CW\*(C`File\*(C'\fR and \f(CW\*(C`Directory\*(C'\fR plugins, added some extra code and documentation for \f(CW\*(C`VIEW\*(C'\fR support, and made a few other minor tweaks. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2000\-2022 Michael Stevens, Andy Wardley. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Template::Plugin::Directory, Template::View PK � �[��4� � ! man3/Template::Plugin::Dumper.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Dumper 3" .TH Template::Plugin::Dumper 3 "2022-04-26" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Dumper \- Plugin interface to Data::Dumper .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE Dumper %] \& \& [% Dumper.dump(variable) %] \& [% Dumper.dump_html(variable) %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a very simple Template Toolkit Plugin Interface to the Data::Dumper module. A \f(CW\*(C`Dumper\*(C'\fR object will be instantiated via the following directive: .PP .Vb 1 \& [% USE Dumper %] .Ve .PP As a standard plugin, you can also specify its name in lower case: .PP .Vb 1 \& [% USE dumper %] .Ve .PP The \f(CW\*(C`Data::Dumper\*(C'\fR \f(CW\*(C`Pad\*(C'\fR, \f(CW\*(C`Indent\*(C'\fR and \f(CW\*(C`Varname\*(C'\fR options are supported as constructor arguments to affect the output generated. See Data::Dumper for further details. .PP .Vb 1 \& [% USE dumper(Indent=0, Pad="<br>") %] .Ve .PP These options can also be specified in lower case. .PP .Vb 1 \& [% USE dumper(indent=0, pad="<br>") %] .Ve .SH "METHODS" .IX Header "METHODS" There are two methods supported by the \f(CW\*(C`Dumper\*(C'\fR object. Each will output into the template the contents of the variables passed to the object method. .SS "\fBdump()\fP" .IX Subsection "dump()" Generates a raw text dump of the data structure(s) passed .PP .Vb 3 \& [% USE Dumper %] \& [% Dumper.dump(myvar) %] \& [% Dumper.dump(myvar, yourvar) %] .Ve .SS "\fBdump_html()\fP" .IX Subsection "dump_html()" Generates a dump of the data structures, as per \fBdump()\fR, but with the characters <, > and & converted to their equivalent \s-1HTML\s0 entities and newlines converted to <br>. .PP .Vb 2 \& [% USE Dumper %] \& [% Dumper.dump_html(myvar) %] .Ve .SH "AUTHOR" .IX Header "AUTHOR" Simon Matthews <sam@tt2.org> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2000 Simon Matthews. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Data::Dumper PK � �[��M M man3/Template::Modules.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Modules 3" .TH Template::Modules 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Modules \- Template Toolkit Modules .SH "Template Toolkit Modules" .IX Header "Template Toolkit Modules" This documentation provides an overview of the different modules that comprise the Template Toolkit. .SS "Template" .IX Subsection "Template" The Template module is the front-end to the Template Toolkit for Perl programmers. .PP .Vb 3 \& use Template; \& my $tt = Template\->new(); \& $tt\->process(\*(Aqhello.html\*(Aq, message => \*(AqHello World\*(Aq); .Ve .SS "Template::Base" .IX Subsection "Template::Base" The Template::Base module implements a base class from which the other Template Toolkit modules are derived. It implements common functionality for creating objects, error reporting, debugging, and so on. .SS "Template::Config" .IX Subsection "Template::Config" The Template::Config module defines the configuration of the Template Toolkit for your system. It is an example of a \fIfactory module\fR which is responsible for instantiating the various other modules used in the Template Toolkit. .PP For example, the Template::Config module defines the \f(CW$STASH\fR package variable which indicates which version of the Template::Stash you are using by default. If you elected to use the faster \s-1XS\s0 stash when you installed the Template Toolkit, then this will be set as: .PP .Vb 1 \& $STASH = \*(AqTemplate::Stash::XS\*(Aq; .Ve .PP Otherwise you'll get the regular Perl stash: .PP .Vb 1 \& $STASH = \*(AqTemplate::Stash\*(Aq; .Ve .PP This approach means that other parts of the Template Toolkit don't have to worry about which stash you're using. They just ask the Template::Config module to create a stash of the right kind. .SS "Template::Constants" .IX Subsection "Template::Constants" The Template::Constants defines a number of constants that are used by the Template Toolkit. .PP For example, the \f(CW\*(C`:chomp\*(C'\fR tagset defines the \f(CW\*(C`CHOMP_???\*(C'\fR constants that can be used with the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR configuration options. .PP .Vb 4 \& use Template::Constants \*(Aq:chomp\*(Aq; \& my $tt = Template\->new({ \& PRE_CHOMP => CHOMP_COLLAPSE, \& }); .Ve .SS "Template::Context" .IX Subsection "Template::Context" The Template::Context module defines a runtime context in which templates are processed. A context keeps track of all the templates, variables, plugins, and other resources that are available (either directly or through delegate objects) and provides methods to fetch, store, and perform various operations on them. .SS "Template::Document" .IX Subsection "Template::Document" The Template::Document module implements a compiled template document object. This is generated by the Template::Parser module. .SS "Template::Exception" .IX Subsection "Template::Exception" The Template::Exception module implements an exception object which is used for runtime error reporting. .SS "Template::Filters" .IX Subsection "Template::Filters" The Template::Filters module implements a filter provider. It includes the core collection of filters that can be used via the \f(CW\*(C`FILTER\*(C'\fR directive. .SS "Template::Iterator" .IX Subsection "Template::Iterator" The Template::Iterator module implements a data iterator which steps through each item in a list in turn. It is used by the \f(CW\*(C`FOREACH\*(C'\fR directive. Within a \f(CW\*(C`FOREACH\*(C'\fR block, the \f(CW\*(C`loop\*(C'\fR variable always references the current iterator object. .PP .Vb 10 \& [% FOREACH item IN list; \& IF loop.first; \& # first item in loop \& ELSIF loop.last; \& # last item in loop \& ELSE; \& # any other item in loop \& END; \& END \& %] .Ve .SS "Template::Namespace::Constants" .IX Subsection "Template::Namespace::Constants" The Template::Namespace::Constants module is used internally to represent constants. These can be resolved immediately at the point that a template is compiled. .SS "Template::Parser" .IX Subsection "Template::Parser" The Template::Parser module is used to parse a source template and turn it into Perl code which can be executed. .SS "Template::Plugin" .IX Subsection "Template::Plugin" The Template::Plugin module is a base class for Template Toolkit plugins that can be loaded on demand from within a template using the \f(CW\*(C`USE\*(C'\fR directive. .SS "Template::Plugins" .IX Subsection "Template::Plugins" The Template::Plugins module is the plugins provider. It loads and prepares plugins as and when they are requested from within a template. .SS "Template::Provider" .IX Subsection "Template::Provider" The Template::Provider module is responsible for loading, compiling and caching templates. .SS "Template::Service" .IX Subsection "Template::Service" The Template::Service module implements a service layer that sits just behind the Template module, and just in front of a Template::Context. It handles each request to process a template (forwarded from the Template module). It adds any headers and/or footers (specified via the \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR options), applies any wrapper (the \f(CW\*(C`WRAPPER\*(C'\fR option) and catches any errors returned (the \f(CW\*(C`ERRORS\*(C'\fR option). .SS "Template::Stash" .IX Subsection "Template::Stash" The Template::Stash module is used to fetch and store template variables. It implements all of the magic associated with the dot operator. .SS "Template::Stash::XS" .IX Subsection "Template::Stash::XS" The Template::Stash::XS module is a high-speed implementation of Template::Stash written in C. .SS "Template::Test" .IX Subsection "Template::Test" The Template::Test module is used to automate the Template Toolkit test scripts. PK � �[ V�� � man3/Template::Manual.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual 3" .TH Template::Manual 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual \- Template Toolkit User Manual .SH "Template Toolkit Manual" .IX Header "Template Toolkit Manual" The Template Toolkit manual contains documentation on using and extending the Template Toolkit. .SS "Template::Manual::Intro" .IX Subsection "Template::Manual::Intro" The Template::Manual::Intro page provides an introduction to the Template Toolkit .SS "Template::Manual::Syntax" .IX Subsection "Template::Manual::Syntax" The Template::Manual::Syntax describes the syntax and structure of templates and the directive tags embedded within them. .SS "Template::Manual::Directives" .IX Subsection "Template::Manual::Directives" The Template::Manual::Directives page lists all the Template Toolkit directives and gives examples of their use. .SS "Template::Manual::Variables" .IX Subsection "Template::Manual::Variables" The Template::Manual::Variables page describes the use of variables in templates. .SS "Template::Manual::VMethods" .IX Subsection "Template::Manual::VMethods" The Template::Manual::VMethods page provides a full list of virtual methods that can be used in conjunction with variables, and gives examples of their use. .SS "Template::Manual::Config" .IX Subsection "Template::Manual::Config" The Template::Manual::Config page describes all of the Template Toolkit configuration options. .SS "Template::Manual::Filters" .IX Subsection "Template::Manual::Filters" The Template::Manual::Filters page lists all of the Template Toolkit filters and gives examples of their use. .SS "Template::Manual::Plugins" .IX Subsection "Template::Manual::Plugins" The Template::Manual::Plugins page lists all of the standard plugins distributed with Template Toolkit and gives examples of their use. .SS "Template::Manual::Internals" .IX Subsection "Template::Manual::Internals" The Template::Manual::Internals page describes the internal workings of the Template Toolkit. It is aimed at developers who wish to extend or modify the .SS "Template::Manual::Views" .IX Subsection "Template::Manual::Views" The Template::Manual::Views page describes the experimental \f(CW\*(C`VIEW\*(C'\fR directive. .SS "Template::Manual::Credits" .IX Subsection "Template::Manual::Credits" The Template::Manual::Credits page lists the people who have contributed to the Template Toolkit. PK � �[NE@$5 5 man3/Template::Test.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Test 3" .TH Template::Test 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Test \- Module for automating TT2 test scripts .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Test; \& \& $Template::Test::DEBUG = 0; # set this true to see each test running \& $Template::Test::EXTRA = 2; # 2 extra tests follow test_expect()... \& \& # ok() can be called any number of times before test_expect \& ok( $true_or_false ) \& \& # test_expect() splits $input into individual tests, processes each \& # and compares generated output against expected output \& test_expect($input, $template, \e%replace ); \& \& # $input is text or filehandle (e.g. DATA section after _\|_END_\|_) \& test_expect( $text ); \& test_expect( \e*DATA ); \& \& # $template is a Template object or configuration hash \& my $template_cfg = { ... }; \& test_expect( $input, $template_cfg ); \& my $template_obj = Template\->new($template_cfg); \& test_expect( $input, $template_obj ); \& \& # $replace is a hash reference of template variables \& my $replace = { \& a => \*(Aqalpha\*(Aq, \& b => \*(Aqbravo\*(Aq \& }; \& test_expect( $input, $template, $replace ); \& \& # ok() called after test_expect should be declared in $EXTRA (2) \& ok( $true_or_false ) \& ok( $true_or_false ) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Test\*(C'\fR module defines the \fBtest_expect()\fR and other related subroutines which can be used to automate test scripts for the Template Toolkit. See the numerous tests in the \fIt\fR sub-directory of the distribution for examples of use. .SH "PACKAGE SUBROUTINES" .IX Header "PACKAGE SUBROUTINES" .SS "\fBtext_expect()\fP" .IX Subsection "text_expect()" The \f(CW\*(C`test_expect()\*(C'\fR subroutine splits an input document into a number of separate tests, processes each one using the Template Toolkit and then compares the generated output against an expected output, also specified in the input document. It generates the familiar \&\f(CW\*(C`ok\*(C'\fR/\f(CW\*(C`not ok\*(C'\fR output compatible with \f(CW\*(C`Test::Harness\*(C'\fR. .PP The test input should be specified as a text string or a reference to a filehandle (e.g. \f(CW\*(C`GLOB\*(C'\fR or \f(CW\*(C`IO::Handle\*(C'\fR) from which it can be read. In particular, this allows the test input to be placed after the \f(CW\*(C`_\|_END_\|_\*(C'\fR marker and read via the \f(CW\*(C`DATA\*(C'\fR filehandle. .PP .Vb 1 \& use Template::Test; \& \& test_expect(\e*DATA); \& \& _\|_END_\|_ \& # this is the first test (this is a comment) \& \-\- test \-\- \& blah blah blah [% foo %] \& \-\- expect \-\- \& blah blah blah value_of_foo \& \& # here\*(Aqs the second test (no surprise, so is this) \& \-\- test \-\- \& more blah blah [% bar %] \& \-\- expect \-\- \& more blah blah value_of_bar .Ve .PP Blank lines between test sections are generally ignored. Any line starting with \f(CW\*(C`#\*(C'\fR is treated as a comment and is ignored. .PP The second and third parameters to \f(CW\*(C`test_expect()\*(C'\fR are optional. The second may be either a reference to a Template object which should be used to process the template fragments, or a reference to a hash array containing configuration values which should be used to instantiate a new Template object. .PP .Vb 6 \& # pass reference to config hash \& my $config = { \& INCLUDE_PATH => \*(Aq/here/there:/every/where\*(Aq, \& POST_CHOMP => 1, \& }; \& test_expect(\e*DATA, $config); \& \& # or create Template object explicitly \& my $template = Template\->new($config); \& test_expect(\e*DATA, $template); .Ve .PP The third parameter may be used to reference a hash array of template variable which should be defined when processing the tests. This is passed to the Template \fBprocess()\fR method. .PP .Vb 4 \& my $replace = { \& a => \*(Aqalpha\*(Aq, \& b => \*(Aqbravo\*(Aq, \& }; \& \& test_expect(\e*DATA, $config, $replace); .Ve .PP The second parameter may be left undefined to specify a default Template configuration. .PP .Vb 1 \& test_expect(\e*DATA, undef, $replace); .Ve .PP For testing the output of different Template configurations, a reference to a list of named Template objects also may be passed as the second parameter. .PP .Vb 3 \& my $tt1 = Template\->new({ ... }); \& my $tt2 = Template\->new({ ... }); \& my @tts = [ one => $tt1, two => $tt1 ]; .Ve .PP The first object in the list is used by default. Other objects may be switched in with a '\f(CW\*(C`\-\- use $name \-\-\*(C'\fR' marker. This should immediately follow a '\f(CW\*(C`\-\- test \-\-\*(C'\fR' line. That object will then be used for the rest of the test, or until a different object is selected. .PP .Vb 5 \& \-\- test \-\- \& \-\- use one \-\- \& [% blah %] \& \-\- expect \-\- \& blah, blah \& \& \-\- test \-\- \& still using one... \& \-\- expect \-\- \& ... \& \& \-\- test \-\- \& \-\- use two \-\- \& [% blah %] \& \-\- expect \-\- \& blah, blah, more blah .Ve .PP The \f(CW\*(C`test_expect()\*(C'\fR sub counts the number of tests, and then calls \fBntests()\fR to generate the familiar "\f(CW\*(C`1..$ntests\en\*(C'\fR" test harness line. Each test defined generates two test numbers. The first indicates that the input was processed without error, and the second that the output matches that expected. .PP Additional test may be run before \f(CW\*(C`test_expect()\*(C'\fR by calling \fBok()\fR. These test results are cached until \fBntests()\fR is called and the final number of tests can be calculated. Then, the "\f(CW\*(C`1..$ntests\*(C'\fR\*(L" line is output, along with \&\*(R"\f(CW\*(C`ok $n\*(C'\fR\*(L" / \*(R"\f(CW\*(C`not ok $n\*(C'\fR" lines for each of the cached test result. Subsequent calls to \fBok()\fR then generate an output line immediately. .PP .Vb 2 \& my $something = SomeObject\->new(); \& ok( $something ); \& \& my $other = AnotherThing\->new(); \& ok( $other ); \& \& test_expect(\e*DATA); .Ve .PP If any tests are to follow after \f(CW\*(C`test_expect()\*(C'\fR is called then these should be pre-declared by setting the \f(CW$EXTRA\fR package variable. This value (default: \f(CW0\fR) is added to the grand total calculated by \fBntests()\fR. The results of the additional tests are also registered by calling \fBok()\fR. .PP .Vb 1 \& $Template::Test::EXTRA = 2; \& \& # can call ok() any number of times before test_expect() \& ok( $did_that_work ); \& ok( $make_sure ); \& ok( $dead_certain ); \& \& # <some> number of tests... \& test_expect(\e*DATA, $config, $replace); \& \& # here\*(Aqs those $EXTRA tests \& ok( defined $some_result && ref $some_result eq \*(AqARRAY\*(Aq ); \& ok( $some_result\->[0] eq \*(Aqsome expected value\*(Aq ); .Ve .PP If you don't want to call \f(CW\*(C`test_expect()\*(C'\fR at all then you can call \&\f(CW\*(C`ntests($n)\*(C'\fR to declare the number of tests and generate the test header line. After that, simply call \fBok()\fR for each test passing a true or false values to indicate that the test passed or failed. .PP .Vb 3 \& ntests(2); \& ok(1); \& ok(0); .Ve .PP If you're really lazy, you can just call \fBok()\fR and not bother declaring the number of tests at all. All tests results will be cached until the end of the script and then printed in one go before the program exits. .PP .Vb 2 \& ok( $x ); \& ok( $y ); .Ve .PP You can identify only a specific part of the input file for testing using the '\f(CW\*(C`\-\- start \-\-\*(C'\fR' and '\f(CW\*(C`\-\- stop \-\-\*(C'\fR' markers. Anything before the first '\f(CW\*(C`\-\- start \-\-\*(C'\fR' is ignored, along with anything after the next \&'\f(CW\*(C`\-\- stop \-\-\*(C'\fR' marker. .PP .Vb 4 \& \-\- test \-\- \& this is test 1 (not performed) \& \-\- expect \-\- \& this is test 1 (not performed) \& \& \-\- start \-\- \& \& \-\- test \-\- \& this is test 2 \& \-\- expect \-\- \& this is test 2 \& \& \-\- stop \-\- \& \& ... .Ve .SS "\fBntests()\fP" .IX Subsection "ntests()" Subroutine used to specify how many tests you're expecting to run. .SS "ok($test)" .IX Subsection "ok($test)" Generates an "\f(CW\*(C`ok $n\*(C'\fR\*(L" or \*(R"\f(CW\*(C`not ok $n\*(C'\fR" message if \f(CW$test\fR is true or false. .SS "not_ok($test)" .IX Subsection "not_ok($test)" The logical inverse of \fBok()\fR. Prints an "\f(CW\*(C`ok $n\*(C'\fR" message is \f(CW$test\fR is \&\fIfalse\fR and vice-versa. .SS "\fBcallsign()\fP" .IX Subsection "callsign()" For historical reasons and general utility, the module also defines a \&\f(CW\*(C`callsign()\*(C'\fR subroutine which returns a hash mapping the letters \f(CW\*(C`a\*(C'\fR to \f(CW\*(C`z\*(C'\fR to their phonetic alphabet equivalent (e.g. radio callsigns). This is used by many of the test scripts as a known source of variable values. .PP .Vb 1 \& test_expect(\e*DATA, $config, callsign()); .Ve .SS "\fBbanner()\fP" .IX Subsection "banner()" This subroutine prints a simple banner including any text passed as parameters. The \f(CW$DEBUG\fR variable must be set for it to generate any output. .PP .Vb 1 \& banner(\*(AqTesting something\-or\-other\*(Aq); .Ve .PP example output: .PP .Vb 3 \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& # Testing something\-or\-other (27 tests completed) \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .Ve .SH "PACKAGE VARIABLES" .IX Header "PACKAGE VARIABLES" .ie n .SS "$DEBUG" .el .SS "\f(CW$DEBUG\fP" .IX Subsection "$DEBUG" The \f(CW$DEBUG\fR package variable can be set to enable debugging mode. .ie n .SS "$PRESERVE" .el .SS "\f(CW$PRESERVE\fP" .IX Subsection "$PRESERVE" The \f(CW$PRESERVE\fR package variable can be set to stop the \fBtest_expect()\fR from converting newlines in the output and expected output into the literal strings '\en'. .SH "HISTORY" .IX Header "HISTORY" This module started its butt-ugly life as the \f(CW\*(C`t/texpect.pl\*(C'\fR script. It was cleaned up to became the \f(CW\*(C`Template::Test\*(C'\fR module some time around version 0.29. It underwent further cosmetic surgery for version 2.00 but still retains some remarkable rear-end resemblances. .PP Since then the \f(CW\*(C`Test::More\*(C'\fR and related modules have appeared on \s-1CPAN\s0 making this module mostly, but not entirely, redundant. .ie n .SH "BUGS / KNOWN ""FEATURES""" .el .SH "BUGS / KNOWN ``FEATURES''" .IX Header "BUGS / KNOWN FEATURES" Imports all methods by default. This is generally a Bad Thing, but this module is only used in test scripts (i.e. at build time) so a) we don't really care and b) it saves typing. .PP The line splitter may be a bit dumb, especially if it sees lines like \&\f(CW\*(C`\-\- this \-\-\*(C'\fR that aren't supposed to be special markers. So don't do that. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template PK � �[����. �. " man3/Template::Manual::Plugins.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Plugins 3" .TH Template::Manual::Plugins 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Plugins \- Standard plugins .SH "TEMPLATE TOOLKIT PLUGINS" .IX Header "TEMPLATE TOOLKIT PLUGINS" The following plugin modules are distributed with the Template Toolkit. Some of the plugins interface to external modules (detailed below) which should be downloaded from any \s-1CPAN\s0 site and installed before using the plugin. .SS "Assert" .IX Subsection "Assert" New in 2.20! The Assert plugin adds an \&\f(CW\*(C`assert\*(C'\fR virtual method that you can use to catch undefined values. .PP For example, consider this dotop: .PP .Vb 1 \& [% user.name %] .Ve .PP If \f(CW\*(C`user.name\*(C'\fR is an undefined value then \s-1TT\s0 will silently ignore the fact and print nothing. If you \f(CW\*(C`USE\*(C'\fR the \f(CW\*(C`assert\*(C'\fR plugin then you can add the \f(CW\*(C`assert\*(C'\fR vmethod between the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`name\*(C'\fR elements, like so: .PP .Vb 1 \& [% user.assert.name %] .Ve .PP Now, if \f(CW\*(C`user.name\*(C'\fR is an undefined value, an exception will be thrown: .PP .Vb 1 \& assert error \- undefined value for name .Ve .SS "\s-1CGI\s0" .IX Subsection "CGI" The \s-1CGI\s0 plugin is a wrapper around Lincoln Stein's \&\s-1CGI\s0.pm module. The plugin is distributed with the Template Toolkit (see Template::Plugin::CGI) and the \s-1CGI\s0 module itself is distributed with recent versions Perl, or is available from \s-1CPAN.\s0 .PP .Vb 6 \& [% USE CGI %] \& [% CGI.param(\*(Aqparam_name\*(Aq) %] \& [% CGI.start_form %] \& [% CGI.popup_menu( Name => \*(Aqcolor\*(Aq, \& Values => [ \*(AqGreen\*(Aq, \*(AqBrown\*(Aq ] ) %] \& [% CGI.end_form %] .Ve .SS "Datafile" .IX Subsection "Datafile" Provides an interface to data stored in a plain text file in a simple delimited format. The first line in the file specifies field names which should be delimiter by any non-word character sequence. Subsequent lines define data using the same delimiter as in the first line. Blank lines and comments (lines starting '#') are ignored. See Template::Plugin::Datafile for further details. .PP /tmp/mydata: .PP .Vb 5 \& # define names for each field \& id : email : name : tel \& # here\*(Aqs the data \& fred : fred@here.com : Fred Smith : 555\-1234 \& bill : bill@here.com : Bill White : 555\-5678 .Ve .PP example: .PP .Vb 1 \& [% USE userlist = datafile(\*(Aq/tmp/mydata\*(Aq) %] \& \& [% FOREACH user = userlist %] \& [% user.name %] ([% user.id %]) \& [% END %] .Ve .SS "Date" .IX Subsection "Date" The Date plugin provides an easy way to generate formatted time and date strings by delegating to the \s-1POSIX\s0 \f(CW\*(C`strftime()\*(C'\fR routine. See Template::Plugin::Date and \s-1POSIX\s0 for further details. .PP .Vb 2 \& [% USE date %] \& [% date.format %] # current time/date \& \& File last modified: [% date.format(template.modtime) %] .Ve .SS "Directory" .IX Subsection "Directory" The Directory plugin provides a simple interface to a directory and the files within it. See Template::Plugin::Directory for further details. .PP .Vb 7 \& [% USE dir = Directory(\*(Aq/tmp\*(Aq) %] \& [% FOREACH file = dir.files %] \& # all the plain files in the directory \& [% END %] \& [% FOREACH file = dir.dirs %] \& # all the sub\-directories \& [% END %] .Ve .SS "\s-1DBI\s0" .IX Subsection "DBI" The \f(CW\*(C`DBI\*(C'\fR plugin is no longer distributed as part of the Template Toolkit (as of version 2.15). It is now available as a separate Template::DBI distribution from \s-1CPAN.\s0 .SS "Dumper" .IX Subsection "Dumper" The Dumper plugin provides an interface to the Data::Dumper module. See Template::Plugin::Dumper and Data::Dumper for further details. .PP .Vb 2 \& [% USE dumper(indent=0, pad="<br>") %] \& [% dumper.dump(myvar, yourvar) %] .Ve .SS "File" .IX Subsection "File" The File plugin provides a general abstraction for files and can be used to fetch information about specific files within a filesystem. See Template::Plugin::File for further details. .PP .Vb 4 \& [% USE File(\*(Aq/tmp/foo.html\*(Aq) %] \& [% File.name %] # foo.html \& [% File.dir %] # /tmp \& [% File.mtime %] # modification time .Ve .SS "Filter" .IX Subsection "Filter" This module implements a base class plugin which can be subclassed to easily create your own modules that define and install new filters. .PP .Vb 1 \& package MyOrg::Template::Plugin::MyFilter; \& \& use Template::Plugin::Filter; \& use base qw( Template::Plugin::Filter ); \& \& sub filter { \& my ($self, $text) = @_; \& # ...mungify $text... \& return $text; \& } .Ve .PP Example of use: .PP .Vb 2 \& # now load it... \& [% USE MyFilter %] \& \& # ...and use the returned object as a filter \& [% FILTER $MyFilter %] \& ... \& [% END %] .Ve .PP See Template::Plugin::Filter for further details. .SS "Format" .IX Subsection "Format" The Format plugin provides a simple way to format text according to a \f(CW\*(C`printf()\*(C'\fR\-like format. See Template::Plugin::Format for further details. .PP .Vb 2 \& [% USE bold = format(\*(Aq<b>%s</b>\*(Aq) %] \& [% bold(\*(AqHello\*(Aq) %] .Ve .SS "\s-1GD\s0" .IX Subsection "GD" The \f(CW\*(C`GD\*(C'\fR plugins are no longer part of the core Template Toolkit distribution. They are now available from \s-1CPAN\s0 in a separate Template::GD distribution. .SS "\s-1HTML\s0" .IX Subsection "HTML" The \s-1HTML\s0 plugin is very basic, implementing a few useful methods for generating \s-1HTML.\s0 It is likely to be extended in the future or integrated with a larger project to generate \s-1HTML\s0 elements in a generic way. .PP .Vb 4 \& [% USE HTML %] \& [% HTML.escape("if (a < b && c > d) ..." %] \& [% HTML.attributes(border => 1, cellpadding => 2) %] \& [% HTML.element(table => { border => 1, cellpadding => 2 }) %] .Ve .PP See Template::Plugin::HTML for further details. .SS "Iterator" .IX Subsection "Iterator" The Iterator plugin provides a way to create a Template::Iterator object to iterate over a data set. An iterator is created automatically by the \f(CW\*(C`FOREACH\*(C'\fR directive and is aliased to the \f(CW\*(C`loop\*(C'\fR variable. This plugin allows an iterator to be explicitly created with a given name, or the default plugin name, \f(CW\*(C`iterator\*(C'\fR. See Template::Plugin::Iterator for further details. .PP .Vb 1 \& [% USE iterator(list, args) %] \& \& [% FOREACH item = iterator %] \& [% \*(Aq<ul>\*(Aq IF iterator.first %] \& <li>[% item %] \& [% \*(Aq</ul>\*(Aq IF iterator.last %] \& [% END %] .Ve .SS "Pod" .IX Subsection "Pod" This plugin provides an interface to the Pod::POM module which parses \s-1POD\s0 documents into an internal object model which can then be traversed and presented through the Template Toolkit. .PP .Vb 1 \& [% USE Pod(podfile) %] \& \& [% FOREACH head1 = Pod.head1; \& FOREACH head2 = head1/head2; \& ... \& END; \& END \& %] .Ve .SS "Scalar" .IX Subsection "Scalar" The Template Toolkit calls user-defined subroutines and object methods using Perl's array context by default. .PP .Vb 2 \& # TT2 calls object methods in array context by default \& [% object.method %] .Ve .PP This plugin module provides a way for you to call subroutines and methods in scalar context. .PP .Vb 1 \& [% USE scalar %] \& \& # force it to use scalar context \& [% object.scalar.method %] \& \& # also works with subroutine references \& [% scalar.my_sub_ref %] .Ve .SS "String" .IX Subsection "String" The String plugin implements an object-oriented interface for manipulating strings. See Template::Plugin::String for further details. .PP .Vb 2 \& [% USE String \*(AqHello\*(Aq %] \& [% String.append(\*(Aq World\*(Aq) %] \& \& [% msg = String.new(\*(AqAnother string\*(Aq) %] \& [% msg.replace(\*(Aqstring\*(Aq, \*(Aqtext\*(Aq) %] \& \& The string "[% msg %]" is [% msg.length %] characters long. .Ve .SS "Table" .IX Subsection "Table" The Table plugin allows you to format a list of data items into a virtual table by specifying a fixed number of rows or columns, with an optional overlap. See Template::Plugin::Table for further details. .PP .Vb 1 \& [% USE table(list, rows=10, overlap=1) %] \& \& [% FOREACH item = table.col(3) %] \& [% item %] \& [% END %] .Ve .SS "\s-1URL\s0" .IX Subsection "URL" The \s-1URL\s0 plugin provides a simple way of constructing URLs from a base part and a variable set of parameters. See Template::Plugin::URL for further details. .PP .Vb 1 \& [% USE mycgi = url(\*(Aq/cgi\-bin/bar.pl\*(Aq, debug=1) %] \& \& [% mycgi %] \& # ==> /cgi/bin/bar.pl?debug=1 \& \& [% mycgi(mode=\*(Aqsubmit\*(Aq) %] \& # ==> /cgi/bin/bar.pl?mode=submit&debug=1 .Ve .SS "Wrap" .IX Subsection "Wrap" The Wrap plugin uses the Text::Wrap module to provide simple paragraph formatting. See Template::Plugin::Wrap and Text::Wrap for further details. .PP .Vb 3 \& [% USE wrap %] \& [% wrap(mytext, 40, \*(Aq* \*(Aq, \*(Aq \*(Aq) %] # use wrap sub \& [% mytext FILTER wrap(40) \-%] # or wrap FILTER .Ve .PP The \f(CW\*(C`Text::Wrap\*(C'\fR module is available from \s-1CPAN:\s0 .PP .Vb 1 \& http://www.cpan.org/modules/by\-module/Text/ .Ve .SS "\s-1XML\s0" .IX Subsection "XML" The \f(CW\*(C`XML::DOM\*(C'\fR, \f(CW\*(C`XML::RSS\*(C'\fR, \f(CW\*(C`XML::Simple\*(C'\fR and \f(CW\*(C`XML::XPath\*(C'\fR plugins are no longer distributed with the Template Toolkit as of version 2.15 .PP They are now available in a separate Template::XML distribution. PK � �[�t�s s man3/Template::Constants.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Constants 3" .TH Template::Constants 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Constants \- Defines constants for the Template Toolkit .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Constants qw( :status :error :all ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Constants\*(C'\fR modules defines, and optionally exports into the caller's namespace, a number of constants used by the Template package. .PP Constants may be used by specifying the \f(CW\*(C`Template::Constants\*(C'\fR package explicitly: .PP .Vb 2 \& use Template::Constants; \& print Template::Constants::STATUS_DECLINED; .Ve .PP Constants may be imported into the caller's namespace by naming them as options to the \f(CW\*(C`use Template::Constants\*(C'\fR statement: .PP .Vb 2 \& use Template::Constants qw( STATUS_DECLINED ); \& print STATUS_DECLINED; .Ve .PP Alternatively, one of the following tagset identifiers may be specified to import sets of constants: '\f(CW\*(C`:status\*(C'\fR', '\f(CW\*(C`:error\*(C'\fR', '\f(CW\*(C`:all\*(C'\fR'. .PP .Vb 2 \& use Template::Constants qw( :status ); \& print STATUS_DECLINED; .Ve .PP Consult the documentation for the \f(CW\*(C`Exporter\*(C'\fR module for more information on exporting variables. .SH "EXPORTABLE TAG SETS" .IX Header "EXPORTABLE TAG SETS" The following tag sets and associated constants are defined: .PP .Vb 7 \& :status \& STATUS_OK # no problem, continue \& STATUS_RETURN # ended current block then continue (ok) \& STATUS_STOP # controlled stop (ok) \& STATUS_DONE # iterator is all done (ok) \& STATUS_DECLINED # provider declined to service request (ok) \& STATUS_ERROR # general error condition (not ok) \& \& :error \& ERROR_RETURN # return a status code (e.g. \*(Aqstop\*(Aq) \& ERROR_FILE # file error: I/O, parse, recursion \& ERROR_UNDEF # undefined variable value used \& ERROR_PERL # error in [% PERL %] block \& ERROR_FILTER # filter error \& ERROR_PLUGIN # plugin error \& \& :chomp # for PRE_CHOMP and POST_CHOMP \& CHOMP_NONE # do not remove whitespace \& CHOMP_ONE # remove whitespace to newline \& CHOMP_ALL # old name for CHOMP_ONE (deprecated) \& CHOMP_COLLAPSE # collapse whitespace to a single space \& CHOMP_GREEDY # remove all whitespace including newlines \& \& :debug \& DEBUG_OFF # do nothing \& DEBUG_ON # basic debugging flag \& DEBUG_UNDEF # throw undef on undefined variables \& DEBUG_VARS # general variable debugging \& DEBUG_DIRS # directive debugging \& DEBUG_STASH # general stash debugging \& DEBUG_CONTEXT # context debugging \& DEBUG_PARSER # parser debugging \& DEBUG_PROVIDER # provider debugging \& DEBUG_PLUGINS # plugins debugging \& DEBUG_FILTERS # filters debugging \& DEBUG_SERVICE # context debugging \& DEBUG_ALL # everything \& DEBUG_CALLER # add caller file/line info \& DEBUG_FLAGS # bitmap used internally \& \& :all \& All the above constants. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, \f(CW\*(C`Exporter\*(C'\fR PK � �[�Cs�^ ^ " man3/Template::Manual::Credits.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Credits 3" .TH Template::Manual::Credits 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Credits \- Author and contributor credits .SH "HISTORY" .IX Header "HISTORY" The Template Toolkit began its life as the \f(CW\*(C`Text::MetaText\*(C'\fR module, originally released to \s-1CPAN\s0 around 1996. This itself was the public manifestation of an earlier template processing system I developed while working at Peritas (now Knowledge Pool \- http://www.knowledgepool.com/) .PP \&\f(CW\*(C`Text::MetaText\*(C'\fR was the prototype \- the one we always planned to throw away. It did the job well, showing us what worked and what didn't, what was good and what was bad, and gave us some ideas about what could be done better, given the chance to start again from scratch. .PP Some time late in 1998 I threw away the prototype and started work on the Template Toolkit. By then I was working at Canon Research Centre Europe Ltd. (\s-1CRE\s0), involved in a general research programme related to web publishing and dynamic content generation. The first alpha release was in June 1999, followed by numerous more alpha and beta releases culminating in 1.00 being released on 2nd December 1999. .PP A month or so later, work had begun on version 2.00. The plan was to get the template language relatively stable in version 1.00 and not worry too much about performance or other internal matters. Then, version 2.00 would follow to improve performance, clean up the architecture and fix anything that, with the benefit of hindsight, we thought could be improved. As it happens, me starting work on version 2.00 coincided with Doug Steinwand sending me his parser variant which compiled templates to Perl code, giving a major performance boost. As well as the speedups, there are a whole host of significant new features in version 2.00, and a greatly improved internal architecture. Apart from a few minor \*(L"fixups\*(R" the template directives and language have remained the same as in version 1.00 .PP Version 2.00 was available in beta release form in July 2000, just in time for the 4th Perl Conference where version 1.00 was awarded \*(L"Best New Perl Module\*(R". After another extended beta release period, version 2.00 was released on 1st December 2000. .PP Version 3 has been in development ever since. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2020 Andy Wardley. All Rights Reserved. .PP The Template Toolkit is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Many people have contributed ideas, inspiration, fixes and features to the Template Toolkit. Their efforts continue to be very much appreciated. Please let me know if you think anyone is missing from this list. .PP If you submit a patch/pull request then please make sure you add your own name to this list and include it in the changes. .PP Adam Kennedy, ahollandECS, Alexey A. Kiritchun, Amiri Barksdale, Andreas Koenig, Andy Wardley, Autrijus Tang, Axel Gerstmair, Barrie Slaymaker, Ben Tilly, Breno G. de Oliveira, Briac Pilpré, Brian Fraser, Brian Wightman, Bryce Harrington, Chris Dean, Chris Winters, Christian, chromatic, Colin Johnson, Colin Keith, Craig Barratt, Darren Chamberlain, Dave Cash, Dave Cross, Dave Hodgkinson, Dave Howorth, Dave Jacoby, David Steinbrunner, Denis F. Latypoff, Dennis Clark, Doug, Drew Taylor, Dylan, E. Choroba, eadjei, Eric Cholet, Francois Desarmenien, François Andriot, fREW Schmidt, gordon-fish, Guido Flohr, Hans von Lengerke, Harald Joerg, Horst Dumcke, Ivan Krylov, Ivan Kurmanov, Jacques Germishuys, Jason Lewis, Jay Hannah, Jens Rehsack, Jess Robinson, Jim Vaughan, John Lightsey, John Napiorkowski, Jon Jensen, Jonas Liljegren, Jonathon Padfield, José Joaquín Atria, Jose Luis Martinez, Josh Rosenbaum, Kenny Gatdula, Kent Fredric, Kevin M. Goess, Koenig, Leon Brocard, Leslie Michael Orchard, Lubomir, Lyle Brooks, Marc Remy, Mark Fowler, Martin, Matthew Somerville, Michael Fowler, Michael Stevens, Mike Schilli, Mikhail Klyuchnikov from Positive Technologies, nataraj, Neil Bowers, Nick Hibma, Nicolas R, Nik Clayton, Norbert Buchmüller, Paul Orrock, Paul Seamons, Paul Sharpe, Perrin Harkins, Philippe Bruhat (BooK), Piers Cawley, Portman, Rafael Kitover, Randal L. Schwartz, Ricardo Signes, Richard Tietjen, Robin Berjon, Rod Taylor, Schaffner, sdeseille, Sean McAfee, Sean Zellmer, Simon, Simon Dawson, Simon Matthews, Simon Napiorkowski, Slaven Rezic, Smylers, Stas Bekman, Stathy G. Touloumis, stefano-b, Steinwand, Steve Peters, Swen, Thierry-Michel Barral, Thuemmler, Timmy Chan, Todd Rinaldo, Tom Delmas, Tony Bowden, Tosh Cooey, Ville Skyttä, Vivek Khera, Wilcox, William Hardison, Yanick Champoux, Yuri Pimenov. PK � �[��>�n n # man3/Template::Plugin::Datafile.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Datafile 3" .TH Template::Plugin::Datafile 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Datafile \- Plugin to construct records from a simple data file .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& [% USE mydata = datafile(\*(Aq/path/to/datafile\*(Aq) %] \& [% USE mydata = datafile(\*(Aq/path/to/datafile\*(Aq, delim = \*(Aq|\*(Aq) %] \& [% USE mydata = datafile(\*(Aq/path/to/datafile\*(Aq, encoding = \*(AqUTF\-8\*(Aq) %] \& \& [% FOREACH record = mydata %] \& [% record.this %] [% record.that %] \& [% END %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin provides a simple facility to construct a list of hash references, each of which represents a data record of known structure, from a data file. .PP .Vb 1 \& [% USE datafile(filename) %] .Ve .PP A absolute filename must be specified (for this initial implementation at least \- in a future version it might also use the \f(CW\*(C`INCLUDE_PATH\*(C'\fR). An optional \f(CW\*(C`delim\*(C'\fR parameter may also be provided to specify an alternate delimiter character. The optional \f(CW\*(C`encoding\*(C'\fR parameter may be used to specify the input file encoding. .PP .Vb 2 \& [% USE userlist = datafile(\*(Aq/path/to/file/users\*(Aq) %] \& [% USE things = datafile(\*(Aqitems\*(Aq, delim = \*(Aq|\*(Aq) %] .Ve .PP The format of the file is intentionally simple. The first line defines the field names, delimited by colons with optional surrounding whitespace. Subsequent lines then defines records containing data items, also delimited by colons. e.g. .PP .Vb 3 \& id : name : email : tel \& abw : Andy Wardley : abw@tt2.org : 555\-1234 \& sam : Simon Matthews : sam@tt2.org : 555\-9876 .Ve .PP Each line is read, split into composite fields, and then used to initialise a hash array containing the field names as relevant keys. The plugin returns a blessed list reference containing the hash references in the order as defined in the file. .PP .Vb 3 \& [% FOREACH user = userlist %] \& [% user.id %]: [% user.name %] \& [% END %] .Ve .PP The first line of the file \fBmust\fR contain the field definitions. After the first line, blank lines will be ignored, along with comment line which start with a '\f(CW\*(C`#\*(C'\fR'. .SH "BUGS" .IX Header "BUGS" Should handle file names relative to \f(CW\*(C`INCLUDE_PATH\*(C'\fR. Doesn't permit use of '\f(CW\*(C`:\*(C'\fR' in a field. Some escaping mechanism is required. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[+��h�' �' $ man3/Template::Plugin::Directory.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Directory 3" .TH Template::Plugin::Directory 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Directory \- Plugin for generating directory listings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE dir = Directory(dirpath) %] \& \& # files returns list of regular files \& [% FOREACH file = dir.files %] \& [% file.name %] [% file.path %] ... \& [% END %] \& \& # dirs returns list of sub\-directories \& [% FOREACH subdir = dir.dirs %] \& [% subdir.name %] [% subdir.path %] ... \& [% END %] \& \& # list returns both interleaved in order \& [% FOREACH item = dir.list %] \& [% IF item.isdir %] \& Directory: [% item.name %] \& [% ELSE %] \& File: [% item.name %] \& [% END %] \& [% END %] \& \& # define a VIEW to display dirs/files \& [% VIEW myview %] \& [% BLOCK file %] \& File: [% item.name %] \& [% END %] \& \& [% BLOCK directory %] \& Directory: [% item.name %] \& [% item.content(myview) | indent \-%] \& [% END %] \& [% END %] \& \& # display directory content using view \& [% myview.print(dir) %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This Template Toolkit plugin provides a simple interface to directory listings. It is derived from the Template::Plugin::File module and uses Template::Plugin::File object instances to represent files within a directory. Sub-directories within a directory are represented by further \f(CW\*(C`Template::Plugin::Directory\*(C'\fR instances. .PP The constructor expects a directory name as an argument. .PP .Vb 1 \& [% USE dir = Directory(\*(Aq/tmp\*(Aq) %] .Ve .PP It then provides access to the files and sub-directories contained within the directory. .PP .Vb 4 \& # regular files (not directories) \& [% FOREACH file IN dir.files %] \& [% file.name %] \& [% END %] \& \& # directories only \& [% FOREACH file IN dir.dirs %] \& [% file.name %] \& [% END %] \& \& # files and/or directories \& [% FOREACH file IN dir.list %] \& [% file.name %] ([% file.isdir ? \*(Aqdirectory\*(Aq : \*(Aqfile\*(Aq %]) \& [% END %] .Ve .PP The plugin constructor will throw a \f(CW\*(C`Directory\*(C'\fR error if the specified path does not exist, is not a directory or fails to \f(CW\*(C`stat()\*(C'\fR (see Template::Plugin::File). Otherwise, it will scan the directory and create lists named '\f(CW\*(C`files\*(C'\fR' containing files, '\f(CW\*(C`dirs\*(C'\fR' containing directories and '\f(CW\*(C`list\*(C'\fR' containing both files and directories combined. The \f(CW\*(C`nostat\*(C'\fR option can be set to disable all file/directory checks and directory scanning. .PP Each file in the directory will be represented by a Template::Plugin::File object instance, and each directory by another \&\f(CW\*(C`Template::Plugin::Directory\*(C'\fR. If the \f(CW\*(C`recurse\*(C'\fR flag is set, then those directories will contain further nested entries, and so on. With the \&\f(CW\*(C`recurse\*(C'\fR flag unset, as it is by default, then each is just a place marker for the directory and does not contain any further content unless its \f(CW\*(C`scan()\*(C'\fR method is explicitly called. The \f(CW\*(C`isdir\*(C'\fR flag can be tested against files and/or directories, returning true if the item is a directory or false if it is a regular file. .PP .Vb 7 \& [% FOREACH file = dir.list %] \& [% IF file.isdir %] \& * Directory: [% file.name %] \& [% ELSE %] \& * File: [% file.name %] \& [% END %] \& [% END %] .Ve .PP This example shows how you might walk down a directory tree, displaying content as you go. With the recurse flag disabled, as is the default, we need to explicitly call the \f(CW\*(C`scan()\*(C'\fR method on each directory, to force it to lookup files and further sub-directories contained within. .PP .Vb 3 \& [% USE dir = Directory(dirpath) %] \& * [% dir.path %] \& [% INCLUDE showdir %] \& \& [% BLOCK showdir \-%] \& [% FOREACH file = dir.list \-%] \& [% IF file.isdir \-%] \& * [% file.name %] \& [% file.scan \-%] \& [% INCLUDE showdir dir=file FILTER indent(4) \-%] \& [% ELSE \-%] \& \- [% f.name %] \& [% END \-%] \& [% END \-%] \& [% END %] .Ve .PP This example is adapted (with some re-formatting for clarity) from a test in \fIt/directry.t\fR which produces the following output: .PP .Vb 10 \& * test/dir \& \- file1 \& \- file2 \& * sub_one \& \- bar \& \- foo \& * sub_two \& \- waz.html \& \- wiz.html \& \- xyzfile .Ve .PP The \f(CW\*(C`recurse\*(C'\fR flag can be set (disabled by default) to cause the constructor to automatically recurse down into all sub-directories, creating a new \f(CW\*(C`Template::Plugin::Directory\*(C'\fR object for each one and filling it with any further content. In this case there is no need to explicitly call the \f(CW\*(C`scan()\*(C'\fR method. .PP .Vb 2 \& [% USE dir = Directory(dirpath, recurse=1) %] \& ... \& \& [% IF file.isdir \-%] \& * [% file.name %] \& [% INCLUDE showdir dir=file FILTER indent(4) \-%] \& [% ELSE \-%] \& ... .Ve .PP The directory plugin also provides support for views. A view can be defined as a \f(CW\*(C`VIEW ... END\*(C'\fR block and should contain \f(CW\*(C`BLOCK\*(C'\fR definitions for files ('\f(CW\*(C`file\*(C'\fR') and directories ('\f(CW\*(C`directory\*(C'\fR'). .PP .Vb 4 \& [% VIEW myview %] \& [% BLOCK file %] \& \- [% item.name %] \& [% END %] \& \& [% BLOCK directory %] \& * [% item.name %] \& [% item.content(myview) FILTER indent %] \& [% END %] \& [% END %] .Ve .PP The view \f(CW\*(C`print()\*(C'\fR method can then be called, passing the \&\f(CW\*(C`Directory\*(C'\fR object as an argument. .PP .Vb 2 \& [% USE dir = Directory(dirpath, recurse=1) %] \& [% myview.print(dir) %] .Ve .PP When a directory is presented to a view, either as \f(CW\*(C`[% myview.print(dir) %]\*(C'\fR or \f(CW\*(C`[% dir.present(view) %]\*(C'\fR, then the \f(CW\*(C`directory\*(C'\fR \f(CW\*(C`BLOCK\*(C'\fR within the \&\f(CW\*(C`myview\*(C'\fR \f(CW\*(C`VIEW\*(C'\fR is processed. The \f(CW\*(C`item\*(C'\fR variable will be set to alias the \&\f(CW\*(C`Directory\*(C'\fR object. .PP .Vb 4 \& [% BLOCK directory %] \& * [% item.name %] \& [% item.content(myview) FILTER indent %] \& [% END %] .Ve .PP In this example, the directory name is first printed and the content(view) method is then called to present each item within the directory to the view. Further directories will be mapped to the \f(CW\*(C`directory\*(C'\fR block, and files will be mapped to the \f(CW\*(C`file\*(C'\fR block. .PP With the recurse option disabled, as it is by default, the \f(CW\*(C`directory\*(C'\fR block should explicitly call a \f(CW\*(C`scan()\*(C'\fR on each directory. .PP .Vb 4 \& [% VIEW myview %] \& [% BLOCK file %] \& \- [% item.name %] \& [% END %] \& \& [% BLOCK directory %] \& * [% item.name %] \& [% item.scan %] \& [% item.content(myview) FILTER indent %] \& [% END %] \& [% END %] \& \& [% USE dir = Directory(dirpath) %] \& [% myview.print(dir) %] .Ve .SH "AUTHORS" .IX Header "AUTHORS" Michael Stevens wrote the original Directory plugin on which this is based. Andy Wardley split it into separate File and Directory plugins, added some extra code and documentation for \f(CW\*(C`VIEW\*(C'\fR support, and made a few other minor tweaks. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2000\-2022 Michael Stevens, Andy Wardley. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Template::Plugin::File, Template::View PK � �[���/ �/ man3/Template::Manual::Intro.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Intro 3" .TH Template::Manual::Intro 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Intro \- Introduction to the Template Toolkit .SH "Introduction" .IX Header "Introduction" The Template Toolkit is a collection of Perl modules which implement a fast, flexible, powerful and extensible template processing system. It is most often used for generating dynamic web content, although it can be used equally well for processing any kind of text documents. .PP At the simplest level it provides an easy way to process template files, filling in embedded variable references with their equivalent values. Here's an example of a template. .PP .Vb 1 \& Dear [% name %], \& \& It has come to our attention that your account is in \& arrears to the sum of [% debt %]. \& \& Please settle your account before [% deadline %] or we \& will be forced to revoke your Licence to Thrill. \& \& The Management. .Ve .PP By default, template directives are embedded within the character sequences \f(CW\*(C`[%\*(C'\fR ... \f(CW\*(C`%]\*(C'\fR but you can change these and various other options to configure how the Template Toolkit looks, feels and works. You can set the \f(CW\*(C`INTERPOLATE\*(C'\fR option, for example, if you prefer to embed your variables in Perl style: .PP .Vb 1 \& Dear $name, \& \& It has come to our attention that your account is in \& arrears to the sum of $debt. \& \& ...etc... .Ve .SH "The Template Perl Module" .IX Header "The Template Perl Module" The Template Perl module is the front end to the Template Toolkit for Perl programmers, providing access to the full range of functionality through a single module with a simple interface. It loads the other modules as required and instantiates a default set of objects to handle subsequent template processing requests. Configuration parameters may be passed to the Template constructor method, \fBnew()\fR, which are then used to configure the generate object. .PP .Vb 1 \& use Template; \& \& my $tt = Template\->new({ \& INCLUDE_PATH => \*(Aq/usr/local/templates\*(Aq, \& INTERPOLATE => 1, \& }) || die "$Template::ERROR\en"; .Ve .PP The Template object implements a \fBprocess()\fR method for processing template files or text. The name of the input template (or various other sources) is passed as the first argument, followed by a reference to a hash array of variable definitions for substitution in the template. .PP .Vb 5 \& my $vars = { \& name => \*(AqCount Edward van Halen\*(Aq, \& debt => \*(Aq3 riffs and a solo\*(Aq, \& deadline => \*(Aqthe next chorus\*(Aq, \& }; \& \& $tt\->process(\*(Aqletters/overdrawn\*(Aq, $vars) \& || die $tt\->error(), "\en"; .Ve .PP The \fBprocess()\fR method returns a true value (\f(CW1\fR) on success and prints the template output to \f(CW\*(C`STDOUT\*(C'\fR, by default. On error, the \&\fBprocess()\fR method returns a false value (\f(CW\*(C`undef\*(C'\fR). The \fBerror()\fR method can then be called to retrieve details of the error. .SH "Component Based Content Construction" .IX Header "Component Based Content Construction" A number of special directives are provided, such as \f(CW\*(C`INSERT\*(C'\fR, \f(CW\*(C`INCLUDE\*(C'\fR and \&\f(CW\*(C`PROCESS\*(C'\fR, which allow content to be built up from smaller template components. This permits a modular approach to building a web site or other content repository, promoting reusability, cross-site consistency, ease of construction and subsequent maintenance. Common elements such as headers, footers, menu bars, tables, and so on, can be created as separate template files which can then be processed into other documents as required. All defined variables are inherited by these templates along with any additional \&\*(L"local\*(R" values specified. .PP .Vb 3 \& [% PROCESS header \& title = "The Cat Sat on the Mat" \& %] \& \& [% PROCESS menu %] \& \& The location of the missing feline has now been established. \& Thank you for your assistance. \& \& [% INSERT legal/disclaimer %] \& \& [% PROCESS footer %] .Ve .PP You can also define a template as a \s-1BLOCK\s0 within the same file and \&\s-1PROCESS\s0 it just like any other template file. This can be invaluable for building up repetitive elements such as tables, menus, etc. .PP .Vb 3 \& [% BLOCK tabrow %] \& <tr><td>[% name %]</td><td>[% email %]</td></tr> \& [% END %] \& \& <table> \& [% PROCESS tabrow name="tom" email="tom@here.org" %] \& [% PROCESS tabrow name="dick" email="disk@there.org" %] \& [% PROCESS tabrow name="larry" email="larry@where.org" %] \& </table> .Ve .SH "Data and Code Binding" .IX Header "Data and Code Binding" One of the key features that sets the Template Toolkit apart from other template processors is the ability to bind template variables to any kind of Perl data: scalars, lists, hash arrays, sub-routines and objects. .PP .Vb 10 \& my $vars = { \& root => \*(Aqhttp://here.com/there\*(Aq, \& menu => [ \*(Aqmodules\*(Aq, \*(Aqauthors\*(Aq, \*(Aqscripts\*(Aq ], \& client => { \& name => \*(AqDoctor Joseph von Satriani\*(Aq, \& id => \*(AqJVSAT\*(Aq, \& }, \& checkout => sub { my $total = shift; ...; return $something }, \& shopcart => My::Cool::Shopping::Cart\->new(), \& }; .Ve .PP The Template Toolkit will automatically Do The Right Thing to access the data in an appropriate manner to return some value which can then be output. The dot operator '\f(CW\*(C`.\*(C'\fR' is used to access into lists and hashes or to call object methods. The \f(CW\*(C`FOREACH\*(C'\fR directive is provided for iterating through lists, and various logical tests are available using directives such as \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR, \&\f(CW\*(C`ELSIF\*(C'\fR, \f(CW\*(C`ELSE\*(C'\fR, \f(CW\*(C`SWITCH\*(C'\fR, \f(CW\*(C`CASE\*(C'\fR, etc. .PP .Vb 3 \& [% FOREACH section = menu %] \& <a href="[% root %]/[% section %]/index.html">[% section %]</a> \& [% END %] \& \& <b>Client</b>: [% client.name %] (id: [% client.id %]) \& \& [% IF shopcart.nitems %] \& Your shopping cart contains the following items: \& <ul> \& [% FOREACH item = shopcart.contents %] \& <li>[% item.name %] : [% item.qty %] @ [% item.price %] \& [% END %] \& </ul> \& \& [% checkout(shopcart.total) %] \& \& [% ELSE %] \& No items currently in shopping cart. \& [% END %] .Ve .SH "Advanced Features: Filters, Macros, Exceptions, Plugins" .IX Header "Advanced Features: Filters, Macros, Exceptions, Plugins" The Template Toolkit also provides a number of additional directives for advanced processing and programmatical functionality. It supports output filters (\s-1FILTER\s0), allows custom macros to be defined (\s-1MACRO\s0), has a fully-featured exception handling system (\s-1TRY, THROW, CATCH, FINAL\s0) and supports a plugin architecture (\s-1USE\s0) which allows special plugin modules and even regular Perl modules to be loaded and used with the minimum of fuss. The Template Toolkit is \*(L"just\*(R" a template processor but you can trivially extend it to incorporate the functionality of any Perl module you can get your hands on. Thus, it is also a scalable and extensible template framework, ideally suited for managing the presentation layer for application servers, content management systems and other web applications. .SH "Separating Presentation and Application Logic" .IX Header "Separating Presentation and Application Logic" Rather than embedding Perl code or some other scripting language directly into template documents, it encourages you to keep functional components (i.e. Perl code) separate from presentation components (e.g. \s-1HTML\s0 templates). The template variables provide the interface between the two layers, allowing data to be generated in code and then passed to a template component for displaying (pipeline model) or for sub-routine or object references to be bound to variables which can then be called from the template as and when required (callback model). .PP The directives that the Template Toolkit provide implement their own mini programming language, but they're not really designed for serious, general purpose programming. Perl is a far more appropriate language for that. If you embed application logic (e.g. Perl or other scripting language fragments) in \s-1HTML\s0 templates then you risk losing the clear separation of concerns between functionality and presentation. It becomes harder to maintain the two elements in isolation and more difficult, if not impossible, to reuse code or presentation elements by themselves. It is far better to write your application code in separate Perl modules, libraries or scripts and then use templates to control how the resulting data is presented as output. Thus you should think of the Template Toolkit language as a set of layout directives for displaying data, not calculating it. .PP Having said that, the Template Toolkit doesn't force you into one approach or the other. It attempts to be pragmatic rather than dogmatic in allowing you to do whatever best gets the job done. Thus, if you enable the \s-1EVAL_PERL\s0 option then you can happily embed real Perl code in your templates within \s-1PERL ... END\s0 directives. .SH "Performance" .IX Header "Performance" The Template Toolkit uses a fast YACC-like parser which compiles templates into Perl code for maximum runtime efficiency. It also has an advanced caching mechanism which manages in-memory and on-disk (i.e. persistent) versions of compiled templates. The modules that comprise the toolkit are highly configurable and the architecture around which they're built is designed to be extensible. The Template Toolkit provides a powerful framework around which content creation and delivery systems can be built while also providing a simple interface through the Template front-end module for general use. PK � �[���;� � man3/Template::Tools::tpage.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Tools::tpage 3" .TH Template::Tools::tpage 3 "2019-12-23" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tools::tpage \- Process templates from command line .SH "USAGE" .IX Header "USAGE" .Vb 1 \& tpage [ \-\-define var=value ] file(s) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBtpage\fR script is a simple wrapper around the Template Toolkit processor. Files specified by name on the command line are processed in turn by the template processor and the resulting output is sent to \s-1STDOUT\s0 and can be redirected accordingly. e.g. .PP .Vb 2 \& tpage myfile > myfile.out \& tpage header myfile footer > myfile.html .Ve .PP If no file names are specified on the command line then \fBtpage\fR will read \&\s-1STDIN\s0 for input. .PP The \f(CW\*(C`\-\-define\*(C'\fR option can be used to set the values of template variables. e.g. .PP .Vb 1 \& tpage \-\-define author="Andy Wardley" skeleton.pm > MyModule.pm .Ve .SS "The \fI.tpagerc\fP Configuration File" .IX Subsection "The .tpagerc Configuration File" You can use a \fI.tpagerc\fR file in your home directory. .PP The purpose of this file is to set any \fIglobal\fR configuration options that you want applied \fIevery\fR time \fItpage\fR is run. For example, you can use the \f(CW\*(C`include_path\*(C'\fR to use template files from a generic template directory. .PP Run \f(CW\*(C`tpage \-h\*(C'\fR for a summary of the options available. .PP See Template for general information about the Perl Template Toolkit and the template language and features. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2008 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" ttree PK � �[��|�' �' man3/Template::Plugin::Image.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Image 3" .TH Template::Plugin::Image 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Image \- Plugin access to image sizes .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 6 \& [% USE Image(filename) %] \& [% Image.width %] \& [% Image.height %] \& [% Image.size.join(\*(Aq, \*(Aq) %] \& [% Image.attr %] \& [% Image.tag %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin provides an interface to the Image::Info or Image::Size modules for determining the size of image files. .PP You can specify the plugin name as either '\f(CW\*(C`Image\*(C'\fR' or '\f(CW\*(C`image\*(C'\fR'. The plugin object created will then have the same name. The file name of the image should be specified as a positional or named argument. .PP .Vb 6 \& [% # all these are valid, take your pick %] \& [% USE Image(\*(Aqfoo.gif\*(Aq) %] \& [% USE image(\*(Aqbar.gif\*(Aq) %] \& [% USE Image \*(Aqping.gif\*(Aq %] \& [% USE image(name=\*(Aqbaz.gif\*(Aq) %] \& [% USE Image name=\*(Aqpong.gif\*(Aq %] .Ve .PP A \f(CW\*(C`root\*(C'\fR parameter can be used to specify the location of the image file: .PP .Vb 3 \& [% USE Image(root=\*(Aq/path/to/root\*(Aq, name=\*(Aqimages/home.png\*(Aq) %] \& # image path: /path/to/root/images/home.png \& # img src: images/home.png .Ve .PP In cases where the image path and image url do not match up, specify the file name directly: .PP .Vb 1 \& [% USE Image(file=\*(Aq/path/to/home.png\*(Aq, name=\*(Aq/images/home.png\*(Aq) %] .Ve .PP The \f(CW\*(C`alt\*(C'\fR parameter can be used to specify an alternate name for the image, for use in constructing an \s-1XHTML\s0 element (see the \f(CW\*(C`tag()\*(C'\fR method below). .PP .Vb 1 \& [% USE Image(\*(Aqhome.png\*(Aq, alt="Home") %] .Ve .PP You can also provide an alternate name for an \f(CW\*(C`Image\*(C'\fR plugin object. .PP .Vb 2 \& [% USE img1 = image \*(Aqfoo.gif\*(Aq %] \& [% USE img2 = image \*(Aqbar.gif\*(Aq %] .Ve .PP The \f(CW\*(C`name\*(C'\fR method returns the image file name. .PP .Vb 1 \& [% img1.name %] # foo.gif .Ve .PP The \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`height\*(C'\fR methods return the width and height of the image, respectively. The \f(CW\*(C`size\*(C'\fR method returns a reference to a 2 element list containing the width and height. .PP .Vb 4 \& [% USE image \*(Aqfoo.gif\*(Aq %] \& width: [% image.width %] \& height: [% image.height %] \& size: [% image.size.join(\*(Aq, \*(Aq) %] .Ve .PP The \f(CW\*(C`modtime\*(C'\fR method returns the modification time of the file in question, suitable for use with the Date plugin, for example: .PP .Vb 3 \& [% USE image \*(Aqfoo.gif\*(Aq %] \& [% USE date %] \& [% date.format(image.modtime, "%B, %e %Y") %] .Ve .PP The \f(CW\*(C`attr\*(C'\fR method returns the height and width as \s-1HTML/XML\s0 attributes. .PP .Vb 2 \& [% USE image \*(Aqfoo.gif\*(Aq %] \& [% image.attr %] .Ve .PP Typical output: .PP .Vb 1 \& width="60" height="20" .Ve .PP The \f(CW\*(C`tag\*(C'\fR method returns a complete \s-1XHTML\s0 tag referencing the image. .PP .Vb 2 \& [% USE image \*(Aqfoo.gif\*(Aq %] \& [% image.tag %] .Ve .PP Typical output: .PP .Vb 1 \& <img src="foo.gif" width="60" height="20" alt="" /> .Ve .PP You can provide any additional attributes that should be added to the \&\s-1XHTML\s0 tag. .PP .Vb 2 \& [% USE image \*(Aqfoo.gif\*(Aq %] \& [% image.tag(class="logo" alt="Logo") %] .Ve .PP Typical output: .PP .Vb 1 \& <img src="foo.gif" width="60" height="20" alt="Logo" class="logo" /> .Ve .PP Note that the \f(CW\*(C`alt\*(C'\fR attribute is mandatory in a strict \s-1XHTML\s0 \f(CW\*(C`img\*(C'\fR element (even if it's empty) so it is always added even if you don't explicitly provide a value for it. You can do so as an argument to the \f(CW\*(C`tag\*(C'\fR method, as shown in the previous example, or as an argument .PP .Vb 1 \& [% USE image(\*(Aqfoo.gif\*(Aq, alt=\*(AqLogo\*(Aq) %] .Ve .SH "CATCHING ERRORS" .IX Header "CATCHING ERRORS" If the image file cannot be found then the above methods will throw an \&\f(CW\*(C`Image\*(C'\fR error. You can enclose calls to these methods in a \&\f(CW\*(C`TRY...CATCH\*(C'\fR block to catch any potential errors. .PP .Vb 6 \& [% TRY; \& image.width; \& CATCH; \& error; # print error \& END \& %] .Ve .SH "USING Image::Info" .IX Header "USING Image::Info" At run time, the plugin tries to load Image::Info in preference to Image::Size. If Image::Info is found, then some additional methods are available, in addition to \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`width\*(C'\fR, \f(CW\*(C`height\*(C'\fR, \f(CW\*(C`attr\*(C'\fR, and \f(CW\*(C`tag\*(C'\fR. These additional methods are named after the elements that Image::Info retrieves from the image itself. The types of methods available depend on the type of image (see Image::Info for more details). These additional methods will always include the following: .SS "file_media_type" .IX Subsection "file_media_type" This is the \s-1MIME\s0 type that is appropriate for the given file format. The corresponding value is a string like: "\f(CW\*(C`image/png\*(C'\fR\*(L" or \*(R"\f(CW\*(C`image/jpeg\*(C'\fR". .SS "file_ext" .IX Subsection "file_ext" The is the suggested file name extension for a file of the given file format. The value is a 3 letter, lowercase string like "\f(CW\*(C`png\*(C'\fR\*(L", \*(R"\f(CW\*(C`jpg\*(C'\fR". .SS "color_type" .IX Subsection "color_type" The value is a short string describing what kind of values the pixels encode. The value can be one of the following: .PP .Vb 7 \& Gray \& GrayA \& RGB \& RGBA \& CMYK \& YCbCr \& CIELab .Ve .PP These names can also be prefixed by "\f(CW\*(C`Indexed\-\*(C'\fR\*(L" if the image is composed of indexes into a palette. Of these, only \*(R"\f(CW\*(C`Indexed\-RGB\*(C'\fR" is likely to occur. .PP (It is similar to the \s-1TIFF\s0 field PhotometricInterpretation, but this name was found to be too long, so we used the \s-1PNG\s0 inspired term instead.) .SS "resolution" .IX Subsection "resolution" The value of this field normally gives the physical size of the image on screen or paper. When the unit specifier is missing then this field denotes the squareness of pixels in the image. .PP The syntax of this field is: .PP .Vb 3 \& <res> <unit> \& <xres> "/" <yres> <unit> \& <xres> "/" <yres> .Ve .PP The \f(CW\*(C`<res>\*(C'\fR, \f(CW\*(C`<xres>\*(C'\fR and \f(CW\*(C`<yres>\*(C'\fR fields are numbers. The \f(CW\*(C`<unit>\*(C'\fR is a string like \f(CW\*(C`dpi\*(C'\fR, \f(CW\*(C`dpm\*(C'\fR or \&\f(CW\*(C`dpcm\*(C'\fR (denoting "dots per inch/cm/meter). .SS "SamplesPerPixel" .IX Subsection "SamplesPerPixel" This says how many channels there are in the image. For some image formats this number might be higher than the number implied from the \&\f(CW\*(C`color_type\*(C'\fR. .SS "BitsPerSample" .IX Subsection "BitsPerSample" This says how many bits are used to encode each of samples. The value is a reference to an array containing numbers. The number of elements in the array should be the same as \f(CW\*(C`SamplesPerPixel\*(C'\fR. .SS "Comment" .IX Subsection "Comment" Textual comments found in the file. The value is a reference to an array if there are multiple comments found. .SS "Interlace" .IX Subsection "Interlace" If the image is interlaced, then this returns the interlace type. .SS "Compression" .IX Subsection "Compression" This returns the name of the compression algorithm is used. .SS "Gamma" .IX Subsection "Gamma" A number indicating the gamma curve of the image (e.g. 2.2) .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Image::Info PK � �[� �b� � man3/Template::Toolkit.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Toolkit 3" .TH Template::Toolkit 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Toolkit \- Template Processing System .SH "Introduction" .IX Header "Introduction" The Template Toolkit is a collection of Perl modules which implement a fast, flexible, powerful and extensible template processing system. .PP It is \*(L"input-agnostic\*(R" and can be used equally well for processing any kind of text documents: \s-1HTML, XML, CSS,\s0 Javascript, Perl code, plain text, and so on. However, it is most often used for generating static and dynamic web content, so that's what we'll focus on here. .PP Although the Template Toolkit is written in Perl, you don't need to be a Perl programmer to use it. It was designed to allow non-programmers to easily create and maintain template-based web sites without having to mess around writing Perl code or going crazy with cut-n-paste. .PP However, the Template Toolkit is also designed to be extremely flexible and extensible. If you are a Perl programmer, or know someone who is, then you can easily hook the Template Toolkit into your existing code, data, databases and web applications. Furthermore, you can easily extend the Template Toolkit through the use of its plugin mechanism and other developer APIs. .PP Whatever context you use it in, the primary purpose of the Template Toolkit is to allow you to create a clear separation between the presentation elements of your web site and everything else. .PP If you're generating static web pages, then you can use it to separate the commonly repeated user interface elements on each page (headers, menus, footers, etc.) from the core content. If you're generating dynamic web pages for the front end of a web application, then you'll also be using it to keep the back-end Perl code entirely separate from the front-end \s-1HTML\s0 templates. Either way, a \fIclear separation of concerns\fR is what allow you to concentrate on one thing at a time without the other things getting in your way. And that's what the Template Toolkit is all about. .SH "Documentation" .IX Header "Documentation" The documentation for the Template Toolkit is organised into five sections. .PP The Template::Manual contains detailed information about using the Template Toolkit. It gives examples of its use and includes a full reference of the template language, configuration options, filters, plugins and other component parts. .PP The Template::Modules page lists the Perl modules that comprise the Template Toolkit. It gives a brief explanation of what each of them does, and provides a link to the complete documentation for each module for further information. If you're a Perl programmer looking to use the Template Toolkit from your Perl programs then this section is likely to be of interest. .PP Most, if not all of the information you need to call the Template Toolkit from Perl is in the documentation for the Template module. You only really need to start thinking about the other modules if you want to extend or modify the Template Toolkit in some way, or if you're interested in looking under the hood to see how it all works. .PP The documentation for each module is embedded as \s-1POD\s0 in each module, so you can always use \f(CW\*(C`perldoc\*(C'\fR from the command line to read a module's documentation. e.g. .PP .Vb 3 \& $ perldoc Template \& $ perldoc Template::Context \& ...etc... .Ve .PP It's worth noting that all the other documentation, including the user manual is available as \s-1POD.\s0 e.g. .PP .Vb 3 \& $ perldoc Template::Manual \& $ perldoc Template::Manual::Config \& ...etc... .Ve .PP The Template::Tools section contains the documentation for Template::Tools::tpage and Template::Tools::ttree. These are two command line programs that are distributed with the Template Toolkit. tpage is used to process a single template file, ttree for processing entire directories of template files. .PP The Template::Tutorial section contains two introductory tutorials on using the Template Toolkit. The first is Template::Tutorial::Web on generating web content. The second is Template::Tutorial::Datafile on using the Template Toolkit to generate other data formats including \s-1XML.\s0 .PP The final section of the manual is Template::FAQ which contains answers to some of the Frequently Asked Questions about the Template Toolkit. .PP You can read the documentation in \s-1HTML\s0 format either online at the Template Toolkit web site, <http://template\-toolkit.org/>, or by downloading the \&\s-1HTML\s0 version of the documentation from <http://template\-toolkit.org/download/index.html#html_docs> and unpacking it on your local machine. .SH "Author" .IX Header "Author" The Template Toolkit was written by Andy Wardley (<http://wardley.org/> <mailto:abw@wardley.org>) with assistance and contributions from a great number of people. Please see Template::Manual::Credits for a full list. .SH "Copyright" .IX Header "Copyright" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "See Also" .IX Header "See Also" Template, Template::Manual, Template::Modules, Template::Tools, Template::Tutorial PK � �[�qz�' �' man3/Template::Document.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Document 3" .TH Template::Document 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Document \- Compiled template document object .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Document; \& \& $doc = Template::Document\->new({ \& BLOCK => sub { # some perl code; return $some_text }, \& DEFBLOCKS => { \& header => sub { # more perl code; return $some_text }, \& footer => sub { # blah blah blah; return $some_text }, \& }, \& METADATA => { \& author => \*(AqAndy Wardley\*(Aq, \& version => 3.14, \& } \& }) || die $Template::Document::ERROR; \& \& print $doc\->process($context); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module defines an object class whose instances represent compiled template documents. The Template::Parser module creates a \&\f(CW\*(C`Template::Document\*(C'\fR instance to encapsulate a template as it is compiled into Perl code. .PP The constructor method, \fBnew()\fR, expects a reference to a hash array containing the \f(CW\*(C`BLOCK\*(C'\fR, \f(CW\*(C`DEFBLOCKS\*(C'\fR and \f(CW\*(C`METADATA\*(C'\fR items. .PP The \f(CW\*(C`BLOCK\*(C'\fR item should contain a reference to a Perl subroutine or a textual representation of Perl code, as generated by the Template::Parser module. This is then evaluated into a subroutine reference using \f(CW\*(C`eval()\*(C'\fR. .PP The \f(CW\*(C`DEFBLOCKS\*(C'\fR item should reference a hash array containing further named \&\f(CW\*(C`BLOCK\*(C'\fRs which may be defined in the template. The keys represent \f(CW\*(C`BLOCK\*(C'\fR names and the values should be subroutine references or text strings of Perl code as per the main \f(CW\*(C`BLOCK\*(C'\fR item. .PP The \f(CW\*(C`METADATA\*(C'\fR item should reference a hash array of metadata items relevant to the document. .PP The \fBprocess()\fR method can then be called on the instantiated \&\f(CW\*(C`Template::Document\*(C'\fR object, passing a reference to a Template::Context object as the first parameter. This will install any locally defined blocks (\f(CW\*(C`DEFBLOCKS\*(C'\fR) in the \f(CW\*(C`BLOCKS\*(C'\fR cache in the context (via a call to \&\fBvisit()\fR) so that they may be subsequently resolved by the context. The main \f(CW\*(C`BLOCK\*(C'\fR subroutine is then executed, passing the context reference on as a parameter. The text returned from the template subroutine is then returned by the \fBprocess()\fR method, after calling the context \fBleave()\fR method to permit cleanup and de-registration of named \f(CW\*(C`BLOCKS\*(C'\fR previously installed. .PP An \f(CW\*(C`AUTOLOAD\*(C'\fR method provides access to the \f(CW\*(C`METADATA\*(C'\fR items for the document. The Template::Service module installs a reference to the main \&\f(CW\*(C`Template::Document\*(C'\fR object in the stash as the \f(CW\*(C`template\*(C'\fR variable. This allows metadata items to be accessed from within templates, including \f(CW\*(C`PRE_PROCESS\*(C'\fR templates. .PP header: .PP .Vb 5 \& <html> \& <head> \& <title>[% template.title %] \& </head> \& ... .Ve .PP \&\f(CW\*(C`Template::Document\*(C'\fR objects are usually created by the Template::Parser but can be manually instantiated or sub-classed to provide custom template components. .SH "METHODS" .IX Header "METHODS" .SS "new(\e%config)" .IX Subsection "new(%config)" Constructor method which accept a reference to a hash array containing the structure as shown in this example: .PP .Vb 11 \& $doc = Template::Document\->new({ \& BLOCK => sub { # some perl code; return $some_text }, \& DEFBLOCKS => { \& header => sub { # more perl code; return $some_text }, \& footer => sub { # blah blah blah; return $some_text }, \& }, \& METADATA => { \& author => \*(AqAndy Wardley\*(Aq, \& version => 3.14, \& } \& }) || die $Template::Document::ERROR; .Ve .PP \&\f(CW\*(C`BLOCK\*(C'\fR and \f(CW\*(C`DEFBLOCKS\*(C'\fR items may be expressed as references to Perl subroutines or as text strings containing Perl subroutine definitions, as is generated by the Template::Parser module. These are evaluated into subroutine references using \f(CW\*(C`eval()\*(C'\fR. .PP Returns a new \f(CW\*(C`Template::Document\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR on error. The \&\fBerror()\fR class method can be called, or the \f(CW$ERROR\fR package variable inspected to retrieve the relevant error message. .SS "process($context)" .IX Subsection "process($context)" Main processing routine for the compiled template document. A reference to a Template::Context object should be passed as the first parameter. The method installs any locally defined blocks via a call to the context \&\fBvisit()\fR method, processes its own template, (passing the context reference as a parameter) and then calls \&\fBleave()\fR in the context to allow cleanup. .PP .Vb 1 \& print $doc\->process($context); .Ve .PP Returns a text string representing the generated output for the template. Errors are thrown via \f(CW\*(C`die()\*(C'\fR. .SS "\fBblock()\fP" .IX Subsection "block()" Returns a reference to the main \f(CW\*(C`BLOCK\*(C'\fR subroutine. .SS "\fBblocks()\fP" .IX Subsection "blocks()" Returns a reference to the hash array of named \f(CW\*(C`DEFBLOCKS\*(C'\fR subroutines. .SS "\fBvariables()\fP" .IX Subsection "variables()" Returns a reference to a hash of variables used in the template. This requires the \s-1TRACE_VARS\s0 option to be enabled. .SS "\fBmeta()\fP" .IX Subsection "meta()" Return a reference to a hash of any \s-1META\s0 items defined in the template. .SS "\s-1AUTOLOAD\s0" .IX Subsection "AUTOLOAD" An autoload method returns \f(CW\*(C`METADATA\*(C'\fR items. .PP .Vb 1 \& print $doc\->author(); .Ve .SH "CLASS METHODS" .IX Header "CLASS METHODS" These methods are used internally. .SS "as_perl($content)" .IX Subsection "as_perl($content)" This method generate a Perl representation of the template. .PP .Vb 10 \& my $perl = Template::Document\->as_perl({ \& BLOCK => $main_block, \& DEFBLOCKS => { \& foo => $foo_block, \& bar => $bar_block, \& }, \& METADATA => { \& name => \*(Aqmy_template\*(Aq, \& } \& }); .Ve .SS "write_perl_file(\e%config)" .IX Subsection "write_perl_file(%config)" This method is used to write compiled Perl templates to disk. If the \&\f(CW\*(C`COMPILE_EXT\*(C'\fR option (to indicate a file extension for saving compiled templates) then the Template::Parser module calls this subroutine before calling the \fBnew()\fR constructor. At this stage, the parser has a representation of the template as text strings containing Perl code. We can write that to a file, enclosed in a small wrapper which will allow us to subsequently \f(CW\*(C`require()\*(C'\fR the file and have Perl parse and compile it into a \&\f(CW\*(C`Template::Document\*(C'\fR. Thus we have persistence of compiled templates. .SH "INTERNAL FUNCTIONS" .IX Header "INTERNAL FUNCTIONS" .SS "\fBcatch_warnings()\fP" .IX Subsection "catch_warnings()" This is a simple handler used to catch any errors that arise when the compiled Perl template is first evaluated (that is, evaluated by Perl to create a template subroutine at compile, rather than the template being processed at runtime). .SS "\fBis_utf8()\fP" .IX Subsection "is_utf8()" This is mapped to \f(CW\*(C`utf8::is_utf8\*(C'\fR for versions of Perl that have it (> 5.008) or to \f(CW\*(C`Encode::is_utf8\*(C'\fR for Perl 5.008. Earlier versions of Perl are not supported. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2013 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Parser PK � �[�wD� ~ ~ man3/Template::Tutorial::Web.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Tutorial::Web 3" .TH Template::Tutorial::Web 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tutorial::Web \- Generating Web Content Using the Template Toolkit .SH "Overview" .IX Header "Overview" This tutorial document provides a introduction to the Template Toolkit and demonstrates some of the typical ways it may be used for generating web content. It covers the generation of static pages from templates using the tpage and ttree scripts and then goes on to show dynamic content generation using \s-1CGI\s0 scripts and Apache/mod_perl handlers. .PP Various features of the Template Toolkit are introduced and described briefly and explained by use of example. For further information, see Template, Template::Manual and the various sections within it. e.g .PP .Vb 3 \& perldoc Template # Template.pm module usage \& perldoc Template::Manual # index to manual \& perldoc Template::Manual::Config # e.g. configuration options .Ve .PP The documentation is also available in \s-1HTML\s0 format to read online, or download from the Template Toolkit web site: .PP .Vb 1 \& http://template\-toolkit.org/docs/ .Ve .SH "Introduction" .IX Header "Introduction" The Template Toolkit is a set of Perl modules which collectively implement a template processing system. .PP A template is a text document with special markup tags embedded in it. By default, the Template Toolkit uses '\f(CW\*(C`[%\*(C'\fR' and '\f(CW\*(C`%]\*(C'\fR' to denote the start and end of a tag. Here's an example: .PP .Vb 1 \& [% INCLUDE header %] \& \& People of [% planet %], your attention please. \& \& This is [% captain %] of the \& Galactic Hyperspace Planning Council. \& \& As you will no doubt be aware, the plans \& for development of the outlying regions \& of the Galaxy require the building of a \& hyperspatial express route through your \& star system, and regrettably your planet \& is one of those scheduled for destruction. \& \& The process will take slightly less than \& [% time %]. \& \& Thank you. \& \& [% INCLUDE footer %] .Ve .PP Tags can contain simple \fIvariables\fR (like \f(CW\*(C`planet\*(C'\fR and \f(CW\*(C`captain\*(C'\fR) and more complex \fIdirectives\fR that start with an upper case keyword (like \f(CW\*(C`INCLUDE\*(C'\fR). A directive is an instruction that tells the template processor to perform some action, like processing another template (\f(CW\*(C`header\*(C'\fR and \f(CW\*(C`footer\*(C'\fR in this example) and inserting the output into the current template. In fact, the simple variables we mentioned are actually \f(CW\*(C`GET\*(C'\fR directives, but the \f(CW\*(C`GET\*(C'\fR keyword is optional. .PP .Vb 2 \& People of [% planet %], your attention please. # short form \& People of [% GET planet %], your attention please. # long form .Ve .PP Other directives include \f(CW\*(C`SET\*(C'\fR to set a variable value (the \f(CW\*(C`SET\*(C'\fR keyword is also optional), \f(CW\*(C`FOREACH\*(C'\fR to iterate through a list of values, and \f(CW\*(C`IF\*(C'\fR, \&\f(CW\*(C`UNLESS\*(C'\fR, \f(CW\*(C`ELSIF\*(C'\fR and \f(CW\*(C`ELSE\*(C'\fR to declare conditional blocks. .PP The Template Toolkit processes all \fItext\fR files equally, regardless of what kind of content they contain. So you can use \s-1TT\s0 to generate \s-1HTML, XML, CSS,\s0 Javascript, Perl, \s-1RTF,\s0 LaTeX, or any other text-based format. In this tutorial, however, we'll be concentrating on generating \s-1HTML\s0 for web pages. .SH "Generating Static Web Content" .IX Header "Generating Static Web Content" Here's an example of a template used to generate an \s-1HTML\s0 document. .PP .Vb 2 \& [% INCLUDE header \& title = \*(AqThis is an HTML example\*(Aq; \& \& pages = [ \& { url = \*(Aqhttp://foo.org\*(Aq \& title = \*(AqThe Foo Organisation\*(Aq \& } \& { url = \*(Aqhttp://bar.org\*(Aq \& title = \*(AqThe Bar Organisation\*(Aq \& } \& ] \& %] \& <h1>Some Interesting Links</h1> \& <ul> \& [% FOREACH page IN pages %] \& <li><a href="[% page.url %]">[% page.title %]</a> \& [% END %] \& </ul> \& \& [% INCLUDE footer %] .Ve .PP This example shows how the \f(CW\*(C`INCLUDE\*(C'\fR directive is used to load and process separate '\f(CW\*(C`header\*(C'\fR' and '\f(CW\*(C`footer\*(C'\fR' template files, including the output in the current document. These files might look something like this: .PP header: .PP .Vb 5 \& <html> \& <head> \& <title>[% title %]</title> \& </head> \& <body> .Ve .PP footer: .PP .Vb 5 \& <div class="copyright"> \& © Copyright 2007 Arthur Dent \& </div> \& </body> \& </html> .Ve .PP The example also uses the \f(CW\*(C`FOREACH\*(C'\fR directive to iterate through the \&'\f(CW\*(C`pages\*(C'\fR' list to build a table of links. In this example, we have defined this list within the template to contain a number of hash references, each containing a '\f(CW\*(C`url\*(C'\fR' and '\f(CW\*(C`title\*(C'\fR' member. The \f(CW\*(C`FOREACH\*(C'\fR directive iterates through the list, aliasing '\f(CW\*(C`page\*(C'\fR' to each item (in this case, hash array references). The \f(CW\*(C`[% page.url %]\*(C'\fR and \f(CW\*(C`[% page.title %]\*(C'\fR directives then access the individual values in the hash arrays and insert them into the document. .SS "Using tpage" .IX Subsection "Using tpage" Having created a template file we can now process it to generate some real output. The quickest and easiest way to do this is to use the tpage script. This is provided as part of the Template Toolkit and should be installed in your usual Perl bin directory. .PP Assuming you saved your template file as \fIexample.html\fR, you would run the command: .PP .Vb 1 \& $ tpage example.html .Ve .PP This will process the template file, sending the output to \f(CW\*(C`STDOUT\*(C'\fR (i.e. whizzing past you on the screen). You may want to redirect the output to a file but be careful not to specify the same name as the template file, or you'll overwrite it. You may want to use one prefix for your templates (e.g. \&'\f(CW\*(C`.tt\*(C'\fR') and another (e.g. '\f(CW\*(C`.html\*(C'\fR') for the output files. .PP .Vb 1 \& $ tpage example.tt > example.html .Ve .PP Or you can redirect the output to another directory. e.g. .PP .Vb 1 \& $ tpage templates/example.tt > html/example.html .Ve .PP The output generated would look like this: .PP .Vb 10 \& <html> \& <head> \& <title>This is an HTML example</title> \& </head> \& <body> \& <h1>Some Interesting Links</h1> \& <ul> \& <li><a href="http://foo.org">The Foo Organsiation</a> \& <li><a href="http://bar.org">The Bar Organsiation</a> \& </ul> \& <div class="copyright"> \& © Copyright 2007 Arthur Dent \& </div> \& </body> \& </html> .Ve .PP The \fIheader\fR and \fIfooter\fR template files have been included (assuming you created them and they're in the current directory) and the link data has been built into an \s-1HTML\s0 list. .SS "Using ttree" .IX Subsection "Using ttree" The tpage script gives you a simple and easy way to process a single template without having to write any Perl code. The <ttree:Template::Tools::ttree> script, also distributed as part of the Template Toolkit, provides a more flexible way to process a number of template documents in one go. .PP The first time you run the script, it will ask you if it should create a configuration file (\fI.ttreerc\fR) in your home directory. Answer \f(CW\*(C`y\*(C'\fR to have it create the file. .PP The <ttree:Template::Tools::ttree> documentation describes how you can change the location of this file and also explains the syntax and meaning of the various options in the file. Comments are written to the sample configuration file which should also help. .PP In brief, the configuration file describes the directories in which template files are to be found (\f(CW\*(C`src\*(C'\fR), where the corresponding output should be written to (\f(CW\*(C`dest\*(C'\fR), and any other directories (\f(CW\*(C`lib\*(C'\fR) that may contain template files that you plan to \f(CW\*(C`INCLUDE\*(C'\fR into your source documents. You can also specify processing options (such as \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`recurse\*(C'\fR) and provide regular expression to match files that you don't want to process (\f(CW\*(C`ignore\*(C'\fR, \&\f(CW\*(C`accept\*(C'\fR)> or should be copied instead of being processed as templates (\f(CW\*(C`copy\*(C'\fR). .PP An example \fI.ttreerc\fR file is shown here: .PP \&\f(CW$HOME\fR/.ttreerc: .PP .Vb 2 \& verbose \& recurse \& \& # this is where I keep other ttree config files \& cfg = ~/.ttree \& \& src = ~/websrc/src \& lib = ~/websrc/lib \& dest = ~/public_html/test \& \& ignore = \eb(CVS|RCS)\eb \& ignore = ^# .Ve .PP You can create many different configuration files and store them in the directory specified in the \f(CW\*(C`cfg\*(C'\fR option, shown above. You then add the \f(CW\*(C`\-f filename\*(C'\fR option to \f(CW\*(C`ttree\*(C'\fR to have it read that file. .PP When you run the script, it compares all the files in the \f(CW\*(C`src\*(C'\fR directory (including those in sub-directories if the \f(CW\*(C`recurse\*(C'\fR option is set), with those in the \f(CW\*(C`dest\*(C'\fR directory. If the destination file doesn't exist or has an earlier modification time than the corresponding source file, then the source will be processed with the output written to the destination file. The \f(CW\*(C`\-a\*(C'\fR option forces all files to be processed, regardless of modification times. .PP The script \fIdoesn't\fR process any of the files in the \f(CW\*(C`lib\*(C'\fR directory, but it does add it to the \f(CW\*(C`INCLUDE_PATH\*(C'\fR for the template processor so that it can locate these files via an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive. Thus, the \f(CW\*(C`lib\*(C'\fR directory is an excellent place to keep template elements such as header, footers, etc., that aren't complete documents in their own right. .PP You can also specify various Template Toolkit options from the configuration file. Consult the ttree documentation and help summary (\f(CW\*(C`ttree \-h\*(C'\fR) for full details. e.g. .PP \&\f(CW$HOME\fR/.ttreerc: .PP .Vb 3 \& pre_process = config \& interpolate \& post_chomp .Ve .PP The \f(CW\*(C`pre_process\*(C'\fR option allows you to specify a template file which should be processed before each file. Unsurprisingly, there's also a \&\f(CW\*(C`post_process\*(C'\fR option to add a template after each file. In the fragment above, we have specified that the \f(CW\*(C`config\*(C'\fR template should be used as a prefix template. We can create this file in the \f(CW\*(C`lib\*(C'\fR directory and use it to define some common variables, including those web page links we defined earlier and might want to re-use in other templates. We could also include an \s-1HTML\s0 header, title, or menu bar in this file which would then be prepended to each and every template file, but for now we'll keep all that in a separate \f(CW\*(C`header\*(C'\fR file. .PP \&\f(CW$lib\fR/config: .PP .Vb 10 \& [% root = \*(Aq~/abw\*(Aq \& home = "$root/index.html" \& images = "$root/images" \& email = \*(Aqabw@wardley.org\*(Aq \& graphics = 1 \& webpages = [ \& { url => \*(Aqhttp://foo.org\*(Aq, title => \*(AqThe Foo Organsiation\*(Aq } \& { url => \*(Aqhttp://bar.org\*(Aq, title => \*(AqThe Bar Organsiation\*(Aq } \& ] \& %] .Ve .PP Assuming you've created or copied the \f(CW\*(C`header\*(C'\fR and \f(CW\*(C`footer\*(C'\fR files from the earlier example into your \f(CW\*(C`lib\*(C'\fR directory, you can now start to create web pages like the following in your \f(CW\*(C`src\*(C'\fR directory and process them with \f(CW\*(C`ttree\*(C'\fR. .PP \&\f(CW$src\fR/newpage.html: .PP .Vb 3 \& [% INCLUDE header \& title = \*(AqAnother Template Toolkit Test Page\*(Aq \& %] \& \& <a href="[% home %]">Home</a> \& <a href="mailto:[% email %]">Email</a> \& \& [% IF graphics %] \& <img src="[% images %]/logo.gif" align=right width=60 height=40> \& [% END %] \& \& [% INCLUDE footer %] .Ve .PP Here we've shown how pre-defined variables can be used as flags to enable certain feature (e.g. \f(CW\*(C`graphics\*(C'\fR) and to specify common items such as an email address and \s-1URL\s0's for the home page, images directory and so on. This approach allows you to define these values once so that they're consistent across all pages and can easily be changed to new values. .PP When you run \fIttree\fR, you should see output similar to the following (assuming you have the verbose flag set). .PP .Vb 1 \& ttree 2.9 (Template Toolkit version 2.20) \& \& Source: /home/abw/websrc/src \& Destination: /home/abw/public_html/test \& Include Path: [ /home/abw/websrc/lib ] \& Ignore: [ \eb(CVS|RCS)\eb, ^# ] \& Copy: [ ] \& Accept: [ * ] \& \& + newpage.html .Ve .PP The \f(CW\*(C`+\*(C'\fR in front of the \f(CW\*(C`newpage.html\*(C'\fR filename shows that the file was processed, with the output being written to the destination directory. If you run the same command again, you'll see the following line displayed instead showing a \f(CW\*(C`\-\*(C'\fR and giving a reason why the file wasn't processed. .PP .Vb 1 \& \- newpage.html (not modified) .Ve .PP It has detected a \f(CW\*(C`newpage.html\*(C'\fR in the destination directory which is more recent than that in the source directory and so hasn't bothered to waste time re-processing it. To force all files to be processed, use the \f(CW\*(C`\-a\*(C'\fR option. You can also specify one or more filenames as command line arguments to \f(CW\*(C`ttree\*(C'\fR: .PP .Vb 1 \& tpage newpage.html .Ve .PP This is what the destination page looks like. .PP \&\f(CW$dest\fR/newpage.html: .PP .Vb 5 \& <html> \& <head> \& <title>Another Template Toolkit Test Page</title> \& </head> \& <body> \& \& <a href="~/abw/index.html">Home</a> \& <a href="mailto:abw@wardley.org">Email me</a> \& <img src="~/abw/images/logo.gif" align=right width=60 height=40> \& \& <div class="copyright"> \& © Copyright 2007 Arthur Dent \& </div> \& </body> \& </html> .Ve .PP You can add as many documents as you like to the \f(CW\*(C`src\*(C'\fR directory and \&\f(CW\*(C`ttree\*(C'\fR will apply the same process to them all. In this way, it is possible to build an entire tree of static content for a web site with a single command. The added benefit is that you can be assured of consistency in links, header style, or whatever else you choose to implement in terms of common templates elements or variables. .SH "Dynamic Content Generation Via CGI Script" .IX Header "Dynamic Content Generation Via CGI Script" The Template module provides a simple front-end to the Template Toolkit for use in \s-1CGI\s0 scripts and Apache/mod_perl handlers. Simply \f(CW\*(C`use\*(C'\fR the Template module, create an object instance with the \fBnew()\fR method and then call the \&\fBprocess()\fR method on the object, passing the name of the template file as a parameter. The second parameter passed is a reference to a hash array of variables that we want made available to the template: .PP .Vb 4 \& #!/usr/bin/perl \& use strict; \& use warnings; \& use Template; \& \& my $file = \*(Aqsrc/greeting.html\*(Aq; \& my $vars = { \& message => "Hello World\en" \& }; \& \& my $template = Template\->new(); \& \& $template\->process($file, $vars) \& || die "Template process failed: ", $template\->error(), "\en"; .Ve .PP So that our scripts will work with the same template files as our earlier examples, we'll can add some configuration options to the constructor to tell it about our environment: .PP .Vb 6 \& my $template\->new({ \& # where to find template files \& INCLUDE_PATH => [\*(Aq/home/abw/websrc/src\*(Aq, \*(Aq/home/abw/websrc/lib\*(Aq], \& # pre\-process lib/config to define any extra values \& PRE_PROCESS => \*(Aqconfig\*(Aq, \& }); .Ve .PP Note that here we specify the \f(CW\*(C`config\*(C'\fR file as a \f(CW\*(C`PRE_PROCESS\*(C'\fR option. This means that the templates we process can use the same global variables defined earlier for our static pages. We don't have to replicate their definitions in this script. However, we can supply additional data and functionality specific to this script via the hash of variables that we pass to the \f(CW\*(C`process()\*(C'\fR method. .PP These entries in this hash may contain simple text or other values, references to lists, others hashes, sub-routines or objects. The Template Toolkit will automatically apply the correct procedure to access these different types when you use the variables in a template. .PP Here's a more detailed example to look over. Amongst the different template variables we define in \f(CW$vars\fR, we create a reference to a \&\s-1CGI\s0 object and a \f(CW\*(C`get_user_projects()\*(C'\fR sub-routine. .PP .Vb 5 \& #!/usr/bin/perl \& use strict; \& use warnings; \& use Template; \& use CGI; \& \& $| = 1; \& print "Content\-type: text/html\en\en"; \& \& my $file = \*(Aquserinfo.html\*(Aq; \& my $vars = { \& \*(Aqversion\*(Aq => 3.14, \& \*(Aqdays\*(Aq => [ qw( mon tue wed thu fri sat sun ) ], \& \*(Aqworklist\*(Aq => \e&get_user_projects, \& \*(Aqcgi\*(Aq => CGI\->new(), \& \*(Aqme\*(Aq => { \& \*(Aqid\*(Aq => \*(Aqabw\*(Aq, \& \*(Aqname\*(Aq => \*(AqAndy Wardley\*(Aq, \& }, \& }; \& \& sub get_user_projects { \& my $user = shift; \& my @projects = ... # do something to retrieve data \& return \e@projects; \& } \& \& my $template = Template\->new({ \& INCLUDE_PATH => \*(Aq/home/abw/websrc/src:/home/abw/websrc/lib\*(Aq, \& PRE_PROCESS => \*(Aqconfig\*(Aq, \& }); \& \& $template\->process($file, $vars) \& || die $template\->error(); .Ve .PP Here's a sample template file that we might create to build the output for this script. .PP \&\f(CW$src\fR/userinfo.html: .PP .Vb 3 \& [% INCLUDE header \& title = \*(AqTemplate Toolkit CGI Test\*(Aq \& %] \& \& <a href="mailto:[% email %]">Email [% me.name %]</a> \& \& <p>This is version [% version %]</p> \& \& <h3>Projects</h3> \& <ul> \& [% FOREACH project IN worklist(me.id) %] \& <li> <a href="[% project.url %]">[% project.name %]</a> \& [% END %] \& </ul> \& \& [% INCLUDE footer %] .Ve .PP This example shows how we've separated the Perl implementation (code) from the presentation (\s-1HTML\s0). This not only makes them easier to maintain in isolation, but also allows the re-use of existing template elements such as headers and footers, etc. By using template to create the output of your \s-1CGI\s0 scripts, you can give them the same consistency as your static pages built via ttree or other means. .PP Furthermore, we can modify our script so that it processes any one of a number of different templates based on some condition. A \s-1CGI\s0 script to maintain a user database, for example, might process one template to provide an empty form for new users, the same form with some default values set for updating an existing user record, a third template for listing all users in the system, and so on. You can use any Perl functionality you care to write to implement the logic of your application and then choose one or other template to generate the desired output for the application state. .SH "Dynamic Content Generation Via Apache/Mod_Perl Handler" .IX Header "Dynamic Content Generation Via Apache/Mod_Perl Handler" \&\fB\s-1NOTE:\s0\fR the Apache::Template module is available from \s-1CPAN\s0 and provides a simple and easy to use Apache/mod_perl interface to the Template Toolkit. Although basic, it implements most, if not all of what is described below, and it avoids the need to write your own handler. However, in many cases, you'll want to write your own handler to customise processing for your own need, and this section will show you how to get started. .PP The Template module can be used from an Apache/mod_perl handler. Here's an example of a typical Apache \fIhttpd.conf\fR file: .PP .Vb 3 \& PerlModule CGI; \& PerlModule Template \& PerlModule MyOrg::Apache::User \& \& PerlSetVar websrc_root /home/abw/websrc \& \& <Location /user/bin> \& SetHandler perl\-script \& PerlHandler MyOrg::Apache::User \& </Location> .Ve .PP This defines a location called \f(CW\*(C`/user/bin\*(C'\fR to which all requests will be forwarded to the \f(CW\*(C`handler()\*(C'\fR method of the \f(CW\*(C`MyOrg::Apache::User\*(C'\fR module. That module might look something like this: .PP .Vb 1 \& package MyOrg::Apache::User; \& \& use strict; \& use Apache::Constants qw( :common ); \& use Template; \& use CGI; \& \& our $VERSION = 1.59; \& \& sub handler { \& my $r = shift; \& \& my $websrc = $r\->dir_config(\*(Aqwebsrc_root\*(Aq) \& or return fail($r, SERVER_ERROR, \& "\*(Aqwebsrc_root\*(Aq not specified"); \& \& my $template = Template\->new({ \& INCLUDE_PATH => "$websrc/src/user:$websrc/lib", \& PRE_PROCESS => \*(Aqconfig\*(Aq, \& OUTPUT => $r, # direct output to Apache request \& }); \& \& my $params = { \& uri => $r\->uri, \& cgi => CGI\->new, \& }; \& \& # use the path_info to determine which template file to process \& my $file = $r\->path_info; \& $file =~ s[^/][]; \& \& $r\->content_type(\*(Aqtext/html\*(Aq); \& $r\->send_http_header; \& \& $template\->process($file, $params) \& || return fail($r, SERVER_ERROR, $template\->error()); \& \& return OK; \& } \& \& sub fail { \& my ($r, $status, $message) = @_; \& $r\->log_reason($message, $r\->filename); \& return $status; \& } .Ve .PP The handler accepts the request and uses it to determine the \f(CW\*(C`websrc_root\*(C'\fR value from the config file. This is then used to define an \f(CW\*(C`INCLUDE_PATH\*(C'\fR for a new Template object. The \s-1URI\s0 is extracted from the request and a \&\s-1CGI\s0 object is created. These are both defined as template variables. .PP The name of the template file itself is taken from the \f(CW\*(C`PATH_INFO\*(C'\fR element of the request. In this case, it would comprise the part of the \s-1URL\s0 coming after \f(CW\*(C`/user/bin\*(C'\fR, e.g for \f(CW\*(C`/user/bin/edit\*(C'\fR, the template file would be \f(CW\*(C`edit\*(C'\fR located in \f(CW\*(C`$websrc/src/user\*(C'\fR. The headers are sent and the template file is processed. All output is sent directly to the \&\f(CW\*(C`print()\*(C'\fR method of the Apache request object. .SH "Using Plugins to Extend Functionality" .IX Header "Using Plugins to Extend Functionality" As we've already shown, it is possible to bind Perl data and functions to template variables when creating dynamic content via a \s-1CGI\s0 script or Apache/mod_perl process. The Template Toolkit also supports a plugin interface which allows you define such additional data and/or functionality in a separate module and then load and use it as required with the \f(CW\*(C`USE\*(C'\fR directive. .PP The main benefit to this approach is that you can load the extension into any template document, even those that are processed \*(L"statically\*(R" by \&\f(CW\*(C`tpage\*(C'\fR or \f(CW\*(C`ttree\*(C'\fR. You \fIdon't\fR need to write a Perl wrapper to explicitly load the module and make it available via the stash. .PP Let's demonstrate this principle using the \f(CW\*(C`DBI\*(C'\fR plugin written by Simon Matthews (available from \s-1CPAN\s0). You can create this template in your \f(CW\*(C`src\*(C'\fR directory and process it using \f(CW\*(C`ttree\*(C'\fR to see the results. Of course, this example relies on the existence of the appropriate \s-1SQL\s0 database but you should be able to adapt it to your own resources, or at least use it as a demonstrative example of what's possible. .PP .Vb 3 \& [% INCLUDE header \& title = \*(AqUser Info\*(Aq \& %] \& \& [% USE DBI(\*(Aqdbi:mSQL:mydbname\*(Aq) %] \& \& <table border=0 width="100%"> \& <tr> \& <th>User ID</th> \& <th>Name</th> \& <th>Email</th> \& </tr> \& [% FOREACH user IN DBI.query(\*(AqSELECT * FROM user ORDER BY id\*(Aq) %] \& <tr> \& <td>[% user.id %]</td> \& <td>[% user.name %]</td> \& <td>[% user.email %]</td> \& </tr> \& [% END %] \& </table> \& \& [% INCLUDE footer %] .Ve .PP A plugin is simply a Perl module in a known location and conforming to a known standard such that the Template Toolkit can find and load it automatically. You can create your own plugin by inheriting from the Template::Plugin module. .PP Here's an example which defines some data items (\f(CW\*(C`foo\*(C'\fR and \f(CW\*(C`people\*(C'\fR) and also an object method (\f(CW\*(C`bar\*(C'\fR). We'll call the plugin \f(CW\*(C`FooBar\*(C'\fR for want of a better name and create it in the \f(CW\*(C`MyOrg::Template::Plugin::FooBar\*(C'\fR package. We've added a \f(CW\*(C`MyOrg\*(C'\fR to the regular \f(CW\*(C`Template::Plugin::*\*(C'\fR package to avoid any conflict with existing plugins. .PP .Vb 3 \& package MyOrg::Template::Plugin::FooBar; \& use base \*(AqTemplate::Plugin\*(Aq \& our $VERSION = 1.23; \& \& sub new { \& my ($class, $context, @params) = @_; \& \& bless { \& _CONTEXT => $context, \& foo => 25, \& people => [ \*(Aqtom\*(Aq, \*(Aqdick\*(Aq, \*(Aqharry\*(Aq ], \& }, $class; \& } \& \& sub bar { \& my ($self, @params) = @_; \& # ...do something... \& return $some_value; \& } .Ve .PP The plugin constructor \f(CW\*(C`new()\*(C'\fR receives the class name as the first parameter, as is usual in Perl, followed by a reference to something called a Template::Context object. You don't need to worry too much about this at the moment, other than to know that it's the main processing object for the Template Toolkit. It provides access to the functionality of the processor and some plugins may need to communicate with it. We don't at this stage, but we'll save the reference anyway in the \f(CW\*(C`_CONTEXT\*(C'\fR member. The leading underscore is a convention which indicates that this item is private and the Template Toolkit won't attempt to access this member. The other members defined, \f(CW\*(C`foo\*(C'\fR and \f(CW\*(C`people\*(C'\fR are regular data items which will be made available to templates using this plugin. Following the context reference are passed any additional parameters specified with the \s-1USE\s0 directive, such as the data source parameter, \f(CW\*(C`dbi:mSQL:mydbname\*(C'\fR, that we used in the earlier \s-1DBI\s0 example. .PP If you don't or can't install it to the regular place for your Perl modules (perhaps because you don't have the required privileges) then you can set the \s-1PERL5LIB\s0 environment variable to specify another location. If you're using \f(CW\*(C`ttree\*(C'\fR then you can add the following line to your configuration file instead. .PP \&\f(CW$HOME\fR/.ttreerc: .PP .Vb 1 \& perl5lib = /path/to/modules .Ve .PP One further configuration item must be added to inform the toolkit of the new package name we have adopted for our plugins: .PP \&\f(CW$HOME\fR/.ttreerc: .PP .Vb 1 \& plugin_base = \*(AqMyOrg::Template::Plugin\*(Aq .Ve .PP If you're writing Perl code to control the Template modules directly, then this value can be passed as a configuration parameter when you create the module. .PP .Vb 1 \& use Template; \& \& my $template = Template\->new({ \& PLUGIN_BASE => \*(AqMyOrg::Template::Plugin\*(Aq \& }); .Ve .PP Now we can create a template which uses this plugin: .PP .Vb 3 \& [% INCLUDE header \& title = \*(AqFooBar Plugin Test\*(Aq \& %] \& \& [% USE FooBar %] \& \& Some values available from this plugin: \& [% FooBar.foo %] [% FooBar.bar %] \& \& The users defined in the \*(Aqpeople\*(Aq list: \& [% FOREACH uid = FooBar.people %] \& * [% uid %] \& [% END %] \& \& [% INCLUDE footer %] .Ve .PP The \f(CW\*(C`foo\*(C'\fR, \f(CW\*(C`bar\*(C'\fR, and \f(CW\*(C`people\*(C'\fR items of the FooBar plugin are automatically resolved to the appropriate data items or method calls on the underlying object. .PP Using this approach, it is possible to create application functionality in a single module which can then be loaded and used on demand in any template. The simple interface between template directives and plugin objects allows complex, dynamic content to be built from a few simple template documents without knowing anything about the underlying implementation. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[�9�� � man3/Template::Stash::XS.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Stash::XS 3" .TH Template::Stash::XS 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Stash::XS \- High\-speed variable stash written in C .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Template; \& use Template::Stash::XS; \& \& my $stash = Template::Stash::XS\->new(\e%vars); \& my $tt2 = Template\->new({ STASH => $stash }); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Template:Stash::XS module is an implementation of the Template::Stash written in C. The \*(L"\s-1XS\*(R"\s0 in the name refers to Perl's \&\s-1XS\s0 extension system for interfacing Perl to C code. It works just like the regular Perl implementation of Template::Stash but runs about twice as fast. .PP The easiest way to use the \s-1XS\s0 stash is to configure the Template Toolkit to use it by default. You can do this at installation time (when you run \f(CW\*(C`perl Makefile.PL\*(C'\fR) by answering 'y' to the questions: .PP .Vb 2 \& Do you want to build the XS Stash module? y \& Do you want to use the XS Stash by default? y .Ve .PP See the \fI\s-1INSTALL\s0\fR file distributed with the Template Toolkit for further details on installation. .PP If you don't elect to use the \s-1XS\s0 stash by default then you should use the \f(CW\*(C`STASH\*(C'\fR configuration item when you create a new Template object. This should reference an \s-1XS\s0 stash object that you have created manually. .PP .Vb 2 \& use Template; \& use Template::Stash::XS; \& \& my $stash = Template::Stash::XS\->new(\e%vars); \& my $tt2 = Template\->new({ STASH => $stash }); .Ve .PP Alternately, you can set the \f(CW$Template::Config::STASH\fR package variable like so: .PP .Vb 2 \& use Template; \& use Template::Config; \& \& $Template::Config::STASH = \*(AqTemplate::Stash::XS\*(Aq; \& \& my $tt2 = Template\->new(); .Ve .PP The \s-1XS\s0 stash will then be automatically used. .PP If you want to use the \s-1XS\s0 stash by default and don't want to re-install the Template Toolkit, then you can manually modify the \&\f(CW\*(C`Template/Config.pm\*(C'\fR module near line 42 to read: .PP .Vb 1 \& $STASH = \*(AqTemplate::Stash::XS\*(Aq; .Ve .SH "BUGS" .IX Header "BUGS" Please report bugs to the Template Toolkit mailing list templates@template\-toolkit.org .SH "AUTHORS" .IX Header "AUTHORS" Andy Wardley <abw@wardley.org> <http://wardley.org/> .PP Doug Steinwand <dsteinwand@citysearch.com> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Stash PK � �[A4i��1 �1 man3/Template::FAQ.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::FAQ 3" .TH Template::FAQ 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::FAQ \- Frequently Asked Questions about the Template Toolkit .SH "Template Toolkit Language" .IX Header "Template Toolkit Language" .SS "Why doesn't [% a = b \s-1IF\s0 c %] work as expected?" .IX Subsection "Why doesn't [% a = b IF c %] work as expected?" There's a limitation in the \s-1TT2\s0 parser which means that the following code doesn't work as you might expect: .PP .Vb 1 \& [% a = b IF c %] .Ve .PP The parser interprets it as an attempt to set \f(CW\*(C`a\*(C'\fR to the result of \&\f(CW\*(C`b IF c\*(C'\fR, like this: .PP .Vb 1 \& [% a = (b IF c) %] .Ve .PP If you want to set \f(CW\*(C`a = b\*(C'\fR only if \f(CW\*(C`c\*(C'\fR is true, then do this instead: .PP .Vb 1 \& [% SET a = b IF c %] .Ve .PP The explicit \f(CW\*(C`SET\*(C'\fR keyword gives the parser the clue it needs to do the right thing. .PP \&\s-1NOTE:\s0 this will be fixed in \s-1TT3\s0 .SS "If I'm using \s-1TT\s0 to write out a \s-1TT\s0 template, is there a good way to escape [% and %]?" .IX Subsection "If I'm using TT to write out a TT template, is there a good way to escape [% and %]?" You can do something like this: .PP .Vb 3 \& [% stag = "[\e%" \& etag = "%\e]" \& %] .Ve .PP and then: .PP .Vb 1 \& [% stag; \*(Aqhello\*(Aq; etag %] .Ve .PP Or you can use the \f(CW\*(C`TAGS\*(C'\fR directive, like so: .PP .Vb 3 \& [% TAGS [\- \-] %] \& [\- INCLUDE foo \-] # is a directive \& [% INCLUDE foo %] # not a directive .Ve .SS "How do I iterate over a hash?" .IX Subsection "How do I iterate over a hash?" This is covered in the Template::Manual::VMethods section of the manual. A list of all the keys that are in the hash can be obtained with the \&\f(CW\*(C`keys\*(C'\fR virtual method. You can then iterate over that list and by looking up each key in turn get the value. .PP .Vb 3 \& [% FOREACH key = product.keys %] \& [% key %] => [% product.$key %] \& [% END %] .Ve .SH "Plugins" .IX Header "Plugins" .SS "How do I get the Table plugin to order data across rather than down?" .IX Subsection "How do I get the Table plugin to order data across rather than down?" Order the data into rows: .PP .Vb 3 \& Steve Karen Jeff \& Brooklyn Nantucket Fairfax \& NY MA VA \& \& [% USE table(data, rows=3) %] .Ve .PP Then ask for each column .PP .Vb 1 \& [% FOREACH column = table.cols %] .Ve .PP And then print each item in the column going across the output rows .PP .Vb 3 \& [% FOREACH item = column %] \& <td>[% item %]</td> \& [% END %] .Ve .SS "Accessing Cookies" .IX Subsection "Accessing Cookies" Jeff Boes <jboes@nexcerpt.com> asks: .PP .Vb 2 \& Does anyone have a quick\-n\-dirty approach to accessing \& cookies from templates? .Ve .PP Jonas Liljegren answers: .PP .Vb 1 \& [% USE CGI %] \& \& <p>The value is [% CGI.cookie(\*(Aqcookie_name\*(Aq) | html %] .Ve .PP You will need to have Template::Plugin::CGI installed. .SH "Extending the Template Toolkit" .IX Header "Extending the Template Toolkit" .SS "Can I serve templates from a database?" .IX Subsection "Can I serve templates from a database?" Short answer: yes, Chris Nandor has done this for Slash. You need to subclass Template::Provider. See the mailing list archives for further info. .SS "Can I fetch templates via http?" .IX Subsection "Can I fetch templates via http?" To do the job properly, you should subclass Template::Provider to \&\f(CW\*(C`Template::Provider::HTTP\*(C'\fR and use a \f(CW\*(C`PREFIX_MAP\*(C'\fR option to bind the \f(CW\*(C`http\*(C'\fR template prefix to that particular provider (you may want to go digging around in the \fIChanges\fR file around version 2.01 for more info on \f(CW\*(C`PREFIX_MAP\*(C'\fR \- it may not be properly documented anywhere else...yet!). e.g. .PP .Vb 1 \& use Template::Provider::HTTP; \& \& my $file = Template::Provider( INCLUDE_PATH => [...] ); \& my $http = Template::Provider::HTTP\->new(...); \& my $tt2 = Template\->new({ \& LOAD_TEMPLATES => [ $file, $http ], \& PREFIX_MAP => { \& file => \*(Aq0\*(Aq, # file:foo.html \& http => \*(Aq1\*(Aq, # http:foo.html \& default => \*(Aq0\*(Aq, # foo.html => file:foo.html \& } \& }); .Ve .PP Now a template specified as: .PP .Vb 1 \& [% INCLUDE foo %] .Ve .PP will be served by the 'file' provider (the default). Otherwise you can explicitly add a prefix: .PP .Vb 3 \& [% INCLUDE file:foo.html %] \& [% INCLUDE http:foo.html %] \& [% INCLUDE http://www.xyz.com/tt2/header.tt2 %] .Ve .PP This same principal can be used to create a \s-1DBI\s0 template provider. e.g. .PP .Vb 1 \& [% INCLUDE dbi:foo.html %] .Ve .PP Alas, we don't yet have a \s-1DBI\s0 provider as part of the Template Toolkit. There has been some talk on the mailing list about efforts to develop \s-1DBI\s0 and/or \&\s-1HTTP\s0 providers but as yet no-one has stepped forward to take up the challenge... .PP In the mean time, Craig Barrat's post from the mailing list has some useful pointers on how to achieve this using existing modules. See <http://tt2.org/pipermail/templates/2001\-May/000954.html> .SH "Miscellaneous" .IX Header "Miscellaneous" .SS "How can I find out the name of the main template being processed?" .IX Subsection "How can I find out the name of the main template being processed?" The \f(CW\*(C`template\*(C'\fR variable contains a reference to the Template::Document object for the main template you're processing (i.e. the one provided as the first argument to the Template \fBprocess()\fR method). The \f(CW\*(C`name\*(C'\fR method returns its name. .PP .Vb 1 \& [% template.name %] # e.g. index.html .Ve .SS "How can I find out the name of the current template being processed?" .IX Subsection "How can I find out the name of the current template being processed?" The \f(CW\*(C`template\*(C'\fR variable always references the \fImain\fR template being processed. So even if you call [% \s-1INCLUDE\s0 header %], and that calls [% \s-1INCLUDE\s0 menu %], the \f(CW\*(C`template\*(C'\fR variable will be unchanged. .PP index.html: .PP .Vb 2 \& [% template.name %] # index.html \& [% INCLUDE header %] .Ve .PP header: .PP .Vb 2 \& [% template.name %] # index.html \& [% INCLUDE menu %] .Ve .PP menu: .PP .Vb 1 \& [% template.name %] # index.html .Ve .PP In contrast, the \f(CW\*(C`component\*(C'\fR variable always references the \fIcurrent\fR template being processed. .PP index.html .PP .Vb 2 \& [% component.name %] # index.html \& [% INCLUDE header %] .Ve .PP header: .PP .Vb 2 \& [% component.name %] # header \& [% INCLUDE menu %] .Ve .PP menu: .PP .Vb 1 \& [% component.name %] # menu .Ve .SS "How do I print the modification time of the template or component?" .IX Subsection "How do I print the modification time of the template or component?" The \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR variables reference the main template and the current template being processed (see previous questions). The \f(CW\*(C`modtime\*(C'\fR method returns the modification time of the corresponding template file as a number of seconds since the Unix epoch (00:00:00 \s-1GMT\s0 1st January 1970). .PP This number doesn't mean much to anyone (except perhaps serious Unix geeks) so you'll probably want to use the Date plugin to format it for human consumption. .PP .Vb 2 \& [% USE Date %] \& [% template.name %] last modified [% Date.format(template.modtime) %] .Ve .SS "How can I configure variables on a per-request basis?" .IX Subsection "How can I configure variables on a per-request basis?" One easy way to achieve this is to define a single \f(CW\*(C`PRE_PROCESS\*(C'\fR template which loads in other configuration files based on variables defined or other conditions. .PP For example, my setup usually looks something like this: .PP .Vb 1 \& PRE_PROCESS => \*(Aqconfig/main\*(Aq .Ve .PP config/main: .PP .Vb 2 \& [% DEFAULT style = \*(Aqtext\*(Aq \& section = template.section or \*(Aqhome\*(Aq; \& \& PROCESS config/site \& + config/urls \& + config/macros \& + "config/style/$style" \& + "config/section/$section" \& + ... \& %] .Ve .PP This allows me to set a single 'style' variable to control which config file gets pre-processed to set my various style options (colours, img paths, etc). For example: .PP config/style/basic: .PP .Vb 2 \& [% style = { \& name = style # save existing \*(Aqstyle\*(Aq var as \*(Aqstyle.name\*(Aq \& \& # define various other style variables.... \& col = { \& back => \*(Aq#ffffff\*(Aq \& text => \*(Aq#000000\*(Aq \& # ...etc... \& } \& \& logo = { \& # ...etc... \& } \& \& # ...etc... \& } \& %] .Ve .PP Each source template can declare which section it's in via a \s-1META\s0 directive: .PP .Vb 5 \& [% META \& title = \*(AqGeneral Information\*(Aq \& section = \*(Aqinfo\*(Aq \& %] \& ... .Ve .PP This controls which section configuration file gets loaded to set various other variables for defining the section title, menu, etc. .PP config/section/info: .PP .Vb 7 \& [% section = { \& name = section # save \*(Aqsection\*(Aq var as \*(Aqsection.name\*(Aq \& title = \*(AqInformation\*(Aq \& menu = [ ... ] \& # ...etc... \& } \& %] .Ve .PP This illustrates the basic principal but you can extend it to perform pretty much any kind of per-document initialisation that you require. .SS "Why do I get rubbish for my utf\-8 templates?" .IX Subsection "Why do I get rubbish for my utf-8 templates?" First of all, make sure that your template files define a Byte Order Mark <http://en.wikipedia.org/wiki/Byte_Order_Mark> .PP If you for some reason don't want to add \s-1BOM\s0 to your templates, you can force Template to use a particular encoding (e.g. \f(CW\*(C`utf8\*(C'\fR) for your templates with the \f(CW\*(C`ENCODING\*(C'\fR option. .PP .Vb 3 \& my $template = Template\->new({ \& ENCODING => \*(Aqutf8\*(Aq \& }); .Ve .SH "Questions About This FAQ" .IX Header "Questions About This FAQ" .SS "Why is this \s-1FAQ\s0 so short?" .IX Subsection "Why is this FAQ so short?" Because we don't have anyone maintaining it. .SS "Can I help?" .IX Subsection "Can I help?" Yes please :\-) PK � �[�b@GJ GJ " man3/Template::Manual::Filters.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Filters 3" .TH Template::Manual::Filters 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Filters \- Standard filters .SH "format(format)" .IX Header "format(format)" The \f(CW\*(C`format\*(C'\fR filter takes a format string as a parameter (as per \&\f(CW\*(C`printf()\*(C'\fR) and formats each line of text accordingly. .PP .Vb 4 \& [% FILTER format(\*(Aq<!\-\- %\-40s \-\->\*(Aq) %] \& This is a block of text filtered \& through the above format. \& [% END %] .Ve .PP Output: .PP .Vb 2 \& <!\-\- This is a block of text filtered \-\-> \& <!\-\- through the above format. \-\-> .Ve .SH "upper" .IX Header "upper" Folds the input to \s-1UPPER CASE.\s0 .PP .Vb 1 \& [% "hello world" FILTER upper %] .Ve .PP Output: .PP .Vb 1 \& HELLO WORLD .Ve .SH "lower" .IX Header "lower" Folds the input to lower case. .PP .Vb 1 \& [% "Hello World" FILTER lower %] .Ve .PP Output: .PP .Vb 1 \& hello world .Ve .SH "ucfirst" .IX Header "ucfirst" Folds the first character of the input to \s-1UPPER CASE.\s0 .PP .Vb 1 \& [% "hello" FILTER ucfirst %] .Ve .PP Output: .PP .Vb 1 \& Hello .Ve .SH "lcfirst" .IX Header "lcfirst" Folds the first character of the input to lower case. .PP .Vb 1 \& [% "HELLO" FILTER lcfirst %] .Ve .PP Output: .PP .Vb 1 \& hELLO .Ve .SH "trim" .IX Header "trim" Trims any leading or trailing whitespace from the input text. Particularly useful in conjunction with \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR, etc., having the same effect as the \f(CW\*(C`TRIM\*(C'\fR configuration option. .PP .Vb 1 \& [% INCLUDE myfile | trim %] .Ve .SH "collapse" .IX Header "collapse" Collapse any whitespace sequences in the input text into a single space. Leading and trailing whitespace (which would be reduced to a single space) is removed, as per trim. .PP .Vb 1 \& [% FILTER collapse %] \& \& The cat \& \& sat on \& \& the mat \& \& [% END %] .Ve .PP Output: .PP .Vb 1 \& The cat sat on the mat .Ve .SH "html" .IX Header "html" Converts the characters \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`&\*(C'\fR and \f(CW\*(C`"\*(C'\fR to \f(CW\*(C`<\*(C'\fR, \&\f(CW\*(C`>\*(C'\fR, \f(CW\*(C`&\*(C'\fR, and \f(CW\*(C`"\*(C'\fR respectively, protecting them from being interpreted as representing \s-1HTML\s0 tags or entities. .PP .Vb 3 \& [% FILTER html %] \& Binary "<=>" returns \-1, 0, or 1 depending on... \& [% END %] .Ve .PP Output: .PP .Vb 1 \& Binary "<=>" returns \-1, 0, or 1 depending on... .Ve .SH "html_entity" .IX Header "html_entity" The \f(CW\*(C`html\*(C'\fR filter is fast and simple but it doesn't encode the full range of \s-1HTML\s0 entities that your text may contain. The \f(CW\*(C`html_entity\*(C'\fR filter uses either the \f(CW\*(C`Apache::Util\*(C'\fR module (which is written in C and is therefore faster) or the \f(CW\*(C`HTML::Entities\*(C'\fR module (written in Perl but equally as comprehensive) to perform the encoding. .PP If one or other of these modules are installed on your system then the text will be encoded (via the \f(CW\*(C`escape_html()\*(C'\fR or \f(CW\*(C`encode_entities()\*(C'\fR subroutines respectively) to convert all extended characters into their appropriate \s-1HTML\s0 entities (e.g. converting '\f(CW\*(C`?\*(C'\fR' to '\f(CW\*(C`é\*(C'\fR'). If neither module is available on your system then an '\f(CW\*(C`html_entity\*(C'\fR' exception will be thrown reporting an appropriate message. .PP If you want to force \s-1TT\s0 to use one of the above modules in preference to the other, then call either of the Template::Filters class methods: \&\fBuse_html_entities()\fR or \&\fBuse_apache_util()\fR. .PP .Vb 2 \& use Template::Filters; \& Template::Filters\->use_html_entities; .Ve .PP For further information on \s-1HTML\s0 entity encoding, see <http://www.w3.org/TR/REC\-html40/sgml/entities.html>. .SH "xml" .IX Header "xml" Same as the \f(CW\*(C`html\*(C'\fR filter, but adds \f(CW\*(C`'\*(C'\fR which is the fifth \s-1XML\s0 built-in entity. .SH "html_para" .IX Header "html_para" This filter formats a block of text into \s-1HTML\s0 paragraphs. A sequence of two or more newlines is used as the delimiter for paragraphs which are then wrapped in \s-1HTML\s0 \f(CW\*(C`<p>\*(C'\fR...\f(CW\*(C`</p>\*(C'\fR tags. .PP .Vb 2 \& [% FILTER html_para %] \& The cat sat on the mat. \& \& Mary had a little lamb. \& [% END %] .Ve .PP Output: .PP .Vb 3 \& <p> \& The cat sat on the mat. \& </p> \& \& <p> \& Mary had a little lamb. \& </p> .Ve .SH "html_break / html_para_break" .IX Header "html_break / html_para_break" Similar to the html_para filter described above, but uses the \s-1HTML\s0 tag sequence \f(CW\*(C`<br><br>\*(C'\fR to join paragraphs. .PP .Vb 2 \& [% FILTER html_break %] \& The cat sat on the mat. \& \& Mary had a little lamb. \& [% END %] .Ve .PP Output: .PP .Vb 4 \& The cat sat on the mat. \& <br> \& <br> \& Mary had a little lamb. .Ve .SH "html_line_break" .IX Header "html_line_break" This filter replaces any newlines with \f(CW\*(C`<br>\*(C'\fR \s-1HTML\s0 tags, thus preserving the line breaks of the original text in the \&\s-1HTML\s0 output. .PP .Vb 4 \& [% FILTER html_line_break %] \& The cat sat on the mat. \& Mary had a little lamb. \& [% END %] .Ve .PP Output: .PP .Vb 2 \& The cat sat on the mat.<br> \& Mary had a little lamb.<br> .Ve .SH "uri" .IX Header "uri" This filter \s-1URI\s0 escapes the input text, converting any characters outside of the permitted \s-1URI\s0 character set (as defined by \s-1RFC 3986\s0) into a \f(CW%nn\fR hex escape. .PP .Vb 1 \& [% \*(Aqmy file.html\*(Aq | uri %] .Ve .PP Output: .PP .Vb 1 \& my%20file.html .Ve .PP The uri filter correctly encodes all reserved characters, including \&\f(CW\*(C`&\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`/\*(C'\fR, \f(CW\*(C`;\*(C'\fR, \f(CW\*(C`:\*(C'\fR, \f(CW\*(C`=\*(C'\fR, \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`?\*(C'\fR and \f(CW\*(C`$\*(C'\fR. This filter is typically used to encode parameters in a \s-1URL\s0 that could otherwise be interpreted as part of the \s-1URL.\s0 Here's an example: .PP .Vb 5 \& [% path = \*(Aqhttp://tt2.org/example\*(Aq \& back = \*(Aq/other?foo=bar&baz=bam\*(Aq \& title = \*(AqEarth: "Mostly Harmless"\*(Aq \& %] \& <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]"> .Ve .PP The output generated is rather long so we'll show it split across two lines: .PP .Vb 2 \& <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26 \& baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22"> .Ve .PP Without the uri filter the output would look like this (also split across two lines). .PP .Vb 2 \& <a href="http://tt2.org/example?back=/other?foo=bar \& &baz=bam&title=Earth: "Mostly Harmless""> .Ve .PP In this rather contrived example we've manage to generate both a broken \s-1URL\s0 (the repeated \f(CW\*(C`?\*(C'\fR is not allowed) and a broken \s-1HTML\s0 element (the href attribute is terminated by the first \f(CW\*(C`"\*(C'\fR after \f(CW\*(C`Earth: \*(C'\fR leaving \f(CW\*(C`Mostly Harmless"\*(C'\fR dangling on the end of the tag in precisely the way that harmless things shouldn't dangle). So don't do that. Always use the uri filter to encode your \s-1URL\s0 parameters. .PP However, you should \fBnot\fR use the uri filter to encode an entire \s-1URL.\s0 .PP .Vb 1 \& <a href="[% page_url | uri %]"> # WRONG! .Ve .PP This will incorrectly encode any reserved characters like \f(CW\*(C`:\*(C'\fR and \f(CW\*(C`/\*(C'\fR and that's almost certainly not what you want in this case. Instead you should use the \fBurl\fR (note spelling) filter for this purpose. .PP .Vb 1 \& <a href="[% page_url | url %]"> # CORRECT .Ve .PP Please note that this behaviour was changed in version 2.16 of the Template Toolkit. Prior to that, the uri filter did not encode the reserved characters, making it technically incorrect according to the \&\s-1RFC 2396\s0 specification (since superceded by \s-1RFC2732\s0 and \s-1RFC3986\s0). So we fixed it in 2.16 and provided the url filter to implement the old behaviour of not encoding reserved characters. .PP As of version 2.28 of the Template Toolkit, the \f(CW\*(C`uri\*(C'\fR and url filters use the unsafe character set defined by \s-1RFC3986.\s0 This means that certain characters (\*(L"(\*(R", \*(L")\*(R", \*(L"*\*(R", \*(L"!\*(R", \*(L"'\*(R", and '"') are now deemed unsafe and will be escaped as hex character sequences. .PP The ability to use the \s-1RFC3986\s0 character set was added in 2.26 but not enabled by default; double quote was incorrectly deemed safe in 2.26 but correctly escaped in 2.27. .PP If you want to enable the old behaviour then call the \f(CW\*(C`use_rfc2732()\*(C'\fR method in Template::Filters .PP .Vb 2 \& use Template::Filters \& Template::Filters\->use_rfc2732; .Ve .SH "url" .IX Header "url" The url filter is a less aggressive version of the uri filter. It encodes any characters outside of the permitted \s-1URI\s0 character set (as defined by \s-1RFC 2396\s0) into \f(CW%nn\fR hex escapes. However, unlike the uri filter, the url filter does \&\fBnot\fR encode the reserved characters \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`/\*(C'\fR, \f(CW\*(C`;\*(C'\fR, \f(CW\*(C`:\*(C'\fR, \f(CW\*(C`=\*(C'\fR, \f(CW\*(C`+\*(C'\fR, \&\f(CW\*(C`?\*(C'\fR and \f(CW\*(C`$\*(C'\fR. .SH "indent(pad)" .IX Header "indent(pad)" Indents the text block by a fixed pad string or width. The '\f(CW\*(C`pad\*(C'\fR' argument can be specified as a string, or as a numerical value to indicate a pad width (spaces). Defaults to 4 spaces if unspecified. .PP .Vb 4 \& [% FILTER indent(\*(AqME> \*(Aq) %] \& blah blah blah \& cabbages, rhubard, onions \& [% END %] .Ve .PP Output: .PP .Vb 2 \& ME> blah blah blah \& ME> cabbages, rhubard, onions .Ve .SH "truncate(length,dots)" .IX Header "truncate(length,dots)" Truncates the text block to the length specified, or a default length of 32. Truncated text will be terminated with '\f(CW\*(C`...\*(C'\fR' (i.e. the '\f(CW\*(C`...\*(C'\fR' falls inside the required length, rather than appending to it). .PP .Vb 4 \& [% FILTER truncate(21) %] \& I have much to say on this matter that has previously \& been said on more than one occasion. \& [% END %] .Ve .PP Output: .PP .Vb 1 \& I have much to say... .Ve .PP If you want to use something other than '\f(CW\*(C`...\*(C'\fR' you can pass that as a second argument. .PP .Vb 4 \& [% FILTER truncate(26, \*(Aq…\*(Aq) %] \& I have much to say on this matter that has previously \& been said on more than one occasion. \& [% END %] .Ve .PP Output: .PP .Vb 1 \& I have much to say… .Ve .SH "repeat(iterations)" .IX Header "repeat(iterations)" Repeats the text block for as many iterations as are specified (default: 1). .PP .Vb 4 \& [% FILTER repeat(3) %] \& We want more beer and we want more beer, \& [% END %] \& We are the more beer wanters! .Ve .PP Output: .PP .Vb 4 \& We want more beer and we want more beer, \& We want more beer and we want more beer, \& We want more beer and we want more beer, \& We are the more beer wanters! .Ve .SH "remove(string)" .IX Header "remove(string)" Searches the input text for any occurrences of the specified string and removes them. A Perl regular expression may be specified as the search string. .PP .Vb 1 \& [% "The cat sat on the mat" FILTER remove(\*(Aq\es+\*(Aq) %] .Ve .PP Output: .PP .Vb 1 \& Thecatsatonthemat .Ve .SH "replace(search, replace)" .IX Header "replace(search, replace)" Similar to the remove filter described above, but taking a second parameter which is used as a replacement string for instances of the search string. .PP .Vb 1 \& [% "The cat sat on the mat" | replace(\*(Aq\es+\*(Aq, \*(Aq_\*(Aq) %] .Ve .PP Output: .PP .Vb 1 \& The_cat_sat_on_the_mat .Ve .SH "redirect(file, options)" .IX Header "redirect(file, options)" The \f(CW\*(C`redirect\*(C'\fR filter redirects the output of the block into a separate file, specified relative to the \f(CW\*(C`OUTPUT_PATH\*(C'\fR configuration item. .PP .Vb 5 \& [% FOREACH user IN myorg.userlist %] \& [% FILTER redirect("users/${user.id}.html") %] \& [% INCLUDE userinfo %] \& [% END %] \& [% END %] .Ve .PP or more succinctly, using side-effect notation: .PP .Vb 5 \& [% FOREACH user IN myorg.userlist; \& INCLUDE userinfo \& FILTER redirect("users/${user.id}.html"); \& END \& %] .Ve .PP A \f(CW\*(C`file\*(C'\fR exception will be thrown if the \f(CW\*(C`OUTPUT_PATH\*(C'\fR option is undefined. .PP An optional \f(CW\*(C`binmode\*(C'\fR argument can follow the filename to explicitly set the output file to binary mode. .PP .Vb 2 \& [% PROCESS my/png/generator \& FILTER redirect("images/logo.png", binmode=1) %] .Ve .PP For backwards compatibility with earlier versions, a single true/false value can be used to set binary mode. .PP .Vb 2 \& [% PROCESS my/png/generator \& FILTER redirect("images/logo.png", 1) %] .Ve .PP For the sake of future compatibility and clarity, if nothing else, we would strongly recommend you explicitly use the named \f(CW\*(C`binmode\*(C'\fR option as shown in the first example. .SH "eval / evaltt" .IX Header "eval / evaltt" The \f(CW\*(C`eval\*(C'\fR filter evaluates the block as template text, processing any directives embedded within it. This allows template variables to contain template fragments, or for some method to be provided for returning template fragments from an external source such as a database, which can then be processed in the template as required. .PP .Vb 4 \& my $vars = { \& fragment => "The cat sat on the [% place %]", \& }; \& $template\->process($file, $vars); .Ve .PP The following example: .PP .Vb 1 \& [% fragment | eval %] .Ve .PP is therefore equivalent to .PP .Vb 1 \& The cat sat on the [% place %] .Ve .PP The \f(CW\*(C`evaltt\*(C'\fR filter is provided as an alias for \f(CW\*(C`eval\*(C'\fR. .SH "perl / evalperl" .IX Header "perl / evalperl" The \f(CW\*(C`perl\*(C'\fR filter evaluates the block as Perl code. The \f(CW\*(C`EVAL_PERL\*(C'\fR option must be set to a true value or a \f(CW\*(C`perl\*(C'\fR exception will be thrown. .PP .Vb 1 \& [% my_perl_code | perl %] .Ve .PP In most cases, the \f(CW\*(C`[% PERL %]\*(C'\fR ... \f(CW\*(C`[% END %]\*(C'\fR block should suffice for evaluating Perl code, given that template directives are processed before being evaluate as Perl. Thus, the previous example could have been written in the more verbose form: .PP .Vb 3 \& [% PERL %] \& [% my_perl_code %] \& [% END %] .Ve .PP as well as .PP .Vb 3 \& [% FILTER perl %] \& [% my_perl_code %] \& [% END %] .Ve .PP The \f(CW\*(C`evalperl\*(C'\fR filter is provided as an alias for \f(CW\*(C`perl\*(C'\fR for backwards compatibility. .SH "stdout(options)" .IX Header "stdout(options)" The stdout filter prints the output generated by the enclosing block to \&\f(CW\*(C`STDOUT\*(C'\fR. The \f(CW\*(C`binmode\*(C'\fR option can be passed as either a named parameter or a single argument to set \f(CW\*(C`STDOUT\*(C'\fR to binary mode (see the binmode perl function). .PP .Vb 2 \& [% PROCESS something/cool \& FILTER stdout(binmode=1) # recommended %] \& \& [% PROCESS something/cool \& FILTER stdout(1) # alternate %] .Ve .PP The \f(CW\*(C`stdout\*(C'\fR filter can be used to force \f(CW\*(C`binmode\*(C'\fR on \f(CW\*(C`STDOUT\*(C'\fR, or also inside \f(CW\*(C`redirect\*(C'\fR, \f(CW\*(C`null\*(C'\fR or \f(CW\*(C`stderr\*(C'\fR blocks to make sure that particular output goes to \f(CW\*(C`STDOUT\*(C'\fR. See the \f(CW\*(C`null\*(C'\fR filter below for an example. .SH "stderr" .IX Header "stderr" The stderr filter prints the output generated by the enclosing block to \&\f(CW\*(C`STDERR\*(C'\fR. .SH "null" .IX Header "null" The \f(CW\*(C`null\*(C'\fR filter prints nothing. This is useful for plugins whose methods return values that you don't want to appear in the output. Rather than assigning every plugin method call to a dummy variable to silence it, you can wrap the block in a null filter: .PP .Vb 10 \& [% FILTER null; \& USE im = GD.Image(100,100); \& black = im.colorAllocate(0, 0, 0); \& red = im.colorAllocate(255,0, 0); \& blue = im.colorAllocate(0, 0, 255); \& im.arc(50,50,95,75,0,360,blue); \& im.fill(50,50,red); \& im.png | stdout(1); \& END; \& \-%] .Ve .PP Notice the use of the \f(CW\*(C`stdout\*(C'\fR filter to ensure that a particular expression generates output to \f(CW\*(C`STDOUT\*(C'\fR (in this case in binary mode). PK � �[Z4E� � ! man3/Template::Plugin::Scalar.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Scalar 3" .TH Template::Plugin::Scalar 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Scalar \- call object methods in scalar context .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE scalar %] \& \& # TT2 calls object methods in array context by default \& [% object.method %] \& \& # force it to use scalar context \& [% object.scalar.method %] \& \& # also works with subroutine references \& [% scalar.my_sub_ref %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Template Toolkit calls user-defined subroutines and object methods using Perl's array context by default. This plugin module provides a way for you to call subroutines and methods in scalar context. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2008\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[�G�� � man3/Template::Plugin::Wrap.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Wrap 3" .TH Template::Plugin::Wrap 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Wrap \- Plugin interface to Text::Wrap .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE wrap %] \& \& # call wrap subroutine \& [% wrap(mytext, width, initial_tab, subsequent_tab) %] \& \& # or use wrap FILTER \& [% mytext FILTER wrap(width, initital_tab, subsequent_tab) %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin provides an interface to the Text::Wrap module which provides simple paragraph formatting. .PP It defines a \f(CW\*(C`wrap\*(C'\fR subroutine which can be called, passing the input text and further optional parameters to specify the page width (default: 72), and tab characters for the first and subsequent lines (no defaults). .PP .Vb 1 \& [% USE wrap %] \& \& [% text = BLOCK %] \& First, attach the transmutex multiplier to the cross\-wired \& quantum homogeniser. \& [% END %] \& \& [% wrap(text, 40, \*(Aq* \*(Aq, \*(Aq \*(Aq) %] .Ve .PP Output: .PP .Vb 3 \& * First, attach the transmutex \& multiplier to the cross\-wired quantum \& homogeniser. .Ve .PP It also registers a \f(CW\*(C`wrap\*(C'\fR filter which accepts the same three optional arguments but takes the input text directly via the filter input. .PP Example 1: .PP .Vb 4 \& [% FILTER bullet = wrap(40, \*(Aq* \*(Aq, \*(Aq \*(Aq) \-%] \& First, attach the transmutex multiplier to the cross\-wired quantum \& homogeniser. \& [%\- END %] .Ve .PP Output: .PP .Vb 3 \& * First, attach the transmutex \& multiplier to the cross\-wired quantum \& homogeniser. .Ve .PP Example 2: .PP .Vb 4 \& [% FILTER bullet \-%] \& Then remodulate the shield to match the harmonic frequency, taking \& care to correct the phase difference. \& [% END %] .Ve .PP Output: .PP .Vb 3 \& * Then remodulate the shield to match \& the harmonic frequency, taking \& care to correct the phase difference. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .PP The Text::Wrap module was written by David Muir Sharnoff with help from Tim Pierce and many others. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Text::Wrap PK � �["���� � man3/Template::Base.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Base 3" .TH Template::Base 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Base \- Base class module implementing common functionality .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& package My::Module; \& use base qw( Template::Base ); \& \& sub _init { \& my ($self, $config) = @_; \& $self\->{ doodah } = $config\->{ doodah } \& || return $self\->error("No \*(Aqdoodah\*(Aq specified"); \& return $self; \& } \& \& package main; \& \& my $object = My::Module\->new({ doodah => \*(Aqfoobar\*(Aq }) \& || die My::Module\->error(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Base class module which implements a constructor and error reporting functionality for various Template Toolkit modules. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .SS "new(\e%config)" .IX Subsection "new(%config)" Constructor method which accepts a reference to a hash array or a list of \f(CW\*(C`name => value\*(C'\fR parameters which are folded into a hash. The \&\f(CW\*(C`_init()\*(C'\fR method is then called, passing the configuration hash and should return true/false to indicate success or failure. A new object reference is returned, or undef on error. Any error message raised can be examined via the \fBerror()\fR class method or directly via the \f(CW$ERROR\fR package variable in the derived class. .PP .Vb 2 \& my $module = My::Module\->new({ ... }) \& || die My::Module\->error(), "\en"; \& \& my $module = My::Module\->new({ ... }) \& || die "constructor error: $My::Module::ERROR\en"; .Ve .SS "error($msg, ...)" .IX Subsection "error($msg, ...)" May be called as an object method to get/set the internal \f(CW\*(C`_ERROR\*(C'\fR member or as a class method to get/set the \f(CW$ERROR\fR variable in the derived class's package. .PP .Vb 2 \& my $module = My::Module\->new({ ... }) \& || die My::Module\->error(), "\en"; \& \& $module\->do_something() \& || die $module\->error(), "\en"; .Ve .PP When called with parameters (multiple params are concatenated), this method will set the relevant variable and return undef. This is most often used within object methods to report errors to the caller. .PP .Vb 1 \& package My::Module; \& \& sub foobar { \& my $self = shift; \& \& # some other code... \& \& return $self\->error(\*(Aqsome kind of error...\*(Aq) \& if $some_condition; \& } .Ve .SS "debug($msg, ...)" .IX Subsection "debug($msg, ...)" Generates a debugging message by concatenating all arguments passed into a string and printing it to \f(CW\*(C`STDERR\*(C'\fR. A prefix is added to indicate the module of the caller. .PP .Vb 1 \& package My::Module; \& \& sub foobar { \& my $self = shift; \& \& $self\->debug(\*(Aqcalled foobar()\*(Aq); \& \& # some other code... \& } .Ve .PP When the \f(CW\*(C`foobar()\*(C'\fR method is called, the following message is sent to \f(CW\*(C`STDERR\*(C'\fR: .PP .Vb 1 \& [My::Module] called foobar() .Ve .PP Objects can set an internal \f(CW\*(C`DEBUG\*(C'\fR value which the \f(CW\*(C`debug()\*(C'\fR method will examine. If this value sets the relevant bits to indicate \f(CW\*(C`DEBUG_CALLER\*(C'\fR then the file and line number of the caller will be append to the message. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $module = My::Module\->new({ \& DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER, \& }); \& \& $module\->foobar(); .Ve .PP This generates an error message such as: .PP .Vb 1 \& [My::Module] called foobar() at My/Module.pm line 6 .Ve .SS "\fBmodule_version()\fP" .IX Subsection "module_version()" Returns the version number for a module, as defined by the \f(CW$VERSION\fR package variable. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template PK � �[S.ZCE CE % man3/Template::Tutorial::Datafile.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Tutorial::Datafile 3" .TH Template::Tutorial::Datafile 3 "2019-12-23" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tutorial::Datafile \- Creating Data Output Files Using the Template Toolkit .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SH "Introducing the Template Toolkit" .IX Header "Introducing the Template Toolkit" There are a number of Perl modules that are universally recognised as The Right Thing To Use for certain tasks. If you accessed a database without using \s-1DBI,\s0 pulled data from the \s-1WWW\s0 without using one of the \s-1LWP\s0 modules or parsed \s-1XML\s0 without using XML::Parser or one of its subclasses then you'd run the risk of being shunned by polite Perl society. .PP I believe that the year 2000 saw the emergence of another 'must have' Perl module \- the Template Toolkit. I don't think I'm alone in this belief as the Template Toolkit won the 'Best New Module' award at the Perl Conference last summer. Version 2.0 of the Template Toolkit (known as \s-1TT2\s0 to its friends) was recently released to the \s-1CPAN.\s0 .PP \&\s-1TT2\s0 was designed and written by Andy Wardley <abw@wardley.org>. It was born out of Andy's previous templating module, Text::Metatext, in best Fred Brooks 'plan to throw one away' manner; and aims to be the most useful (or, at least, the most \&\fIused\fR) Perl templating system. .PP \&\s-1TT2\s0 provides a way to take a file of fixed boilerplate text (the template) and embed variable data within it. One obvious use of this is in the creation of dynamic web pages and this is where a lot of the attention that \s-1TT2\s0 has received has been focussed. In this article, I hope to demonstrate that \s-1TT2\s0 is just as useful in non-web applications. .SH "Using the Template Toolkit" .IX Header "Using the Template Toolkit" Let's look at how we'd use \s-1TT2\s0 to process a simple data file. \&\s-1TT2\s0 is an object oriented Perl module. Having downloaded it from \&\s-1CPAN\s0 and installed it in the usual manner, using it in your program is as easy as putting the lines .PP .Vb 2 \& use Template; \& my $tt = Template\->new; .Ve .PP in your code. The constructor function, \f(CW\*(C`new\*(C'\fR, takes a number of optional parameters which are documented in the copious manual pages that come with the module, but for the purposes of this article we'll keep things as simple as possible. .PP To process the template, you would call the \f(CW\*(C`process\*(C'\fR method like this .PP .Vb 2 \& $tt\->process(\*(Aqmy_template\*(Aq, \e%data) \& || die $tt\->error; .Ve .PP We pass two parameters to \f(CW\*(C`process\*(C'\fR, the first is the name of the file containing the template to process (in this case, my_template) and the second is a reference to a hash which contains the data items that you want to use in the template. If processing the template gives any kind of error, the program will die with a (hopefully) useful error message. .PP So what kinds of things can go in \f(CW%data\fR? The answer is just about anything. Here's an example showing data about English Premier League football teams. .PP .Vb 10 \& my @teams = ({ name => \*(AqMan Utd\*(Aq, \& played => 16, \& won => 12, \& drawn => 3, \& lost => 1 }, \& { name => \*(AqBradford\*(Aq, \& played => 16, \& won => 2, \& drawn => 5, \& lost => 9 }); \& \& my %data = ( name => \*(AqEnglish Premier League\*(Aq, \& season => \*(Aq2000/01\*(Aq, \& teams => \e@teams ); .Ve .PP This creates three data items which can be accessed within the template, called \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`season\*(C'\fR and \f(CW\*(C`teams\*(C'\fR. Notice that \&\f(CW\*(C`teams\*(C'\fR is a complex data structure. .PP Here is a template that we might use to process this data. .PP .Vb 1 \& League Standings \& \& League Name: [% name %] \& Season : [% season %] \& \& Teams: \& [% FOREACH team = teams \-%] \& [% team.name %] [% team.played \-%] \& [% team.won %] [% team.drawn %] [% team.lost %] \& [% END %] .Ve .PP Running this template with this data gives us the following output .PP .Vb 1 \& League Standings \& \& League Name: English Premier League \& Season : 2000/01 \& \& Teams: \& Man Utd 16 12 3 1 \& Bradford 16 2 5 9 .Ve .PP Hopefully the syntax of the template is simple enough to follow. There are a few points to note. .IP "\(bu" 4 Template processing directives are written using a simple language which is not Perl. .IP "\(bu" 4 The keys of the \f(CW%data\fR have become the names of the data variables within the template. .IP "\(bu" 4 Template processing directives are surrounded by \f(CW\*(C`[%\*(C'\fR and \&\f(CW\*(C`%]\*(C'\fR sequences. .IP "\(bu" 4 If these tags are replaced with \f(CW\*(C`[%\-\*(C'\fR \f(CW\*(C`\-%]\*(C'\fR then the preceding or following linefeed is suppressed. .IP "\(bu" 4 In the \f(CW\*(C`FOREACH\*(C'\fR loop, each element of the \f(CW\*(C`teams\*(C'\fR list was assigned, in turn, to the temporary variable \f(CW\*(C`team\*(C'\fR. .IP "\(bu" 4 Each item assigned to the \f(CW\*(C`team\*(C'\fR variable is a Perl hash. Individual values within the hash are accessed using a dot notation. .PP It's probably the first and last of these points which are the most important. The first point emphasises the separation of the data acquisition logic from the presentation logic. The person creating the presentation template doesn't need to know Perl, they only need to know the data items which will be passed into the template. .PP The last point demonstrates the way that \s-1TT2\s0 protects the template designer from the implementation of the data structures. The data objects passed to the template processor can be scalars, arrays, hashes, objects or even subroutines. The template processor will just interpret your data correctly and Do The Right Thing to return the correct value to you. In this example each team was a hash, but in a larger system each team might be an object, in which case \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`played\*(C'\fR, etc. would be accessor methods to the underlying object attributes. No changes would be required to the template as the template processor would realise that it needed to call methods rather than access hash values. .SS "A more complex example" .IX Subsection "A more complex example" Stats about the English Football League are usually presented in a slightly more complex format than the one we used above. A full set of stats will show the number of games that a team has won, lost or drawn, the number of goals scored for and against the team and the number of points that the team therefore has. Teams gain three points for a win and one point for a draw. When teams have the same number of points they are separated by the goal difference, that is the number of goals the team has scored minus the number of team scored against them. To complicate things even further, the games won, drawn and lost and the goals for and against are often split between home and away games. .PP Therefore if you have a data source which lists the team name together with the games won, drawn and lost and the goals for and against split into home and away (a total of eleven data items) you can calculate all of the other items (goal difference, points awarded and even position in the league). Let's take such a file, but we'll only look at the top three teams. It will look something like this: .PP .Vb 3 \& Man Utd,7,1,0,26,4,5,2,1,15,6 \& Arsenal,7,1,0,17,4,2,3,3,7,9 \& Leicester,4,3,1,10,8,4,2,2,7,4 .Ve .PP A simple script to read this data into an array of hashes will look something like this (I've simplified the names of the data columns \- w, d, and l are games won, drawn and lost and f and a are goals scored for and against; h and a at the front of a data item name indicates whether it's a home or away statistic): .PP .Vb 1 \& my @cols = qw(name hw hd hl hf ha aw ad al af aa); \& \& my @teams; \& while (<>) { \& chomp; \& \& my %team; \& \& @team{@cols} = split /,/; \& \& push @teams, \e%team; \& } .Ve .PP We can then go thru the teams again and calculate all of the derived data items: .PP .Vb 4 \& foreach (@teams) { \& $_\->{w} = $_\->{hw} + $_\->{aw}; \& $_\->{d} = $_\->{hd} + $_\->{ad}; \& $_\->{l} = $_\->{hl} + $_\->{al}; \& \& $_\->{pl} = $_\->{w} + $_\->{d} + $_\->{l}; \& \& $_\->{f} = $_\->{hf} + $_\->{af}; \& $_\->{a} = $_\->{ha} + $_\->{aa}; \& \& $_\->{gd} = $_\->{f} \- $_\->{a}; \& $_\->{pt} = (3 * $_\->{w}) + $_\->{d}; \& } .Ve .PP And then produce a list sorted in descending order: .PP .Vb 3 \& @teams = sort { \& $b\->{pt} <=> $b\->{pt} || $b\->{gd} <=> $a\->{gd} \& } @teams; .Ve .PP And finally add the league position data item: .PP .Vb 2 \& $teams[$_]\->{pos} = $_ + 1 \& foreach 0 .. $#teams; .Ve .PP Having pulled all of our data into an internal data structure we can start to produce output using out templates. A template to create a \s-1CSV\s0 file containing the data split between home and away stats would look like this: .PP .Vb 6 \& [% FOREACH team = teams \-%] \& [% team.pos %],[% team.name %],[% team.pl %],[% team.hw %], \& [%\- team.hd %],[% team.hl %],[% team.hf %],[% team.ha %], \& [%\- team.aw %],[% team.ad %],[% team.al %],[% team.af %], \& [%\- team.aa %],[% team.gd %],[% team.pt %] \& [%\- END %] .Ve .PP And processing it like this: .PP .Vb 2 \& $tt\->process(\*(Aqsplit.tt\*(Aq, { teams => \e@teams }, \*(Aqsplit.csv\*(Aq) \& || die $tt\->error; .Ve .PP produces the following output: .PP .Vb 3 \& 1,Man Utd,16,7,1,0,26,4,5,2,1,15,6,31,39 \& 2,Arsenal,16,7,1,0,17,4,2,3,3,7,9,11,31 \& 3,Leicester,16,4,3,1,10,8,4,2,2,7,4,5,29 .Ve .PP Notice that we've introduced the third parameter to \f(CW\*(C`process\*(C'\fR. If this parameter is missing then the \s-1TT2\s0 sends its output to \&\f(CW\*(C`STDOUT\*(C'\fR. If this parameter is a scalar then it is taken as the name of a file to write the output to. This parameter can also be (amongst other things) a filehandle or a reference to an object which is assumed to implement a \f(CW\*(C`print\*(C'\fR method. .PP If we weren't interested in the split between home and away games, then we could use a simpler template like this: .PP .Vb 5 \& [% FOREACH team = teams \-%] \& [% team.pos %],[% team.name %],[% team.pl %],[% team.w %], \& [%\- team.d %],[% team.l %],[% team.f %],[% team.a %], \& [%\- team.aa %],[% team.gd %],[% team.pt %] \& [% END \-%] .Ve .PP Which would produce output like this: .PP .Vb 3 \& 1,Man Utd,16,12,3,1,41,10,6,31,39 \& 2,Arsenal,16,9,4,3,24,13,9,11,31 \& 3,Leicester,16,8,5,3,17,12,4,5,29 .Ve .SH "Producing XML" .IX Header "Producing XML" This is starting to show some of the power and flexibility of \&\s-1TT2,\s0 but you may be thinking that you could just as easily produce this output with a \f(CW\*(C`foreach\*(C'\fR loop and a couple of \f(CW\*(C`print\*(C'\fR statements in your code. This is, of course, true; but that's because I've chosen a deliberately simple example to explain the concepts. What if we wanted to produce an \s-1XML\s0 file containing the data? And what if (as I mentioned earlier) the league data was held in an object? The code would then look even easier as most of the code we've written earlier would be hidden away in \f(CW\*(C`FootballLeague.pm\*(C'\fR. .PP .Vb 2 \& use FootballLeague; \& use Template; \& \& my $league = FootballLeague\->new(name => \*(AqEnglish Premier\*(Aq); \& \& my $tt = Template\->new; \& \& $tt\->process(\*(Aqleague_xml.tt\*(Aq, { league => $league }) \& || die $tt\->error; .Ve .PP And the template in \f(CW\*(C`league_xml.tt\*(C'\fR would look something like this: .PP .Vb 2 \& <?xml version="1.0"?> \& <!DOCTYPE LEAGUE SYSTEM "league.dtd"> \& \& <league name="[% league.name %]" season="[% league.season %]"> \& [% FOREACH team = league.teams \-%] \& <team name="[% team.name %]" \& pos="[% team.pos %]" \& played="[% team.pl %]" \& goal_diff="[% team.gd %]" \& points="[% team.pt %]"> \& <stats type="home"> \& win="[% team.hw %]" \& draw="[%\- team.hd %]" \& lose="[% team.hl %]" \& for="[% team.hf %]" \& against="[% team.ha %]" /> \& <stats type="away"> \& win="[% team.aw %]" \& draw="[%\- team.ad %]" \& lose="[% team.al %]" \& for="[% team.af %]" \& against="[% team.aa %]" /> \& </team> \& [% END \-%] \& &/league> .Ve .PP Notice that as we've passed the whole object into \f(CW\*(C`process\*(C'\fR then we need to put an extra level of indirection on our template variables \- everything is now a component of the \f(CW\*(C`league\*(C'\fR variable. Other than that, everything in the template is very similar to what we've used before. Presumably now \f(CW\*(C`team.name\*(C'\fR calls an accessor function rather than carrying out a hash lookup, but all of this is transparent to our template designer. .SH "Multiple Formats" .IX Header "Multiple Formats" As a final example, let's suppose that we need to create output football league tables in a number of formats. Perhaps we are passing this data on to other people and they can't all use the same format. Some of our users need \s-1CSV\s0 files and others need \&\s-1XML.\s0 Some require data split between home and away matches and other just want the totals. In total, then, we'll need four different templates, but the good news is that they can use the same data object. All the script needs to do is to establish which template is required and process it. .PP .Vb 2 \& use FootballLeague; \& use Template; \& \& my ($name, $type, $stats) = @_; \& \& my $league = FootballLeague\->new(name => $name); \& \& my $tt = Template\->new; \& \& $tt\->process("league_${type}_$stats.tt", \& { league => $league } \& "league_$stats.$type") \& || die $tt\->error; .Ve .PP For example, you can call this script as .PP .Vb 1 \& league.pl \*(AqEnglish Premier\*(Aq xml split .Ve .PP This will process a template called \f(CW\*(C`league_xml_split.tt\*(C'\fR and put the results in a file called \f(CW\*(C`league_split.xml\*(C'\fR. .PP This starts to show the true strength of the Template Toolkit. If we later wanted to add another file format \- perhaps we wanted to create a league table \s-1HTML\s0 page or even a LaTeX document \- then we would just need to create the appropriate template and name it according to our existing naming convention. We would need to make no changes to the code. .PP I hope you can now see why the Template Toolkit is fast becoming an essential part of many people's Perl installation. .SH "AUTHOR" .IX Header "AUTHOR" Dave Cross <dave@dave.org.uk> .SH "VERSION" .IX Header "VERSION" Template Toolkit version 2.19, released on 27 April 2007. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2001 Dave Cross <dave@dave.org.uk> .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[-5SK�9 �9 man3/Template::Tools::ttree.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Tools::ttree 3" .TH Template::Tools::ttree 3 "2019-12-23" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tools::ttree \- Process entire directory trees of templates .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& ttree [options] [files] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fIttree\fR script is used to process entire directory trees containing template files. The resulting output from processing each file is then written to a corresponding file in a destination directory. The script compares the modification times of source and destination files (where they already exist) and processes only those files that have been modified. In other words, it is the equivalent of 'make' for the Template Toolkit. .PP It supports a number of options which can be used to configure behaviour, define locations and set Template Toolkit options. The script first reads the \fI.ttreerc\fR configuration file in the \s-1HOME\s0 directory, or an alternative file specified in the \s-1TTREERC\s0 environment variable. Then, it processes any command line arguments, including any additional configuration files specified via the \f(CW\*(C`\-f\*(C'\fR (file) option. .SS "The \fI.ttreerc\fP Configuration File" .IX Subsection "The .ttreerc Configuration File" When you run \fIttree\fR for the first time it will ask you if you want it to create a \fI.ttreerc\fR file for you. This will be created in your home directory. .PP .Vb 4 \& $ ttree \& Do you want me to create a sample \*(Aq.ttreerc\*(Aq file for you? \& (file: /home/abw/.ttreerc) [y/n]: y \& /home/abw/.ttreerc created. Please edit accordingly and re\-run ttree .Ve .PP The purpose of this file is to set any \fIglobal\fR configuration options that you want applied \fIevery\fR time \fIttree\fR is run. For example, you can use the \f(CW\*(C`ignore\*(C'\fR and \f(CW\*(C`copy\*(C'\fR option to provide regular expressions that specify which files should be ignored and which should be copied rather than being processed as templates. You may also want to set flags like \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`recurse\*(C'\fR according to your preference. .PP A minimal \fI.ttreerc\fR: .PP .Vb 4 \& # ignore these files \& ignore = \eb(CVS|RCS)\eb \& ignore = ^# \& ignore = ~$ \& \& # copy these files \& copy = \e.(gif|png|jpg|pdf)$ \& \& # recurse into directories \& recurse \& \& # provide info about what\*(Aqs going on \& verbose .Ve .PP In most cases, you'll want to create a different \fIttree\fR configuration file for each project you're working on. The \f(CW\*(C`cfg\*(C'\fR option allows you to specify a directory where \fIttree\fR can find further configuration files. .PP .Vb 1 \& cfg = /home/abw/.ttree .Ve .PP The \f(CW\*(C`\-f\*(C'\fR command line option can be used to specify which configuration file should be used. You can specify a filename using an absolute or relative path: .PP .Vb 3 \& $ ttree \-f /home/abw/web/example/etc/ttree.cfg \& $ ttree \-f ./etc/ttree.cfg \& $ ttree \-f ../etc/ttree.cfg .Ve .PP If the configuration file does not begin with \f(CW\*(C`/\*(C'\fR or \f(CW\*(C`.\*(C'\fR or something that looks like a MS-DOS absolute path (e.g. \f(CW\*(C`C:\e\eetc\e\ettree.cfg\*(C'\fR) then \&\fIttree\fR will look for it in the directory specified by the \f(CW\*(C`cfg\*(C'\fR option. .PP .Vb 1 \& $ ttree \-f test1 # /home/abw/.ttree/test1 .Ve .PP The \f(CW\*(C`cfg\*(C'\fR option can only be used in the \fI.ttreerc\fR file. All the other options can be used in the \fI.ttreerc\fR or any other \fIttree\fR configuration file. They can all also be specified as command line options. .PP Remember that \fI.ttreerc\fR is always processed \fIbefore\fR any configuration file specified with the \f(CW\*(C`\-f\*(C'\fR option. Certain options like \f(CW\*(C`lib\*(C'\fR can be used any number of times and accumulate their values. .PP For example, consider the following configuration files: .PP \&\fI/home/abw/.ttreerc\fR: .PP .Vb 2 \& cfg = /home/abw/.ttree \& lib = /usr/local/tt2/templates .Ve .PP \&\fI/home/abw/.ttree/myconfig\fR: .PP .Vb 1 \& lib = /home/abw/web/example/templates/lib .Ve .PP When \fIttree\fR is invoked as follows: .PP .Vb 1 \& $ ttree \-f myconfig .Ve .PP the \f(CW\*(C`lib\*(C'\fR option will be set to the following directories: .PP .Vb 2 \& /usr/local/tt2/templates \& /home/abw/web/example/templates/lib .Ve .PP Any templates located under \fI/usr/local/tt2/templates\fR will be used in preference to those located under \&\fI/home/abw/web/example/templates/lib\fR. This may be what you want, but then again, it might not. For this reason, it is good practice to keep the \fI.ttreerc\fR as simple as possible and use different configuration files for each \fIttree\fR project. .SS "Directory Options" .IX Subsection "Directory Options" The \f(CW\*(C`src\*(C'\fR option is used to define the directory containing the source templates to be processed. It can be provided as a command line option or in a configuration file as shown here: .PP .Vb 1 \& src = /home/abw/web/example/templates/src .Ve .PP Each template in this directory typically corresponds to a single web page or other document. .PP The \f(CW\*(C`dest\*(C'\fR option is used to specify the destination directory for the generated output. .PP .Vb 1 \& dest = /home/abw/web/example/html .Ve .PP The \f(CW\*(C`lib\*(C'\fR option is used to define one or more directories containing additional library templates. These templates are not documents in their own right and typically comprise of smaller, modular components like headers, footers and menus that are incorporated into pages templates. .PP .Vb 2 \& lib = /home/abw/web/example/templates/lib \& lib = /usr/local/tt2/templates .Ve .PP The \f(CW\*(C`lib\*(C'\fR option can be used repeatedly to add further directories to the search path. .PP A list of templates can be passed to \fIttree\fR as command line arguments. .PP .Vb 1 \& $ ttree foo.html bar.html .Ve .PP It looks for these templates in the \f(CW\*(C`src\*(C'\fR directory and processes them through the Template Toolkit, using any additional template components from the \f(CW\*(C`lib\*(C'\fR directories. The generated output is then written to the corresponding file in the \f(CW\*(C`dest\*(C'\fR directory. .PP If \fIttree\fR is invoked without explicitly specifying any templates to be processed then it will process every file in the \f(CW\*(C`src\*(C'\fR directory. If the \f(CW\*(C`\-r\*(C'\fR (recurse) option is set then it will additionally iterate down through sub-directories and process and other template files it finds therein. .PP .Vb 1 \& $ ttree \-r .Ve .PP If a template has been processed previously, \fIttree\fR will compare the modification times of the source and destination files. If the source template (or one it is dependant on) has not been modified more recently than the generated output file then \fIttree\fR will not process it. The \fI\-a\fR (all) option can be used to force \fIttree\fR to process all files regardless of modification time. .PP .Vb 1 \& $ ttree \-a .Ve .PP Any templates explicitly named as command line argument are always processed and the modification time checking is bypassed. .SS "File Options" .IX Subsection "File Options" The \f(CW\*(C`ignore\*(C'\fR, \f(CW\*(C`copy\*(C'\fR and \f(CW\*(C`accept\*(C'\fR options are used to specify Perl regexen to filter file names. Files that match any of the \f(CW\*(C`ignore\*(C'\fR options will not be processed. Remaining files that match any of the \&\f(CW\*(C`copy\*(C'\fR regexen will be copied to the destination directory. Remaining files that then match any of the \f(CW\*(C`accept\*(C'\fR criteria are then processed via the Template Toolkit. If no \f(CW\*(C`accept\*(C'\fR parameter is specified then all files will be accepted for processing if not already copied or ignored. .PP .Vb 4 \& # ignore these files \& ignore = \eb(CVS|RCS)\eb \& ignore = ^# \& ignore = ~$ \& \& # copy these files \& copy = \e.(gif|png|jpg|pdf)$ \& \& # accept only .tt2 templates \& accept = \e.tt2$ .Ve .PP The \f(CW\*(C`suffix\*(C'\fR option is used to define mappings between the file extensions for source templates and the generated output files. The following example specifies that source templates with a \f(CW\*(C`.tt2\*(C'\fR suffix should be output as \f(CW\*(C`.html\*(C'\fR files: .PP .Vb 1 \& suffix tt2=html .Ve .PP Or on the command line, .PP .Vb 1 \& \-\-suffix tt2=html .Ve .PP You can provide any number of different suffix mappings by repeating this option. .SS "Template Dependencies" .IX Subsection "Template Dependencies" The \f(CW\*(C`depend\*(C'\fR and \f(CW\*(C`depend_file\*(C'\fR options allow you to specify how any given template file depends on another file or group of files. The \f(CW\*(C`depend\*(C'\fR option is used to express a single dependency. .PP .Vb 1 \& $ ttree \-\-depend foo=bar,baz .Ve .PP This command line example shows the \f(CW\*(C`\-\-depend\*(C'\fR option being used to specify that the \fIfoo\fR file is dependant on the \fIbar\fR and \fIbaz\fR templates. This option can be used many time on the command line: .PP .Vb 1 \& $ ttree \-\-depend foo=bar,baz \-\-depend crash=bang,wallop .Ve .PP or in a configuration file: .PP .Vb 2 \& depend foo=bar,baz \& depend crash=bang,wallop .Ve .PP The file appearing on the left of the \f(CW\*(C`=\*(C'\fR is specified relative to the \f(CW\*(C`src\*(C'\fR or \f(CW\*(C`lib\*(C'\fR directories. The file(s) appearing on the right can be specified relative to any of these directories or as absolute file paths. .PP For example: .PP .Vb 1 \& $ ttree \-\-depend foo=bar,/tmp/baz .Ve .PP To define a dependency that applies to all files, use \f(CW\*(C`*\*(C'\fR on the left of the \f(CW\*(C`=\*(C'\fR. .PP .Vb 1 \& $ ttree \-\-depend *=header,footer .Ve .PP or in a configuration file: .PP .Vb 1 \& depend *=header,footer .Ve .PP Any templates that are defined in the \f(CW\*(C`pre_process\*(C'\fR, \f(CW\*(C`post_process\*(C'\fR, \&\f(CW\*(C`process\*(C'\fR or \f(CW\*(C`wrapper\*(C'\fR options will automatically be added to the list of global dependencies that apply to all templates. .PP The \f(CW\*(C`depend_file\*(C'\fR option can be used to specify a file that contains dependency information. .PP .Vb 1 \& $ ttree \-\-depend_file=/home/abw/web/example/etc/ttree.dep .Ve .PP Here is an example of a dependency file: .PP .Vb 1 \& # This is a comment. It is ignored. \& \& index.html: header footer menubar \& \& header: titlebar hotlinks \& \& menubar: menuitem \& \& # spanning multiple lines with the backslash \& another.html: header footer menubar \e \& sidebar searchform .Ve .PP Lines beginning with the \f(CW\*(C`#\*(C'\fR character are comments and are ignored. Blank lines are also ignored. All other lines should provide a filename followed by a colon and then a list of dependant files separated by whitespace, commas or both. Whitespace around the colon is also optional. Lines ending in the \f(CW\*(C`\e\*(C'\fR character are continued onto the following line. .PP Files that contain spaces can be quoted. That is only necessary for files after the colon (':'). The file before the colon may be quoted if it contains a colon. .PP As with the command line options, the \f(CW\*(C`*\*(C'\fR character can be used as a wildcard to specify a dependency for all templates. .PP .Vb 1 \& * : config,header .Ve .SS "Template Toolkit Options" .IX Subsection "Template Toolkit Options" \&\fIttree\fR also provides access to the usual range of Template Toolkit options. For example, the \f(CW\*(C`\-\-pre_chomp\*(C'\fR and \f(CW\*(C`\-\-post_chomp\*(C'\fR \fIttree\fR options correspond to the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR options. .PP Run \f(CW\*(C`ttree \-h\*(C'\fR for a summary of the options available. .SH "AUTHORS" .IX Header "AUTHORS" Andy Wardley <abw@wardley.org> .PP <http://www.wardley.org> .PP With contributions from Dylan William Hardison (support for dependencies), Bryce Harrington (\f(CW\*(C`absolute\*(C'\fR and \f(CW\*(C`relative\*(C'\fR options), Mark Anderson (\f(CW\*(C`suffix\*(C'\fR and \f(CW\*(C`debug\*(C'\fR options), Harald Joerg and Leon Brocard who gets everywhere, it seems. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Tools::tpage PK � �[W�72 72 man3/Template::Provider.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Provider 3" .TH Template::Provider 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Provider \- Provider module for loading/compiling templates .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& $provider = Template::Provider\->new(\e%options); \& \& ($template, $error) = $provider\->fetch($name); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Template::Provider is used to load, parse, compile and cache template documents. This object may be sub-classed to provide more specific facilities for loading, or otherwise providing access to templates. .PP The Template::Context objects maintain a list of Template::Provider objects which are polled in turn (via \fBfetch()\fR) to return a requested template. Each may return a compiled template, raise an error, or decline to serve the request, giving subsequent providers a chance to do so. .PP The Template::Provider can also be subclassed to provide templates from a different source, e.g. a database. See \s-1SUBCLASSING\s0 below. .PP This documentation needs work. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .SS "new(\e%options)" .IX Subsection "new(%options)" Constructor method which instantiates and returns a new \f(CW\*(C`Template::Provider\*(C'\fR object. A reference to a hash array of configuration options may be passed. .PP See \*(L"\s-1CONFIGURATION OPTIONS\*(R"\s0 below for a summary of configuration options and Template::Manual::Config for full details. .SS "fetch($name)" .IX Subsection "fetch($name)" Returns a compiled template for the name specified. If the template cannot be found then \f(CW\*(C`(undef, STATUS_DECLINED)\*(C'\fR is returned. If an error occurs (e.g. read error, parse error) then \f(CW\*(C`($error, STATUS_ERROR)\*(C'\fR is returned, where \&\f(CW$error\fR is the error message generated. If the \s-1TOLERANT\s0 option is set the the method returns \f(CW\*(C`(undef, STATUS_DECLINED)\*(C'\fR instead of returning an error. .SS "load($name)" .IX Subsection "load($name)" Loads a template without parsing or compiling it. This is used by the the \s-1INSERT\s0 directive. .ie n .SS "store($name, $template)" .el .SS "store($name, \f(CW$template\fP)" .IX Subsection "store($name, $template)" Stores the compiled template, \f(CW$template\fR, in the cache under the name, \&\f(CW$name\fR. Susbequent calls to \f(CW\*(C`fetch($name)\*(C'\fR will return this template in preference to any disk-based file. .SS "include_path(\e@newpath)" .IX Subsection "include_path(@newpath)" Accessor method for the \f(CW\*(C`INCLUDE_PATH\*(C'\fR setting. If called with an argument, this method will replace the existing \f(CW\*(C`INCLUDE_PATH\*(C'\fR with the new value. .SS "\fBpaths()\fP" .IX Subsection "paths()" This method generates a copy of the \f(CW\*(C`INCLUDE_PATH\*(C'\fR list. Any elements in the list which are dynamic generators (e.g. references to subroutines or objects implementing a \f(CW\*(C`paths()\*(C'\fR method) will be called and the list of directories returned merged into the output list. .PP It is possible to provide a generator which returns itself, thus sending this method into an infinite loop. To detect and prevent this from happening, the \f(CW$MAX_DIRS\fR package variable, set to \f(CW64\fR by default, limits the maximum number of paths that can be added to, or generated for the output list. If this number is exceeded then the method will immediately return an error reporting as much. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" The following list summarises the configuration options that can be provided to the \f(CW\*(C`Template::Provider\*(C'\fR \fBnew()\fR constructor. Please consult Template::Manual::Config for further details and examples of each configuration option in use. .SS "\s-1INCLUDE_PATH\s0" .IX Subsection "INCLUDE_PATH" The \s-1INCLUDE_PATH\s0 option is used to specify one or more directories in which template files are located. .PP .Vb 4 \& # single path \& my $provider = Template::Provider\->new({ \& INCLUDE_PATH => \*(Aq/usr/local/templates\*(Aq, \& }); \& \& # multiple paths \& my $provider = Template::Provider\->new({ \& INCLUDE_PATH => [ \*(Aq/usr/local/templates\*(Aq, \& \*(Aq/tmp/my/templates\*(Aq ], \& }); .Ve .SS "\s-1ABSOLUTE\s0" .IX Subsection "ABSOLUTE" The \s-1ABSOLUTE\s0 flag is used to indicate if templates specified with absolute filenames (e.g. '\f(CW\*(C`/foo/bar\*(C'\fR') should be processed. It is disabled by default and any attempt to load a template by such a name will cause a '\f(CW\*(C`file\*(C'\fR' exception to be raised. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& ABSOLUTE => 1, \& }); .Ve .SS "\s-1RELATIVE\s0" .IX Subsection "RELATIVE" The \s-1RELATIVE\s0 flag is used to indicate if templates specified with filenames relative to the current directory (e.g. \&\f(CW\*(C`./foo/bar\*(C'\fR or \f(CW\*(C`../../some/where/else\*(C'\fR) should be loaded. It is also disabled by default, and will raise a \f(CW\*(C`file\*(C'\fR error if such template names are encountered. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& RELATIVE => 1, \& }); .Ve .SS "\s-1DEFAULT\s0" .IX Subsection "DEFAULT" The \s-1DEFAULT\s0 option can be used to specify a default template which should be used whenever a specified template can't be found in the \s-1INCLUDE_PATH\s0. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& DEFAULT => \*(Aqnotfound.html\*(Aq, \& }); .Ve .PP If a non-existant template is requested through the Template \&\fBprocess()\fR method, or by an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \&\f(CW\*(C`WRAPPER\*(C'\fR directive, then the \f(CW\*(C`DEFAULT\*(C'\fR template will instead be processed, if defined. Note that the \f(CW\*(C`DEFAULT\*(C'\fR template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string. .SS "\s-1ENCODING\s0" .IX Subsection "ENCODING" The Template Toolkit will automatically decode Unicode templates that have a Byte Order Marker (\s-1BOM\s0) at the start of the file. This option can be used to set the default encoding for templates that don't define a \s-1BOM.\s0 .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& ENCODING => \*(Aqutf8\*(Aq, \& }); .Ve .PP See Encode for further information. .SS "\s-1CACHE_SIZE\s0" .IX Subsection "CACHE_SIZE" The \s-1CACHE_SIZE\s0 option can be used to limit the number of compiled templates that the module should cache. By default, the \s-1CACHE_SIZE\s0 is undefined and all compiled templates are cached. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& CACHE_SIZE => 64, # only cache 64 compiled templates \& }); .Ve .SS "\s-1STAT_TTL\s0" .IX Subsection "STAT_TTL" The \s-1STAT_TTL\s0 value can be set to control how long the \f(CW\*(C`Template::Provider\*(C'\fR will keep a template cached in memory before checking to see if the source template has changed. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& STAT_TTL => 60, # one minute \& }); .Ve .SS "\s-1COMPILE_EXT\s0" .IX Subsection "COMPILE_EXT" The \s-1COMPILE_EXT\s0 option can be provided to specify a filename extension for compiled template files. It is undefined by default and no attempt will be made to read or write any compiled template files. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& COMPILE_EXT => \*(Aq.ttc\*(Aq, \& }); .Ve .SS "\s-1COMPILE_DIR\s0" .IX Subsection "COMPILE_DIR" The \s-1COMPILE_DIR\s0 option is used to specify an alternate directory root under which compiled template files should be saved. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& COMPILE_DIR => \*(Aq/tmp/ttc\*(Aq, \& }); .Ve .SS "\s-1TOLERANT\s0" .IX Subsection "TOLERANT" The \s-1TOLERANT\s0 flag can be set to indicate that the \f(CW\*(C`Template::Provider\*(C'\fR module should ignore any errors encountered while loading a template and instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR. .SS "\s-1PARSER\s0" .IX Subsection "PARSER" The \s-1PARSER\s0 option can be used to define a parser module other than the default of Template::Parser. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& PARSER => MyOrg::Template::Parser\->new({ ... }), \& }); .Ve .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \s-1DEBUG\s0 option can be used to enable debugging messages from the Template::Provider module by setting it to include the \f(CW\*(C`DEBUG_PROVIDER\*(C'\fR value. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_PROVIDER, \& }); .Ve .SH "SUBCLASSING" .IX Header "SUBCLASSING" The \f(CW\*(C`Template::Provider\*(C'\fR module can be subclassed to provide templates from a different source (e.g. a database). In most cases you'll just need to provide custom implementations of the \f(CW\*(C`_template_modified()\*(C'\fR and \f(CW\*(C`_template_content()\*(C'\fR methods. If your provider requires and custom initialisation then you'll also need to implement a new \f(CW\*(C`_init()\*(C'\fR method. .PP Caching in memory and on disk will still be applied (if enabled) when overriding these methods. .SS "_template_modified($path)" .IX Subsection "_template_modified($path)" Returns a timestamp of the \f(CW$path\fR passed in by calling \f(CW\*(C`stat()\*(C'\fR. This can be overridden, for example, to return a last modified value from a database. The value returned should be a timestamp value (as returned by \f(CW\*(C`time()\*(C'\fR, although a sequence number should work as well. .SS "_template_content($path)" .IX Subsection "_template_content($path)" This method returns the content of the template for all \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR, and \f(CW\*(C`INSERT\*(C'\fR directives. .PP When called in scalar context, the method returns the content of the template located at \f(CW$path\fR, or \f(CW\*(C`undef\*(C'\fR if \f(CW$path\fR is not found. .PP When called in list context it returns \f(CW\*(C`($content, $error, $mtime)\*(C'\fR, where \f(CW$content\fR is the template content, \f(CW$error\fR is an error string (e.g. "\f(CW\*(C`$path: File not found\*(C'\fR"), and \f(CW$mtime\fR is the template modification time. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Parser, Template::Context PK � �[�@]�� � man3/Template::Tutorial.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Tutorial 3" .TH Template::Tutorial 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tutorial \- Template Toolkit Tutorials .SH "Template Toolkit Tutorials" .IX Header "Template Toolkit Tutorials" .SS "Template::Tutorial::Web" .IX Subsection "Template::Tutorial::Web" The Template::Tutorial::Web tutorial shows how you can use the Template Toolkit to generate static and dynamic web content. .SS "Template::Tutorial::Datafile" .IX Subsection "Template::Tutorial::Datafile" The Template::Tutorial::Datafile tutorial shows how you can use the Template Toolkit to generate other data formats like \s-1XML.\s0 PK � �[ɱTDZ Z ' man3/Template::Namespace::Constants.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Namespace::Constants 3" .TH Template::Namespace::Constants 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Namespace::Constants \- Compile time constant folding .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # easy way to define constants \& use Template; \& \& my $tt = Template\->new({ \& CONSTANTS => { \& pi => 3.14, \& e => 2.718, \& }, \& }); \& \& # nitty\-gritty, hands\-dirty way \& use Template::Namespace::Constants; \& \& my $tt = Template\->new({ \& NAMESPACE => { \& constants => Template::Namespace::Constants\->new({ \& pi => 3.14, \& e => 2.718, \& }, \& }, \& }); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Namespace::Constants\*(C'\fR module implements a namespace handler which is plugged into the \f(CW\*(C`Template::Directive\*(C'\fR compiler module. This then performs compile time constant folding of variables in a particular namespace. .SH "METHODS" .IX Header "METHODS" .SS "new(\e%constants)" .IX Subsection "new(%constants)" The \fBnew()\fR constructor method creates and returns a reference to a new Template::Namespace::Constants object. This creates an internal stash to store the constant variable definitions passed as arguments. .PP .Vb 4 \& my $handler = Template::Namespace::Constants\->new({ \& pi => 3.14, \& e => 2.718, \& }); .Ve .SS "ident(\e@ident)" .IX Subsection "ident(@ident)" Method called to resolve a variable identifier into a compiled form. In this case, the method fetches the corresponding constant value from its internal stash and returns it. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Directive PK � �[_�*�pi pi man3/Template.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template 3" .TH Template 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template \- Front\-end module to the Template Toolkit .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template; \& \& # some useful options (see below for full list) \& my $config = { \& INCLUDE_PATH => \*(Aq/search/path\*(Aq, # or list ref \& INTERPOLATE => 1, # expand "$var" in plain text \& POST_CHOMP => 1, # cleanup whitespace \& PRE_PROCESS => \*(Aqheader\*(Aq, # prefix each template \& EVAL_PERL => 1, # evaluate Perl code blocks \& }; \& \& # create Template object \& my $template = Template\->new($config); \& \& # define template variables for replacement \& my $vars = { \& var1 => $value, \& var2 => \e%hash, \& var3 => \e@list, \& var4 => \e&code, \& var5 => $object, \& }; \& \& # specify input filename, or file handle, text reference, etc. \& my $input = \*(Aqmyfile.html\*(Aq; \& \& # process input template, substituting variables \& $template\->process($input, $vars) \& || die $template\->error(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This documentation describes the Template module which is the direct Perl interface into the Template Toolkit. It covers the use of the module and gives a brief summary of configuration options and template directives. Please see Template::Manual for the complete reference manual which goes into much greater depth about the features and use of the Template Toolkit. The Template::Tutorial is also available as an introductory guide to using the Template Toolkit. .SH "METHODS" .IX Header "METHODS" .SS "new(\e%config)" .IX Subsection "new(%config)" The \f(CW\*(C`new()\*(C'\fR constructor method (implemented by the Template::Base base class) instantiates a new \&\f(CW\*(C`Template\*(C'\fR object. A reference to a hash array of configuration items may be passed as a parameter. .PP .Vb 4 \& my $tt = Template\->new({ \& INCLUDE_PATH => \*(Aq/usr/local/templates\*(Aq, \& EVAL_PERL => 1, \& }) || die $Template::ERROR, "\en"; .Ve .PP A reference to a new \f(CW\*(C`Template\*(C'\fR object is returned, or undef on error. In the latter case, the error message can be retrieved by calling \fBerror()\fR as a class method or by examining the \f(CW$Template::ERROR\fR package variable directly. .PP .Vb 2 \& my $tt = Template\->new(\e%config) \& || die Template\->error(), "\en"; \& \& my $tt = Template\->new(\e%config) \& || die $Template::ERROR, "\en"; .Ve .PP For convenience, configuration items may also be specified as a list of items instead of a hash array reference. These are automatically folded into a hash array by the constructor. .PP .Vb 2 \& my $tt = Template\->new(INCLUDE_PATH => \*(Aq/tmp\*(Aq, POST_CHOMP => 1) \& || die $Template::ERROR, "\en"; .Ve .ie n .SS "process($template, \e%vars, $output, %options)" .el .SS "process($template, \e%vars, \f(CW$output\fP, \f(CW%options\fP)" .IX Subsection "process($template, %vars, $output, %options)" The \f(CW\*(C`process()\*(C'\fR method is called to process a template. The first parameter indicates the input template as one of: .IP "\(bu" 4 a filename relative to \f(CW\*(C`INCLUDE_PATH\*(C'\fR, if defined .IP "\(bu" 4 a reference to a text string containing the template text .IP "\(bu" 4 a file handle reference (e.g. \f(CW\*(C`IO::Handle\*(C'\fR or sub-class) or \f(CW\*(C`GLOB\*(C'\fR (e.g. \f(CW\*(C`\e*STDIN\*(C'\fR), from which the template can be read. .PP A reference to a hash array may be passed as the second parameter, containing definitions of template variables. .PP .Vb 3 \& # filename \& $tt\->process(\*(Aqwelcome.tt2\*(Aq) \& || die $tt\->error(), "\en"; \& \& # text reference \& $text = "[% INCLUDE header %]\enHello world!\en[% INCLUDE footer %]"; \& $tt\->process(\e$text) \& || die $tt\->error(), "\en"; \& \& # file handle (GLOB) \& $tt\->process(\e*DATA) \& || die $tt\->error(), "\en"; \& \& _\|_END_\|_ \& [% INCLUDE header %] \& This is a template defined in the _\|_END_\|_ section which is \& accessible via the DATA "file handle". \& [% INCLUDE footer %] .Ve .PP By default, the processed template output is printed to \f(CW\*(C`STDOUT\*(C'\fR. The \&\f(CW\*(C`process()\*(C'\fR method then returns \f(CW1\fR to indicate success. A third parameter may be passed to the \f(CW\*(C`process()\*(C'\fR method to specify a different output location. This value may be one of: .IP "\(bu" 4 a plain string indicating a filename which will be opened (relative to \&\f(CW\*(C`OUTPUT_PATH\*(C'\fR, if defined) and the output written to .IP "\(bu" 4 a file \s-1GLOB\s0 opened ready for output .IP "\(bu" 4 a reference to a scalar (e.g. a text string) to which output/error is appended .IP "\(bu" 4 a reference to a subroutine which is called, passing the output as a parameter .IP "\(bu" 4 any object reference which implements a \f(CW\*(C`print()\*(C'\fR method (e.g. \f(CW\*(C`IO::Handle\*(C'\fR, \&\f(CW\*(C`Apache::Request\*(C'\fR, etc.) which will be called, passing the generated output as a parameter. .PP Examples: .PP .Vb 3 \& # output filename \& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \*(Aqwelcome.html\*(Aq) \& || die $tt\->error(), "\en"; \& \& # reference to output subroutine \& sub myout { \& my $output = shift; \& ... \& } \& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \e&myout) \& || die $tt\->error(), "\en"; \& \& # reference to output text string \& my $output = \*(Aq\*(Aq; \& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \e$output) \& || die $tt\->error(), "\en"; \& \& print "output: $output\en"; .Ve .PP In an Apache/mod_perl handler: .PP .Vb 2 \& sub handler { \& my $req = shift; \& \& # ...your code here... \& \& # direct output to Apache::Request via $req\->print($output) \& $tt\->process($file, $vars, $req) || do { \& $req\->log_reason($tt\->error()); \& return SERVER_ERROR; \& }; \& return OK; \& } .Ve .PP After the optional third output argument can come an optional reference to a hash or a list of \f(CW\*(C`(name, value)\*(C'\fR pairs providing further options for the output. The only option currently supported is \&\f(CW\*(C`binmode\*(C'\fR which, when set to any true value will ensure that files created (but not any existing file handles passed) will be set to binary mode. .PP .Vb 3 \& # either: hash reference of options \& $tt\->process($infile, $vars, $outfile, { binmode => 1 }) \& || die $tt\->error(), "\en"; \& \& # or: list of name, value pairs \& $tt\->process($infile, $vars, $outfile, binmode => 1) \& || die $tt\->error(), "\en"; .Ve .PP Alternately, the \f(CW\*(C`binmode\*(C'\fR argument can specify a particular \s-1IO\s0 layer such as \f(CW\*(C`:utf8\*(C'\fR. .PP .Vb 2 \& $tt\->process($infile, $vars, $outfile, binmode => \*(Aq:utf8\*(Aq) \& || die $tt\->error(), "\en"; .Ve .PP The \f(CW\*(C`OUTPUT\*(C'\fR configuration item can be used to specify a default output location other than \f(CW\*(C`\e*STDOUT\*(C'\fR. The \f(CW\*(C`OUTPUT_PATH\*(C'\fR specifies a directory which should be prefixed to all output locations specified as filenames. .PP .Vb 5 \& my $tt = Template\->new({ \& OUTPUT => sub { ... }, # default \& OUTPUT_PATH => \*(Aq/tmp\*(Aq, \& ... \& }) || die Template\->error(), "\en"; \& \& # use default OUTPUT (sub is called) \& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars) \& || die $tt\->error(), "\en"; \& \& # write file to \*(Aq/tmp/welcome.html\*(Aq \& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \*(Aqwelcome.html\*(Aq) \& || die $tt\->error(), "\en"; .Ve .PP The \f(CW\*(C`process()\*(C'\fR method returns \f(CW1\fR on success or \f(CW\*(C`undef\*(C'\fR on error. The error message generated in the latter case can be retrieved by calling the \&\fBerror()\fR method. See also \*(L"\s-1CONFIGURATION SUMMARY\*(R"\s0 which describes how error handling may be further customised. .SS "\fBerror()\fP" .IX Subsection "error()" When called as a class method, it returns the value of the \f(CW$ERROR\fR package variable. Thus, the following are equivalent. .PP .Vb 2 \& my $tt = Template\->new() \& || die Template\->error(), "\en"; \& \& my $tt = Template\->new() \& || die $Template::ERROR, "\en"; .Ve .PP When called as an object method, it returns the value of the internal \&\f(CW\*(C`_ERROR\*(C'\fR variable, as set by an error condition in a previous call to \&\fBprocess()\fR. .PP .Vb 2 \& $tt\->process(\*(Aqwelcome.tt2\*(Aq) \& || die $tt\->error(), "\en"; .Ve .PP Errors are represented in the Template Toolkit by objects of the Template::Exception class. If the \fBprocess()\fR method returns a false value then the \f(CW\*(C`error()\*(C'\fR method can be called to return an object of this class. The \fBtype()\fR and \&\fBinfo()\fR methods can called on the object to retrieve the error type and information string, respectively. The \&\fBas_string()\fR method can be called to return a string of the form \f(CW\*(C`$type \- $info\*(C'\fR. This method is also overloaded onto the stringification operator allowing the object reference itself to be printed to return the formatted error string. .PP .Vb 6 \& $tt\->process(\*(Aqsomefile\*(Aq) || do { \& my $error = $tt\->error(); \& print "error type: ", $error\->type(), "\en"; \& print "error info: ", $error\->info(), "\en"; \& print $error, "\en"; \& }; .Ve .SS "\fBservice()\fP" .IX Subsection "service()" The \f(CW\*(C`Template\*(C'\fR module delegates most of the effort of processing templates to an underlying Template::Service object. This method returns a reference to that object. .SS "\fBcontext()\fP" .IX Subsection "context()" The Template::Service module uses a core Template::Context object for runtime processing of templates. This method returns a reference to that object and is equivalent to \f(CW\*(C`$template\->service\->context()\*(C'\fR. .SS "template($name)" .IX Subsection "template($name)" This method is a simple wrapper around the Template::Context method of the same name. It returns a compiled template for the source provided as an argument. .SH "CONFIGURATION SUMMARY" .IX Header "CONFIGURATION SUMMARY" The following list gives a short summary of each Template Toolkit configuration option. See Template::Manual::Config for full details. .SS "Template Style and Parsing Options" .IX Subsection "Template Style and Parsing Options" \fI\s-1ENCODING\s0\fR .IX Subsection "ENCODING" .PP Specifies the character encoding. .PP \fI\s-1START_TAG, END_TAG\s0\fR .IX Subsection "START_TAG, END_TAG" .PP Define tokens that indicate start and end of directives (default: '\f(CW\*(C`[%\*(C'\fR' and '\f(CW\*(C`%]\*(C'\fR'). .PP \fI\s-1TAG_STYLE\s0\fR .IX Subsection "TAG_STYLE" .PP Set \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR according to a pre-defined style (default: \&'\f(CW\*(C`template\*(C'\fR', as above). .PP \fI\s-1PRE_CHOMP, POST_CHOMP\s0\fR .IX Subsection "PRE_CHOMP, POST_CHOMP" .PP Removes whitespace before/after directives (default: 0/0). .PP \fI\s-1TRIM\s0\fR .IX Subsection "TRIM" .PP Remove leading and trailing whitespace from template output (default: 0). .PP \fI\s-1INTERPOLATE\s0\fR .IX Subsection "INTERPOLATE" .PP Interpolate variables embedded like \f(CW$this\fR or \f(CW\*(C`${this}\*(C'\fR (default: 0). .PP \fI\s-1ANYCASE\s0\fR .IX Subsection "ANYCASE" .PP Allow directive keywords in lower case (default: 0 \- \s-1UPPER\s0 only). .SS "Template Files and Blocks" .IX Subsection "Template Files and Blocks" \fI\s-1INCLUDE_PATH\s0\fR .IX Subsection "INCLUDE_PATH" .PP One or more directories to search for templates. .PP \fI\s-1DELIMITER\s0\fR .IX Subsection "DELIMITER" .PP Delimiter for separating paths in \f(CW\*(C`INCLUDE_PATH\*(C'\fR (default: '\f(CW\*(C`:\*(C'\fR'). .PP \fI\s-1ABSOLUTE\s0\fR .IX Subsection "ABSOLUTE" .PP Allow absolute file names, e.g. \f(CW\*(C`/foo/bar.html\*(C'\fR (default: 0). .PP \fI\s-1RELATIVE\s0\fR .IX Subsection "RELATIVE" .PP Allow relative filenames, e.g. \f(CW\*(C`../foo/bar.html\*(C'\fR (default: 0). .PP \fI\s-1DEFAULT\s0\fR .IX Subsection "DEFAULT" .PP Default template to use when another not found. .PP \fI\s-1BLOCKS\s0\fR .IX Subsection "BLOCKS" .PP Hash array pre-defining template blocks. .PP \fI\s-1AUTO_RESET\s0\fR .IX Subsection "AUTO_RESET" .PP Enabled by default causing \f(CW\*(C`BLOCK\*(C'\fR definitions to be reset each time a template is processed. Disable to allow \f(CW\*(C`BLOCK\*(C'\fR definitions to persist. .PP \fI\s-1RECURSION\s0\fR .IX Subsection "RECURSION" .PP Flag to permit recursion into templates (default: 0). .SS "Template Variables" .IX Subsection "Template Variables" \fI\s-1VARIABLES\s0\fR .IX Subsection "VARIABLES" .PP Hash array of variables and values to pre-define in the stash. .SS "Runtime Processing Options" .IX Subsection "Runtime Processing Options" \fI\s-1EVAL_PERL\s0\fR .IX Subsection "EVAL_PERL" .PP Flag to indicate if \f(CW\*(C`PERL\*(C'\fR/\f(CW\*(C`RAWPERL\*(C'\fR blocks should be processed (default: 0). .PP \fI\s-1PRE_PROCESS, POST_PROCESS\s0\fR .IX Subsection "PRE_PROCESS, POST_PROCESS" .PP Name of template(s) to process before/after main template. .PP \fI\s-1PROCESS\s0\fR .IX Subsection "PROCESS" .PP Name of template(s) to process instead of main template. .PP \fI\s-1ERROR\s0\fR .IX Subsection "ERROR" .PP Name of error template or reference to hash array mapping error types to templates. .PP \fI\s-1OUTPUT\s0\fR .IX Subsection "OUTPUT" .PP Default output location or handler. .PP \fI\s-1OUTPUT_PATH\s0\fR .IX Subsection "OUTPUT_PATH" .PP Directory into which output files can be written. .PP \fI\s-1DEBUG\s0\fR .IX Subsection "DEBUG" .PP Enable debugging messages. .SS "Caching and Compiling Options" .IX Subsection "Caching and Compiling Options" \fI\s-1CACHE_SIZE\s0\fR .IX Subsection "CACHE_SIZE" .PP Maximum number of compiled templates to cache in memory (default: undef \- cache all) .PP \fI\s-1COMPILE_EXT\s0\fR .IX Subsection "COMPILE_EXT" .PP Filename extension for compiled template files (default: undef \- don't compile). .PP \fI\s-1COMPILE_DIR\s0\fR .IX Subsection "COMPILE_DIR" .PP Root of directory in which compiled template files should be written (default: undef \- don't compile). .SS "Plugins and Filters" .IX Subsection "Plugins and Filters" \fI\s-1PLUGINS\s0\fR .IX Subsection "PLUGINS" .PP Reference to a hash array mapping plugin names to Perl packages. .PP \fI\s-1PLUGIN_BASE\s0\fR .IX Subsection "PLUGIN_BASE" .PP One or more base classes under which plugins may be found. .PP \fI\s-1LOAD_PERL\s0\fR .IX Subsection "LOAD_PERL" .PP Flag to indicate regular Perl modules should be loaded if a named plugin can't be found (default: 0). .PP \fI\s-1FILTERS\s0\fR .IX Subsection "FILTERS" .PP Hash array mapping filter names to filter subroutines or factories. .SS "Customisation and Extension" .IX Subsection "Customisation and Extension" \fI\s-1LOAD_TEMPLATES\s0\fR .IX Subsection "LOAD_TEMPLATES" .PP List of template providers. .PP \fI\s-1LOAD_PLUGINS\s0\fR .IX Subsection "LOAD_PLUGINS" .PP List of plugin providers. .PP \fI\s-1LOAD_FILTERS\s0\fR .IX Subsection "LOAD_FILTERS" .PP List of filter providers. .PP \fI\s-1TOLERANT\s0\fR .IX Subsection "TOLERANT" .PP Set providers to tolerate errors as declinations (default: 0). .PP \fI\s-1SERVICE\s0\fR .IX Subsection "SERVICE" .PP Reference to a custom service object (default: Template::Service). .PP \fI\s-1CONTEXT\s0\fR .IX Subsection "CONTEXT" .PP Reference to a custom context object (default: Template::Context). .PP \fI\s-1STASH\s0\fR .IX Subsection "STASH" .PP Reference to a custom stash object (default: Template::Stash). .PP \fI\s-1PARSER\s0\fR .IX Subsection "PARSER" .PP Reference to a custom parser object (default: Template::Parser). .PP \fI\s-1GRAMMAR\s0\fR .IX Subsection "GRAMMAR" .PP Reference to a custom grammar object (default: Template::Grammar). .SH "DIRECTIVE SUMMARY" .IX Header "DIRECTIVE SUMMARY" The following list gives a short summary of each Template Toolkit directive. See Template::Manual::Directives for full details. .SS "\s-1GET\s0" .IX Subsection "GET" Evaluate and print a variable or value. .PP .Vb 7 \& [% GET variable %] # \*(AqGET\*(Aq keyword is optional \& [% variable %] \& [% hash.key %] \& [% list.n %] \& [% code(args) %] \& [% obj.meth(args) %] \& [% "value: $var" %] .Ve .SS "\s-1CALL\s0" .IX Subsection "CALL" As per \s-1GET\s0 but without printing result (e.g. call code) .PP .Vb 1 \& [% CALL variable %] .Ve .SS "\s-1SET\s0" .IX Subsection "SET" Assign a values to variables. .PP .Vb 8 \& [% SET variable = value %] # \*(AqSET\*(Aq also optional \& [% variable = other_variable \& variable = \*(Aqliteral text @ $100\*(Aq \& variable = "interpolated text: $var" \& list = [ val, val, val, val, ... ] \& list = [ val..val ] \& hash = { var => val, var => val, ... } \& %] .Ve .SS "\s-1DEFAULT\s0" .IX Subsection "DEFAULT" Like \s-1SET\s0, but variables are only set if currently unset (i.e. have no true value). .PP .Vb 1 \& [% DEFAULT variable = value %] .Ve .SS "\s-1INSERT\s0" .IX Subsection "INSERT" Insert a file without any processing performed on the contents. .PP .Vb 1 \& [% INSERT legalese.txt %] .Ve .SS "\s-1PROCESS\s0" .IX Subsection "PROCESS" Process another template file or block and insert the generated output. Any template \s-1BLOCK\s0s or variables defined or updated in the \f(CW\*(C`PROCESS\*(C'\fRed template will thereafter be defined in the calling template. .PP .Vb 2 \& [% PROCESS template %] \& [% PROCESS template var = val, ... %] .Ve .SS "\s-1INCLUDE\s0" .IX Subsection "INCLUDE" Similar to \f(CW\*(C`PROCESS\*(C'\fR, but using a local copy of the current variables. Any template \f(CW\*(C`BLOCK\*(C'\fRs or variables defined in the \f(CW\*(C`INCLUDE\*(C'\fRd template remain local to it. .PP .Vb 2 \& [% INCLUDE template %] \& [% INCLUDE template var = val, ... %] .Ve .SS "\s-1WRAPPER\s0" .IX Subsection "WRAPPER" The content between the \f(CW\*(C`WRAPPER\*(C'\fR and corresponding \f(CW\*(C`END\*(C'\fR directives is first evaluated, with the output generated being stored in the \f(CW\*(C`content\*(C'\fR variable. The named template is then process as per \f(CW\*(C`INCLUDE\*(C'\fR. .PP .Vb 3 \& [% WRAPPER layout %] \& Some template markup [% blah %]... \& [% END %] .Ve .PP A simple \fIlayout\fR template might look something like this: .PP .Vb 3 \& Your header here... \& [% content %] \& Your footer here... .Ve .SS "\s-1BLOCK\s0" .IX Subsection "BLOCK" Define a named template block for \s-1INCLUDE\s0, \s-1PROCESS\s0 and \s-1WRAPPER\s0 to use. .PP .Vb 3 \& [% BLOCK hello %] \& Hello World \& [% END %] \& \& [% INCLUDE hello %] .Ve .SS "\s-1FOREACH\s0" .IX Subsection "FOREACH" Repeat the enclosed \f(CW\*(C`FOREACH\*(C'\fR ... \f(CW\*(C`END\*(C'\fR block for each value in the list. .PP .Vb 4 \& [% FOREACH variable IN [ val, val, val ] %] # either \& [% FOREACH variable IN list %] # or \& The variable is set to [% variable %] \& [% END %] .Ve .SS "\s-1WHILE\s0" .IX Subsection "WHILE" The block enclosed between \f(CW\*(C`WHILE\*(C'\fR and \f(CW\*(C`END\*(C'\fR block is processed while the specified condition is true. .PP .Vb 3 \& [% WHILE condition %] \& content \& [% END %] .Ve .SS "\s-1IF / UNLESS / ELSIF / ELSE\s0" .IX Subsection "IF / UNLESS / ELSIF / ELSE" The enclosed block is processed if the condition is true / false. .PP .Vb 7 \& [% IF condition %] \& content \& [% ELSIF condition %] \& content \& [% ELSE %] \& content \& [% END %] \& \& [% UNLESS condition %] \& content \& [% # ELSIF/ELSE as per IF, above %] \& content \& [% END %] .Ve .SS "\s-1SWITCH / CASE\s0" .IX Subsection "SWITCH / CASE" Multi-way switch/case statement. .PP .Vb 8 \& [% SWITCH variable %] \& [% CASE val1 %] \& content \& [% CASE [ val2, val3 ] %] \& content \& [% CASE %] # or [% CASE DEFAULT %] \& content \& [% END %] .Ve .SS "\s-1MACRO\s0" .IX Subsection "MACRO" Define a named macro. .PP .Vb 5 \& [% MACRO name <directive> %] \& [% MACRO name(arg1, arg2) <directive> %] \& ... \& [% name %] \& [% name(val1, val2) %] .Ve .SS "\s-1FILTER\s0" .IX Subsection "FILTER" Process enclosed \f(CW\*(C`FILTER\*(C'\fR ... \f(CW\*(C`END\*(C'\fR block then pipe through a filter. .PP .Vb 5 \& [% FILTER name %] # either \& [% FILTER name( params ) %] # or \& [% FILTER alias = name( params ) %] # or \& content \& [% END %] .Ve .SS "\s-1USE\s0" .IX Subsection "USE" Load a plugin module (see \f(CW\*(C`Template::<Manual::Plugins\*(C'\fR), or any regular Perl module when the \f(CW\*(C`LOAD_PERL\*(C'\fR option is set. .PP .Vb 6 \& [% USE name %] # either \& [% USE name( params ) %] # or \& [% USE var = name( params ) %] # or \& ... \& [% name.method %] \& [% var.method %] .Ve .SS "\s-1PERL / RAWPERL\s0" .IX Subsection "PERL / RAWPERL" Evaluate enclosed blocks as Perl code (requires the \f(CW\*(C`EVAL_PERL\*(C'\fR option to be set). .PP .Vb 6 \& [% PERL %] \& # perl code goes here \& $stash\->set(\*(Aqfoo\*(Aq, 10); \& print "set \*(Aqfoo\*(Aq to ", $stash\->get(\*(Aqfoo\*(Aq), "\en"; \& print $context\->include(\*(Aqfooter\*(Aq, { var => $val }); \& [% END %] \& \& [% RAWPERL %] \& # raw perl code goes here, no magic but fast. \& $output .= \*(Aqsome output\*(Aq; \& [% END %] .Ve .SS "\s-1TRY / THROW / CATCH / FINAL\s0" .IX Subsection "TRY / THROW / CATCH / FINAL" Exception handling. .PP .Vb 11 \& [% TRY %] \& content \& [% THROW type info %] \& [% CATCH type %] \& catch content \& [% error.type %] [% error.info %] \& [% CATCH %] # or [% CATCH DEFAULT %] \& content \& [% FINAL %] \& this block is always processed \& [% END %] .Ve .SS "\s-1NEXT\s0" .IX Subsection "NEXT" Jump straight to the next item in a \f(CW\*(C`FOREACH\*(C'\fR or \f(CW\*(C`WHILE\*(C'\fR loop. .PP .Vb 1 \& [% NEXT %] .Ve .SS "\s-1LAST\s0" .IX Subsection "LAST" Break out of \f(CW\*(C`FOREACH\*(C'\fR or \f(CW\*(C`WHILE\*(C'\fR loop. .PP .Vb 1 \& [% LAST %] .Ve .SS "\s-1RETURN\s0" .IX Subsection "RETURN" Stop processing current template and return to including templates. .PP .Vb 1 \& [% RETURN %] .Ve .SS "\s-1STOP\s0" .IX Subsection "STOP" Stop processing all templates and return to caller. .PP .Vb 1 \& [% STOP %] .Ve .SS "\s-1TAGS\s0" .IX Subsection "TAGS" Define new tag style or characters (default: \f(CW\*(C`[%\*(C'\fR \f(CW\*(C`%]\*(C'\fR). .PP .Vb 2 \& [% TAGS html %] \& [% TAGS <!\-\- \-\-> %] .Ve .SS "\s-1COMMENTS\s0" .IX Subsection "COMMENTS" Ignored and deleted. .PP .Vb 3 \& [% # this is a comment to the end of line \& foo = \*(Aqbar\*(Aq \& %] \& \& [%# placing the \*(Aq#\*(Aq immediately inside the directive \& tag comments out the entire directive \& %] .Ve .SH "SOURCE CODE REPOSITORY" .IX Header "SOURCE CODE REPOSITORY" The source code for the Template Toolkit is held in a public git repository on Github: <https://github.com/abw/Template2> .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "VERSION" .IX Header "VERSION" Template Toolkit version 3.100, released on July 13 2020. .SH "SUPPORT" .IX Header "SUPPORT" The Template Toolkit mailing list provides a forum for discussing issues relating to the use and abuse of the Template Toolkit. There are a number of knowledgeable and helpful individuals who frequent the list (including the author) who can often offer help or suggestions. Please respect their time and patience by checking the documentation and/or mailing list archives before asking questions that may already have been answered. .PP To subscribe to the mailing list, send an email to: .PP .Vb 1 \& template\-toolkit+subscribe@groups.io .Ve .PP You can also use the web interface: .PP .Vb 1 \& https://groups.io/g/template\-toolkit .Ve .PP For information about commercial support and consultancy for the Template Toolkit, please contact the author. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[���i� � man3/Template::Plugin::Date.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Date 3" .TH Template::Plugin::Date 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Date \- Plugin to generate formatted date strings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE date %] \& \& # use current time and default format \& [% date.format %] \& \& # specify time as seconds since epoch \& # or as a \*(Aqh:m:s d\-m\-y\*(Aq or \*(Aqy\-m\-d h:m:s\*(Aq string \& [% date.format(960973980) %] \& [% date.format(\*(Aq4:20:36 21/12/2000\*(Aq) %] \& [% date.format(\*(Aq2000/12/21 4:20:36\*(Aq) %] \& \& # specify format \& [% date.format(mytime, \*(Aq%H:%M:%S\*(Aq) %] \& \& # specify locale \& [% date.format(date.now, \*(Aq%a %d %b %y\*(Aq, \*(Aqen_GB\*(Aq) %] \& \& # named parameters \& [% date.format(mytime, format = \*(Aq%H:%M:%S\*(Aq) %] \& [% date.format(locale = \*(Aqen_GB\*(Aq) %] \& [% date.format(time = date.now, \& format = \*(Aq%H:%M:%S\*(Aq, \& locale = \*(Aqen_GB\*(Aq \& use_offset = 1) %] \& \& # specify default format to plugin \& [% USE date(format = \*(Aq%H:%M:%S\*(Aq, locale = \*(Aqde_DE\*(Aq) %] \& \& [% date.format %] \& ... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Date\*(C'\fR plugin provides an easy way to generate formatted time and date strings by delegating to the \f(CW\*(C`POSIX\*(C'\fR \f(CW\*(C`strftime()\*(C'\fR routine. .PP The plugin can be loaded via the familiar \s-1USE\s0 directive. .PP .Vb 1 \& [% USE date %] .Ve .PP This creates a plugin object with the default name of '\f(CW\*(C`date\*(C'\fR'. An alternate name can be specified as such: .PP .Vb 1 \& [% USE myname = date %] .Ve .PP The plugin provides the \f(CW\*(C`format()\*(C'\fR method which accepts a time value, a format string and a locale name. All of these parameters are optional with the current system time, default format ('\f(CW\*(C`%H:%M:%S %d\-%b\-%Y\*(C'\fR') and current locale being used respectively, if undefined. Default values for the time, format and/or locale may be specified as named parameters in the \f(CW\*(C`USE\*(C'\fR directive. .PP .Vb 1 \& [% USE date(format = \*(Aq%a %d\-%b\-%Y\*(Aq, locale = \*(Aqfr_FR\*(Aq) %] .Ve .PP When called without any parameters, the \f(CW\*(C`format()\*(C'\fR method returns a string representing the current system time, formatted by \f(CW\*(C`strftime()\*(C'\fR according to the default format and for the default locale (which may not be the current one, if locale is set in the \f(CW\*(C`USE\*(C'\fR directive). .PP .Vb 1 \& [% date.format %] .Ve .PP The plugin allows a time/date to be specified as seconds since the epoch, as is returned by \f(CW\*(C`time()\*(C'\fR. .PP .Vb 1 \& File last modified: [% date.format(filemod_time) %] .Ve .PP The time/date can also be specified as a string of the form \f(CW\*(C`h:m:s d/m/y\*(C'\fR or \f(CW\*(C`y/m/d h:m:s\*(C'\fR. Any of the characters : / \- or space may be used to delimit fields. .PP .Vb 2 \& [% USE day = date(format => \*(Aq%A\*(Aq, locale => \*(Aqen_GB\*(Aq) %] \& [% day.format(\*(Aq4:20:00 9\-13\-2000\*(Aq) %] .Ve .PP Output: .PP .Vb 1 \& Tuesday .Ve .PP A format string can also be passed to the \f(CW\*(C`format()\*(C'\fR method, and a locale specification may follow that. .PP .Vb 2 \& [% date.format(filemod, \*(Aq%d\-%b\-%Y\*(Aq) %] \& [% date.format(filemod, \*(Aq%d\-%b\-%Y\*(Aq, \*(Aqen_GB\*(Aq) %] .Ve .PP A fourth parameter allows you to force output in \s-1GMT,\s0 in the case of seconds-since-the-epoch input: .PP .Vb 1 \& [% date.format(filemod, \*(Aq%d\-%b\-%Y\*(Aq, \*(Aqen_GB\*(Aq, 1) %] .Ve .PP Note that in this case, if the local time is not \s-1GMT,\s0 then also specifying \&'\f(CW%Z\fR' (time zone) in the format parameter will lead to an extremely misleading result. .PP To maintain backwards compatibility, using the \f(CW%z\fR placeholder in the format string (to output the \s-1UTC\s0 offset) currently requires the \f(CW\*(C`use_offset\*(C'\fR parameter to be set to a true value. This can also be passed as the fifth parameter to format (but the former will probably be clearer). .PP Any or all of these parameters may be named. Positional parameters should always be in the order \f(CW\*(C`($time, $format, $locale)\*(C'\fR. .PP .Vb 6 \& [% date.format(format => \*(Aq%H:%M:%S\*(Aq) %] \& [% date.format(time => filemod, format => \*(Aq%H:%M:%S\*(Aq) %] \& [% date.format(mytime, format => \*(Aq%H:%M:%S\*(Aq) %] \& [% date.format(mytime, format => \*(Aq%H:%M:%S\*(Aq, locale => \*(Aqfr_FR\*(Aq) %] \& [% date.format(mytime, format => \*(Aq%H:%M:%S\*(Aq, gmt => 1) %] \& ...etc... .Ve .PP The \f(CW\*(C`now()\*(C'\fR method returns the current system time in seconds since the epoch. .PP .Vb 1 \& [% date.format(date.now, \*(Aq%A\*(Aq) %] .Ve .PP The \f(CW\*(C`calc()\*(C'\fR method can be used to create an interface to the \f(CW\*(C`Date::Calc\*(C'\fR module (if installed on your system). .PP .Vb 2 \& [% calc = date.calc %] \& [% calc.Monday_of_Week(22, 2001).join(\*(Aq/\*(Aq) %] .Ve .PP The \f(CW\*(C`manip()\*(C'\fR method can be used to create an interface to the \f(CW\*(C`Date::Manip\*(C'\fR module (if installed on your system). .PP .Vb 2 \& [% manip = date.manip %] \& [% manip.UnixDate("Noon Yesterday","%Y %b %d %H:%M") %] .Ve .SH "AUTHORS" .IX Header "AUTHORS" Thierry-Michel Barral wrote the original plugin. .PP Andy Wardley provided some minor fixups/enhancements, a test script and documentation. .PP Mark D. Mills cloned \f(CW\*(C`Date::Manip\*(C'\fR from the \f(CW\*(C`Date::Calc\*(C'\fR sub-plugin. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2000\-2022 Thierry-Michel Barral, Andy Wardley. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, \s-1POSIX\s0 PK � �[$X~50 50 ! man3/Template::Manual::Config.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Config 3" .TH Template::Manual::Config 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Config \- Configuration options .SH "Template Style and Parsing Options" .IX Header "Template Style and Parsing Options" .SS "\s-1ENCODING\s0" .IX Subsection "ENCODING" The \f(CW\*(C`ENCODING\*(C'\fR option specifies the template files' character encoding: .PP .Vb 3 \& my $template = Template\->new({ \& ENCODING => \*(Aqutf8\*(Aq, \& }); .Ve .PP A template which starts with a Unicode byte order mark (\s-1BOM\s0) will have its encoding detected automatically. .SS "\s-1START_TAG, END_TAG\s0" .IX Subsection "START_TAG, END_TAG" The \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR options are used to specify character sequences or regular expressions that mark the start and end of inline template directives. The default values for \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR are \&'\f(CW\*(C`[%\*(C'\fR' and '\f(CW\*(C`%]\*(C'\fR' respectively, giving us the familiar directive style: .PP .Vb 1 \& [% example %] .Ve .PP Any Perl regex characters can be used and therefore should be escaped (or use the Perl \f(CW\*(C`quotemeta\*(C'\fR function) if they are intended to represent literal characters. .PP .Vb 4 \& my $template = Template\->new({ \& START_TAG => quotemeta(\*(Aq<+\*(Aq), \& END_TAG => quotemeta(\*(Aq+>\*(Aq), \& }); .Ve .PP Example: .PP .Vb 1 \& <+ INCLUDE foobar +> .Ve .PP The \f(CW\*(C`TAGS\*(C'\fR directive can also be used to set the \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR values on a per-template file basis. .PP .Vb 1 \& [% TAGS <+ +> %] .Ve .SS "\s-1OUTLINE_TAG\s0" .IX Subsection "OUTLINE_TAG" The \f(CW\*(C`OUTLINE_TAG\*(C'\fR option can be used to enable single-line \*(L"outline\*(R" directives. .PP .Vb 3 \& my $template = Template\->new({ \& OUTLINE_TAG => \*(Aq%%\*(Aq, \& }); .Ve .PP This allows you to use both inline and outline tags like so: .PP .Vb 3 \& %% IF user \& Hello [% user.name %] \& %% END .Ve .PP The \f(CW\*(C`OUTLINE_TAG\*(C'\fR string (or regex) must appear at the start of a line. The directive continues until the end of the line. The newline character at the end of the line is considered to be the invisible end-of-directive marker and is removed. .SS "\s-1TAG_STYLE\s0" .IX Subsection "TAG_STYLE" The \f(CW\*(C`TAG_STYLE\*(C'\fR option can be used to set both \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR according to pre-defined tag styles. .PP .Vb 3 \& my $template = Template\->new({ \& TAG_STYLE => \*(Aqstar\*(Aq, \& }); .Ve .PP Available styles are: .PP .Vb 8 \& template [% ... %] (default) \& template1 [% ... %] or %% ... %% (TT version 1) \& metatext %% ... %% (Text::MetaText) \& star [* ... *] (TT alternate) \& php <? ... ?> (PHP) \& asp <% ... %> (ASP) \& mason <% ... > (HTML::Mason) \& html <!\-\- ... \-\-> (HTML comments) .Ve .PP The \f(CW\*(C`outline\*(C'\fR style uses the default markers for \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR (\f(CW\*(C`[%\*(C'\fR and \f(CW\*(C`%]\*(C'\fR respectively) and additionally defines \f(CW\*(C`OUTLINE_TAG\*(C'\fR to be \f(CW\*(C`%%\*(C'\fR. .PP .Vb 3 \& my $template = Template\->new({ \& TAG_STYLE => \*(Aqoutline\*(Aq, \& }); .Ve .PP This allows you to use both inline and outline tags like so: .PP .Vb 3 \& %% IF user \& Hello [% user.name %] \& %% END .Ve .PP Any values specified for \f(CW\*(C`START_TAG\*(C'\fR, \f(CW\*(C`END_TAG\*(C'\fR and/or \f(CW\*(C`OUTLINE_TAG\*(C'\fR will override those defined by a \f(CW\*(C`TAG_STYLE\*(C'\fR. .PP The \f(CW\*(C`TAGS\*(C'\fR directive may also be used to set a \f(CW\*(C`TAG_STYLE\*(C'\fR .PP .Vb 2 \& [% TAGS html %] \& <!\-\- INCLUDE header \-\-> .Ve .SS "\s-1PRE_CHOMP, POST_CHOMP\s0" .IX Subsection "PRE_CHOMP, POST_CHOMP" Anything outside a directive tag is considered plain text and is generally passed through unaltered (but see the \s-1INTERPOLATE\s0 option). This includes all whitespace and newlines characters surrounding directive tags. Directives that don't generate any output will leave gaps in the output document. .PP Example: .PP .Vb 3 \& Foo \& [% a = 10 %] \& Bar .Ve .PP Output: .PP .Vb 1 \& Foo \& \& Bar .Ve .PP The \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR options can help to clean up some of this extraneous whitespace. Both are disabled by default. .PP .Vb 4 \& my $template = Template\->new({ \& PRE_CHOMP => 1, \& POST_CHOMP => 1, \& }); .Ve .PP With \f(CW\*(C`PRE_CHOMP\*(C'\fR set to \f(CW1\fR, the newline and whitespace preceding a directive at the start of a line will be deleted. This has the effect of concatenating a line that starts with a directive onto the end of the previous line. .PP .Vb 9 \& Foo <\-\-\-\-\-\-\-\-\-\-. \& | \& ,\-\-\-(PRE_CHOMP)\-\-\-\-\*(Aq \& | \& \`\-\- [% a = 10 %] \-\-. \& | \& ,\-\-\-(POST_CHOMP)\-\-\-\*(Aq \& | \& \`\-> Bar .Ve .PP With \f(CW\*(C`POST_CHOMP\*(C'\fR set to \f(CW1\fR, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line. .PP If \f(CW\*(C`PRE_CHOMP\*(C'\fR or \f(CW\*(C`POST_CHOMP\*(C'\fR is set to \f(CW2\fR, all whitespace including any number of newline will be removed and replaced with a single space. This is useful for \s-1HTML,\s0 where (usually) a contiguous block of whitespace is rendered the same as a single space. .PP With \f(CW\*(C`PRE_CHOMP\*(C'\fR or \f(CW\*(C`POST_CHOMP\*(C'\fR set to \f(CW3\fR, all adjacent whitespace (including newlines) will be removed entirely. .PP These values are defined as \f(CW\*(C`CHOMP_NONE\*(C'\fR, \f(CW\*(C`CHOMP_ONE\*(C'\fR, \f(CW\*(C`CHOMP_COLLAPSE\*(C'\fR and \&\f(CW\*(C`CHOMP_GREEDY\*(C'\fR constants in the Template::Constants module. \f(CW\*(C`CHOMP_ALL\*(C'\fR is also defined as an alias for \f(CW\*(C`CHOMP_ONE\*(C'\fR to provide backwards compatibility with earlier version of the Template Toolkit. .PP Additionally the chomp tag modifiers listed below may also be used for the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR configuration. .PP .Vb 4 \& my $template = Template\->new({ \& PRE_CHOMP => \*(Aq~\*(Aq, \& POST_CHOMP => \*(Aq\-\*(Aq, \& }); .Ve .PP \&\f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR can be activated for individual directives by placing a '\f(CW\*(C`\-\*(C'\fR' immediately at the start and/or end of the directive. .PP .Vb 3 \& [% FOREACH user IN userlist %] \& [%\- user \-%] \& [% END %] .Ve .PP This has the same effect as \f(CW\*(C`CHOMP_ONE\*(C'\fR in removing all whitespace before or after the directive up to and including the newline. The template will be processed as if written: .PP .Vb 1 \& [% FOREACH user IN userlist %][% user %][% END %] .Ve .PP To remove all whitespace including any number of newlines, use the ('\f(CW\*(C`~\*(C'\fR') tilde character instead. .PP .Vb 1 \& [% FOREACH user IN userlist %] \& \& [%~ user ~%] \& \& [% END %] .Ve .PP To collapse all whitespace to a single space, use the '\f(CW\*(C`=\*(C'\fR' equals sign character. .PP .Vb 1 \& [% FOREACH user IN userlist %] \& \& [%= user =%] \& \& [% END %] .Ve .PP Here the template is processed as if written: .PP .Vb 1 \& [% FOREACH user IN userlist %] [% user %] [% END %] .Ve .PP If you have \f(CW\*(C`PRE_CHOMP\*(C'\fR or \f(CW\*(C`POST_CHOMP\*(C'\fR set as configuration options then you can use the '\f(CW\*(C`+\*(C'\fR' plus sign to disable any chomping options (i.e. leave the whitespace intact) on a per-directive basis. .PP .Vb 3 \& [% FOREACH user IN userlist %] \& User: [% user +%] \& [% END %] .Ve .PP With \f(CW\*(C`POST_CHOMP\*(C'\fR set to \f(CW\*(C`CHOMP_ONE\*(C'\fR, the above example would be parsed as if written: .PP .Vb 2 \& [% FOREACH user IN userlist %]User: [% user %] \& [% END %] .Ve .PP For reference, the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR configuration options may be set to any of the following: .PP .Vb 6 \& Constant Value Tag Modifier \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& CHOMP_NONE 0 + \& CHOMP_ONE 1 \- \& CHOMP_COLLAPSE 2 = \& CHOMP_GREEDY 3 ~ .Ve .SS "\s-1TRIM\s0" .IX Subsection "TRIM" The \f(CW\*(C`TRIM\*(C'\fR option can be set to have any leading and trailing whitespace automatically removed from the output of all template files and \f(CW\*(C`BLOCK\*(C'\fRs. .PP By example, the following \f(CW\*(C`BLOCK\*(C'\fR definition .PP .Vb 3 \& [% BLOCK foo %] \& Line 1 of foo \& [% END %] .Ve .PP will be processed is as "\f(CW\*(C`\enLine 1 of foo\en\*(C'\fR". When \f(CW\*(C`INCLUDE\*(C'\fRd, the surrounding newlines will also be introduced. .PP .Vb 3 \& before \& [% INCLUDE foo %] \& after .Ve .PP Generated output: .PP .Vb 1 \& before \& \& Line 1 of foo \& \& after .Ve .PP With the \f(CW\*(C`TRIM\*(C'\fR option set to any true value, the leading and trailing newlines (which count as whitespace) will be removed from the output of the \f(CW\*(C`BLOCK\*(C'\fR. .PP .Vb 3 \& before \& Line 1 of foo \& after .Ve .PP The \f(CW\*(C`TRIM\*(C'\fR option is disabled (\f(CW0\fR) by default. .SS "\s-1INTERPOLATE\s0" .IX Subsection "INTERPOLATE" The \f(CW\*(C`INTERPOLATE\*(C'\fR flag, when set to any true value will cause variable references in plain text (i.e. not surrounded by \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR) to be recognised and interpolated accordingly. .PP .Vb 3 \& my $template = Template\->new({ \& INTERPOLATE => 1, \& }); .Ve .PP Variables should be prefixed by a '\f(CW\*(C`$\*(C'\fR' dollar sign to identify them. Curly braces '\f(CW\*(C`{\*(C'\fR' and '\f(CW\*(C`}\*(C'\fR' can be used in the familiar Perl/shell style to explicitly scope the variable name where required. .PP .Vb 4 \& # INTERPOLATE => 0 \& <a href="http://[% server %]/[% help %]"> \& <img src="[% images %]/help.gif"></a> \& [% myorg.name %] \& \& # INTERPOLATE => 1 \& <a href="http://$server/$help"> \& <img src="$images/help.gif"></a> \& $myorg.name \& \& # explicit scoping with { } \& <img src="$images/${icon.next}.gif"> .Ve .PP Note that a limitation in Perl's regex engine restricts the maximum length of an interpolated template to around 32 kilobytes or possibly less. Files that exceed this limit in size will typically cause Perl to dump core with a segmentation fault. If you routinely process templates of this size then you should disable \f(CW\*(C`INTERPOLATE\*(C'\fR or split the templates in several smaller files or blocks which can then be joined backed together via \&\f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`INCLUDE\*(C'\fR. .SS "\s-1ANYCASE\s0" .IX Subsection "ANYCASE" By default, directive keywords should be expressed in \s-1UPPER CASE.\s0 The \&\f(CW\*(C`ANYCASE\*(C'\fR option can be set to allow directive keywords to be specified in any case. .PP .Vb 4 \& # ANYCASE => 0 (default) \& [% INCLUDE foobar %] # OK \& [% include foobar %] # ERROR \& [% include = 10 %] # OK, \*(Aqinclude\*(Aq is a variable \& \& # ANYCASE => 1 \& [% INCLUDE foobar %] # OK \& [% include foobar %] # OK \& [% include = 10 %] # ERROR, \*(Aqinclude\*(Aq is reserved word .Ve .PP One side-effect of enabling \f(CW\*(C`ANYCASE\*(C'\fR is that you cannot use a variable of the same name as a reserved word, regardless of case. The reserved words are currently: .PP .Vb 5 \& GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER \& IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE \& USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META \& TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP \& CLEAR TO STEP AND OR NOT MOD DIV END .Ve .PP The only lower case reserved words that cannot be used for variables, regardless of the \f(CW\*(C`ANYCASE\*(C'\fR option, are the operators: .PP .Vb 1 \& and or not mod div .Ve .SH "Template Files and Blocks" .IX Header "Template Files and Blocks" .SS "\s-1INCLUDE_PATH\s0" .IX Subsection "INCLUDE_PATH" The \f(CW\*(C`INCLUDE_PATH\*(C'\fR is used to specify one or more directories in which template files are located. When a template is requested that isn't defined locally as a \f(CW\*(C`BLOCK\*(C'\fR, each of the \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories is searched in turn to locate the template file. Multiple directories can be specified as a reference to a list or as a single string where each directory is delimited by the '\f(CW\*(C`:\*(C'\fR' colon character. .PP .Vb 3 \& my $template = Template\->new({ \& INCLUDE_PATH => \*(Aq/usr/local/templates\*(Aq, \& }); \& \& my $template = Template\->new({ \& INCLUDE_PATH => \*(Aq/usr/local/templates:/tmp/my/templates\*(Aq, \& }); \& \& my $template = Template\->new({ \& INCLUDE_PATH => [ \*(Aq/usr/local/templates\*(Aq, \& \*(Aq/tmp/my/templates\*(Aq ], \& }); .Ve .PP On Win32 systems, a little extra magic is invoked, ignoring delimiters that have '\f(CW\*(C`:\*(C'\fR' colon followed by a '\f(CW\*(C`/\*(C'\fR' slash or '\f(CW\*(C`\e\*(C'\fR' blackslash. This avoids confusion when using directory names like '\f(CW\*(C`C:\eBlah Blah\*(C'\fR'. .PP When specified as a list, the \f(CW\*(C`INCLUDE_PATH\*(C'\fR path can contain elements which dynamically generate a list of \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories. These generator elements can be specified as a reference to a subroutine or an object which implements a \f(CW\*(C`paths()\*(C'\fR method. .PP .Vb 5 \& my $template = Template\->new({ \& INCLUDE_PATH => [ \*(Aq/usr/local/templates\*(Aq, \& \e&incpath_generator, \& My::IncPath::Generator\->new( ... ) ], \& }); .Ve .PP Each time a template is requested and the \f(CW\*(C`INCLUDE_PATH\*(C'\fR examined, the subroutine or object method will be called. A reference to a list of directories should be returned. Generator subroutines should report errors using \f(CW\*(C`die()\*(C'\fR. Generator objects should return undef and make an error available via its \f(CW\*(C`error()\*(C'\fR method. .PP For example: .PP .Vb 2 \& sub incpath_generator { \& # ...some code... \& \& if ($all_is_well) { \& return \e@list_of_directories; \& } \& else { \& die "cannot generate INCLUDE_PATH...\en"; \& } \& } .Ve .PP or: .PP .Vb 1 \& package My::IncPath::Generator; \& \& # Template::Base (or Class::Base) provides error() method \& use Template::Base; \& use base qw( Template::Base ); \& \& sub paths { \& my $self = shift; \& \& # ...some code... \& \& if ($all_is_well) { \& return \e@list_of_directories; \& } \& else { \& return $self\->error("cannot generate INCLUDE_PATH...\en"); \& } \& } \& \& 1; .Ve .SS "\s-1DELIMITER\s0" .IX Subsection "DELIMITER" Used to provide an alternative delimiter character sequence for separating paths specified in the \f(CW\*(C`INCLUDE_PATH\*(C'\fR. The default value for \f(CW\*(C`DELIMITER\*(C'\fR is the '\f(CW\*(C`:\*(C'\fR' colon character. .PP .Vb 4 \& my $template = Template\->new({ \& DELIMITER => \*(Aq; \*(Aq, \& INCLUDE_PATH => \*(AqC:/HERE/NOW; D:/THERE/THEN\*(Aq, \& }); .Ve .PP On Win32 systems, the default delimiter is a little more intelligent, splitting paths only on '\f(CW\*(C`:\*(C'\fR' colon characters that aren't followed by a \&'\f(CW\*(C`/\*(C'\fR' slash character. This means that the following should work as planned, splitting the \&\f(CW\*(C`INCLUDE_PATH\*(C'\fR into 2 separate directories, \f(CW\*(C`C:/foo\*(C'\fR and \f(CW\*(C`C:/bar\*(C'\fR. .PP .Vb 4 \& # on Win32 only \& my $template = Template\->new({ \& INCLUDE_PATH => \*(AqC:/Foo:C:/Bar\*(Aq \& }); .Ve .PP However, if you're using Win32 then it's recommended that you explicitly set the \f(CW\*(C`DELIMITER\*(C'\fR character to something else (e.g. '\f(CW\*(C`;\*(C'\fR' semicolon) rather than rely on this subtle magic. .SS "\s-1ABSOLUTE\s0" .IX Subsection "ABSOLUTE" The \f(CW\*(C`ABSOLUTE\*(C'\fR flag is used to indicate if templates specified with absolute filenames (e.g. '\f(CW\*(C`/foo/bar\*(C'\fR') should be processed. It is disabled by default and any attempt to load a template by such a name will cause a '\f(CW\*(C`file\*(C'\fR' exception to be raised. .PP .Vb 3 \& my $template = Template\->new({ \& ABSOLUTE => 1, \& }); \& \& # this is why it\*(Aqs disabled by default \& [% INSERT /etc/passwd %] .Ve .PP On Win32 systems, the regular expression for matching absolute pathnames is tweaked slightly to also detect filenames that start with a driver letter and colon, such as: .PP .Vb 1 \& C:/Foo/Bar .Ve .SS "\s-1RELATIVE\s0" .IX Subsection "RELATIVE" The \f(CW\*(C`RELATIVE\*(C'\fR flag is used to indicate if templates specified with filenames relative to the current directory (e.g. '\f(CW\*(C`./foo/bar\*(C'\fR' or \&'\f(CW\*(C`../../some/where/else\*(C'\fR') should be loaded. It is also disabled by default, and will raise a '\f(CW\*(C`file\*(C'\fR' error if such template names are encountered. .PP .Vb 3 \& my $template = Template\->new({ \& RELATIVE => 1, \& }); \& \& [% INCLUDE ../logs/error.log %] .Ve .SS "\s-1DEFAULT\s0" .IX Subsection "DEFAULT" The \f(CW\*(C`DEFAULT\*(C'\fR option can be used to specify a default template which should be used whenever a specified template can't be found in the \f(CW\*(C`INCLUDE_PATH\*(C'\fR. .PP .Vb 3 \& my $template = Template\->new({ \& DEFAULT => \*(Aqnotfound.html\*(Aq, \& }); .Ve .PP If a non-existent template is requested through the Template \&\fBprocess()\fR method, or by an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \&\f(CW\*(C`WRAPPER\*(C'\fR directive, then the \f(CW\*(C`DEFAULT\*(C'\fR template will instead be processed, if defined. Note that the \f(CW\*(C`DEFAULT\*(C'\fR template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string. .SS "\s-1BLOCKS\s0" .IX Subsection "BLOCKS" The \f(CW\*(C`BLOCKS\*(C'\fR option can be used to pre-define a default set of template blocks. These should be specified as a reference to a hash array mapping template names to template text, subroutines or Template::Document objects. .PP .Vb 7 \& my $template = Template\->new({ \& BLOCKS => { \& header => \*(AqThe Header. [% title %]\*(Aq, \& footer => sub { return $some_output_text }, \& another => Template::Document\->new({ ... }), \& }, \& }); .Ve .SS "\s-1VIEWS\s0" .IX Subsection "VIEWS" The \s-1VIEWS\s0 option can be used to define one or more Template::View objects. They can be specified as a reference to a hash array or list reference. .PP .Vb 5 \& my $template = Template\->new({ \& VIEWS => { \& my_view => { prefix => \*(Aqmy_templates/\*(Aq }, \& }, \& }); .Ve .PP Be aware of the fact that Perl's hash array are unordered, so if you want to specify multiple views of which one or more are based on other views, then you should use a list reference to preserve the order of definition. .PP .Vb 7 \& my $template = Template\->new({ \& VIEWS => [ \& bottom => { prefix => \*(Aqbottom/\*(Aq }, \& middle => { prefix => \*(Aqmiddle/\*(Aq, base => \*(Aqbottom\*(Aq }, \& top => { prefix => \*(Aqtop/\*(Aq, base => \*(Aqmiddle\*(Aq }, \& ], \& }); .Ve .SS "\s-1AUTO_RESET\s0" .IX Subsection "AUTO_RESET" The \f(CW\*(C`AUTO_RESET\*(C'\fR option is set by default and causes the local \f(CW\*(C`BLOCKS\*(C'\fR cache for the Template::Context object to be reset on each call to the Template \fBprocess()\fR method. This ensures that any \f(CW\*(C`BLOCK\*(C'\fRs defined within a template will only persist until that template is finished processing. This prevents \f(CW\*(C`BLOCK\*(C'\fRs defined in one processing request from interfering with other independent requests subsequently processed by the same context object. .PP The \f(CW\*(C`BLOCKS\*(C'\fR item may be used to specify a default set of block definitions for the Template::Context object. Subsequent \f(CW\*(C`BLOCK\*(C'\fR definitions in templates will over-ride these but they will be reinstated on each reset if \&\f(CW\*(C`AUTO_RESET\*(C'\fR is enabled (default), or if the Template::Context \&\fBreset()\fR method is called. .SS "\s-1RECURSION\s0" .IX Subsection "RECURSION" The template processor will raise a file exception if it detects direct or indirect recursion into a template. Setting this option to any true value will allow templates to include each other recursively. .SH "Template Variables" .IX Header "Template Variables" .SS "\s-1VARIABLES\s0" .IX Subsection "VARIABLES" The \f(CW\*(C`VARIABLES\*(C'\fR option (or \f(CW\*(C`PRE_DEFINE\*(C'\fR \- they're equivalent) can be used to specify a hash array of template variables that should be used to pre-initialise the stash when it is created. These items are ignored if the \f(CW\*(C`STASH\*(C'\fR item is defined. .PP .Vb 7 \& my $template = Template\->new({ \& VARIABLES => { \& title => \*(AqA Demo Page\*(Aq, \& author => \*(AqJoe Random Hacker\*(Aq, \& version => 3.14, \& }, \& }; .Ve .PP or .PP .Vb 7 \& my $template = Template\->new({ \& PRE_DEFINE => { \& title => \*(AqA Demo Page\*(Aq, \& author => \*(AqJoe Random Hacker\*(Aq, \& version => 3.14, \& }, \& }; .Ve .SS "\s-1CONSTANTS\s0" .IX Subsection "CONSTANTS" The \f(CW\*(C`CONSTANTS\*(C'\fR option can be used to specify a hash array of template variables that are compile-time constants. These variables are resolved once when the template is compiled, and thus don't require further resolution at runtime. This results in significantly faster processing of the compiled templates and can be used for variables that don't change from one request to the next. .PP .Vb 7 \& my $template = Template\->new({ \& CONSTANTS => { \& title => \*(AqA Demo Page\*(Aq, \& author => \*(AqJoe Random Hacker\*(Aq, \& version => 3.14, \& }, \& }; .Ve .SS "\s-1CONSTANT_NAMESPACE\s0" .IX Subsection "CONSTANT_NAMESPACE" Constant variables are accessed via the \f(CW\*(C`constants\*(C'\fR namespace by default. .PP .Vb 1 \& [% constants.title %] .Ve .PP The \f(CW\*(C`CONSTANTS_NAMESPACE\*(C'\fR option can be set to specify an alternate namespace. .PP .Vb 7 \& my $template = Template\->new({ \& CONSTANTS => { \& title => \*(AqA Demo Page\*(Aq, \& # ...etc... \& }, \& CONSTANTS_NAMESPACE => \*(Aqconst\*(Aq, \& }; .Ve .PP In this case the constants would then be accessed as: .PP .Vb 1 \& [% const.title %] .Ve .SS "\s-1NAMESPACE\s0" .IX Subsection "NAMESPACE" The constant folding mechanism described above is an example of a namespace handler. Namespace handlers can be defined to provide alternate parsing mechanisms for variables in different namespaces. .PP Under the hood, the Template module converts a constructor configuration such as: .PP .Vb 7 \& my $template = Template\->new({ \& CONSTANTS => { \& title => \*(AqA Demo Page\*(Aq, \& # ...etc... \& }, \& CONSTANTS_NAMESPACE => \*(Aqconst\*(Aq, \& }; .Ve .PP into one like: .PP .Vb 8 \& my $template = Template\->new({ \& NAMESPACE => { \& const => Template:::Namespace::Constants\->new({ \& title => \*(AqA Demo Page\*(Aq, \& # ...etc... \& }), \& }, \& }; .Ve .PP You can use this mechanism to define multiple constant namespaces, or to install custom handlers of your own. .PP .Vb 10 \& my $template = Template\->new({ \& NAMESPACE => { \& site => Template:::Namespace::Constants\->new({ \& title => "Wardley\*(Aqs Widgets", \& version => 2.718, \& }), \& author => Template:::Namespace::Constants\->new({ \& name => \*(AqAndy Wardley\*(Aq, \& email => \*(Aqabw@andywardley.com\*(Aq, \& }), \& voodoo => My::Namespace::Handler\->new( ... ), \& }, \& }; .Ve .PP Now you have two constant namespaces, for example: .PP .Vb 2 \& [% site.title %] \& [% author.name %] .Ve .PP as well as your own custom namespace handler installed for the 'voodoo' namespace. .PP .Vb 1 \& [% voodoo.magic %] .Ve .PP See Template::Namespace::Constants for an example of what a namespace handler looks like on the inside. .SH "Template Processing Options" .IX Header "Template Processing Options" The following options are used to specify any additional templates that should be processed before, after, around or instead of the template passed as the first argument to the Template \fBprocess()\fR method. These options can be perform various useful tasks such as adding standard headers or footers to all pages, wrapping page output in other templates, pre-defining variables or performing initialisation or cleanup tasks, automatically generating page summary information, navigation elements, and so on. .PP The task of processing the template is delegated internally to the Template::Service module which, unsurprisingly, also has a \&\fBprocess()\fR method. Any templates defined by the \&\f(CW\*(C`PRE_PROCESS\*(C'\fR option are processed first and any output generated is added to the output buffer. Then the main template is processed, or if one or more \&\f(CW\*(C`PROCESS\*(C'\fR templates are defined then they are instead processed in turn. In this case, one of the \f(CW\*(C`PROCESS\*(C'\fR templates is responsible for processing the main template, by a directive such as: .PP .Vb 1 \& [% PROCESS $template %] .Ve .PP The output of processing the main template or the \f(CW\*(C`PROCESS\*(C'\fR template(s) is then wrapped in any \f(CW\*(C`WRAPPER\*(C'\fR templates, if defined. \f(CW\*(C`WRAPPER\*(C'\fR templates don't need to worry about explicitly processing the template because it will have been done for them already. Instead \f(CW\*(C`WRAPPER\*(C'\fR templates access the content they are wrapping via the \f(CW\*(C`content\*(C'\fR variable. .PP .Vb 3 \& wrapper before \& [% content %] \& wrapper after .Ve .PP This output generated from processing the main template, and/or any \&\f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR templates is added to the output buffer. Finally, any \f(CW\*(C`POST_PROCESS\*(C'\fR templates are processed and their output is also added to the output buffer which is then returned. .PP If the main template throws an exception during processing then any relevant template(s) defined via the \f(CW\*(C`ERROR\*(C'\fR option will be processed instead. If defined and successfully processed, the output from the error template will be added to the output buffer in place of the template that generated the error and processing will continue, applying any \f(CW\*(C`WRAPPER\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates. If no relevant \f(CW\*(C`ERROR\*(C'\fR option is defined, or if the error occurs in one of the \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`WRAPPER\*(C'\fR or \f(CW\*(C`POST_PROCESS\*(C'\fR templates, then the process will terminate immediately and the error will be returned. .SS "\s-1PRE_PROCESS, POST_PROCESS\s0" .IX Subsection "PRE_PROCESS, POST_PROCESS" These values may be set to contain the name(s) of template files (relative to \f(CW\*(C`INCLUDE_PATH\*(C'\fR) which should be processed immediately before and/or after each template. These do not get added to templates processed into a document via directives such as \f(CW\*(C`INCLUDE\*(C'\fR, \&\f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`WRAPPER\*(C'\fR etc. .PP .Vb 4 \& my $template = Template\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }; .Ve .PP Multiple templates may be specified as a reference to a list. Each is processed in the order defined. .PP .Vb 4 \& my $template = Template\->new({ \& PRE_PROCESS => [ \*(Aqconfig\*(Aq, \*(Aqheader\*(Aq ], \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }; .Ve .PP Alternately, multiple template may be specified as a single string, delimited by '\f(CW\*(C`:\*(C'\fR'. This delimiter string can be changed via the \&\f(CW\*(C`DELIMITER\*(C'\fR option. .PP .Vb 4 \& my $template = Template\->new({ \& PRE_PROCESS => \*(Aqconfig:header\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }; .Ve .PP The \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates are evaluated in the same variable context as the main document and may define or update variables for subsequent use. .PP config: .PP .Vb 4 \& [% # set some site\-wide variables \& bgcolor = \*(Aq#ffffff\*(Aq \& version = 2.718 \& %] .Ve .PP header: .PP .Vb 6 \& [% DEFAULT title = \*(AqMy Funky Web Site\*(Aq %] \& <html> \& <head> \& <title>[% title %]</title> \& </head> \& <body bgcolor="[% bgcolor %]"> .Ve .PP footer: .PP .Vb 4 \& <hr> \& Version [% version %] \& </body> \& </html> .Ve .PP The Template::Document object representing the main template being processed is available within \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates as the \f(CW\*(C`template\*(C'\fR variable. Metadata items defined via the \f(CW\*(C`META\*(C'\fR directive may be accessed accordingly. .PP .Vb 1 \& $template\->process(\*(Aqmydoc.html\*(Aq, $vars); .Ve .PP mydoc.html: .PP .Vb 3 \& [% META title = \*(AqMy Document Title\*(Aq %] \& blah blah blah \& ... .Ve .PP header: .PP .Vb 5 \& <html> \& <head> \& <title>[% template.title %]</title> \& </head> \& <body bgcolor="[% bgcolor %]"> .Ve .SS "\s-1PROCESS\s0" .IX Subsection "PROCESS" The \f(CW\*(C`PROCESS\*(C'\fR option may be set to contain the name(s) of template files (relative to \f(CW\*(C`INCLUDE_PATH\*(C'\fR) which should be processed instead of the main template passed to the Template \fBprocess()\fR method. This can be used to apply consistent wrappers around all templates, similar to the use of \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates. .PP .Vb 3 \& my $template = Template\->new({ \& PROCESS => \*(Aqcontent\*(Aq, \& }; \& \& # processes \*(Aqcontent\*(Aq instead of \*(Aqfoo.html\*(Aq \& $template\->process(\*(Aqfoo.html\*(Aq); .Ve .PP A reference to the original template is available in the \f(CW\*(C`template\*(C'\fR variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by \&\f(CW\*(C`$\*(C'\fR) to an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive. .PP content: .PP .Vb 12 \& <html> \& <head> \& <title>[% template.title %]</title> \& </head> \& <body> \& <!\-\- begin content \-\-> \& [% PROCESS $template %] \& <!\-\- end content \-\-> \& <hr> \& © Copyright [% template.copyright %] \& </body> \& </html> .Ve .PP foo.html: .PP .Vb 7 \& [% META \& title = \*(AqThe Foo Page\*(Aq \& author = \*(AqFred Foo\*(Aq \& copyright = \*(Aq2000 Fred Foo\*(Aq \& %] \& <h1>[% template.title %]</h1> \& Welcome to the Foo Page, blah blah blah .Ve .PP output: .PP .Vb 10 \& <html> \& <head> \& <title>The Foo Page</title> \& </head> \& <body> \& <!\-\- begin content \-\-> \& <h1>The Foo Page</h1> \& Welcome to the Foo Page, blah blah blah \& <!\-\- end content \-\-> \& <hr> \& © Copyright 2000 Fred Foo \& </body> \& </html> .Ve .SS "\s-1WRAPPER\s0" .IX Subsection "WRAPPER" The \f(CW\*(C`WRAPPER\*(C'\fR option can be used to specify one or more templates which should be used to wrap around the output of the main page template. The main template is processed first (or any \f(CW\*(C`PROCESS\*(C'\fR template(s)) and the output generated is then passed as the \f(CW\*(C`content\*(C'\fR variable to the \&\f(CW\*(C`WRAPPER\*(C'\fR template(s) as they are processed. .PP .Vb 3 \& my $template = Template\->new({ \& WRAPPER => \*(Aqwrapper\*(Aq, \& }; \& \& # process \*(Aqfoo\*(Aq then wrap in \*(Aqwrapper\*(Aq \& $template\->process(\*(Aqfoo\*(Aq, { message => \*(AqHello World!\*(Aq }); .Ve .PP wrapper: .PP .Vb 3 \& <wrapper> \& [% content %] \& </wrapper> .Ve .PP foo: .PP .Vb 2 \& This is the foo file! \& Message: [% message %] .Ve .PP The output generated from this example is: .PP .Vb 4 \& <wrapper> \& This is the foo file! \& Message: Hello World! \& </wrapper> .Ve .PP You can specify more than one \f(CW\*(C`WRAPPER\*(C'\fR template by setting the value to be a reference to a list of templates. The \f(CW\*(C`WRAPPER\*(C'\fR templates will be processed in reverse order with the output of each being passed to the next (or previous, depending on how you look at it) as the 'content' variable. It sounds complicated, but the end result is that it just \&\*(L"Does The Right Thing\*(R" to make wrapper templates nest in the order you specify. .PP .Vb 3 \& my $template = Template\->new({ \& WRAPPER => [ \*(Aqouter\*(Aq, \*(Aqinner\*(Aq ], \& }; \& \& # process \*(Aqfoo\*(Aq then wrap in \*(Aqinner\*(Aq, then in \*(Aqouter\*(Aq \& $template\->process(\*(Aqfoo\*(Aq, { message => \*(AqHello World!\*(Aq }); .Ve .PP outer: .PP .Vb 3 \& <outer> \& [% content %] \& </outer> .Ve .PP inner: .PP .Vb 3 \& <inner> \& [% content %] \& </inner> .Ve .PP The output generated is then: .PP .Vb 6 \& <outer> \& <inner> \& This is the foo file! \& Message: Hello World! \& </inner> \& </outer> .Ve .PP One side-effect of the \*(L"inside-out\*(R" processing of the \f(CW\*(C`WRAPPER\*(C'\fR configuration item (and also the \f(CW\*(C`WRAPPER\*(C'\fR directive) is that any variables set in the template being wrapped will be visible to the template doing the wrapping, but not the other way around. .PP You can use this to good effect in allowing page templates to set pre-defined values which are then used in the wrapper templates. For example, our main page template 'foo' might look like this: .PP foo: .PP .Vb 6 \& [% page = { \& title = \*(AqFoo Page\*(Aq \& subtitle = \*(AqEverything There is to Know About Foo\*(Aq \& author = \*(AqFrank Oliver Octagon\*(Aq \& } \& %] \& \& <p> \& Welcome to the page that tells you everything about foo \& blah blah blah... \& </p> .Ve .PP The \f(CW\*(C`foo\*(C'\fR template is processed before the wrapper template meaning that the \f(CW\*(C`page\*(C'\fR data structure will be defined for use in the wrapper template. .PP wrapper: .PP .Vb 11 \& <html> \& <head> \& <title>[% page.title %]</title> \& </head> \& <body> \& <h1>[% page.title %]</h1> \& <h2>[% page.subtitle %]</h1> \& <h3>by [% page.author %]</h3> \& [% content %] \& </body> \& </html> .Ve .PP It achieves the same effect as defining \f(CW\*(C`META\*(C'\fR items which are then accessed via the \f(CW\*(C`template\*(C'\fR variable (which you are still free to use within \f(CW\*(C`WRAPPER\*(C'\fR templates), but gives you more flexibility in the type and complexity of data that you can define. .SS "\s-1ERROR\s0" .IX Subsection "ERROR" The \f(CW\*(C`ERROR\*(C'\fR (or \f(CW\*(C`ERRORS\*(C'\fR if you prefer) configuration item can be used to name a single template or specify a hash array mapping exception types to templates which should be used for error handling. If an uncaught exception is raised from within a template then the appropriate error template will instead be processed. .PP If specified as a single value then that template will be processed for all uncaught exceptions. .PP .Vb 3 \& my $template = Template\->new({ \& ERROR => \*(Aqerror.html\*(Aq \& }); .Ve .PP If the \f(CW\*(C`ERROR\*(C'\fR item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A \f(CW\*(C`default\*(C'\fR template may be provided for the general case. Note that \f(CW\*(C`ERROR\*(C'\fR can be pluralised to \f(CW\*(C`ERRORS\*(C'\fR if you find it more appropriate in this case. .PP .Vb 7 \& my $template = Template\->new({ \& ERRORS => { \& user => \*(Aquser/index.html\*(Aq, \& dbi => \*(Aqerror/database\*(Aq, \& default => \*(Aqerror/default\*(Aq, \& }, \& }); .Ve .PP In this example, any \f(CW\*(C`user\*(C'\fR exceptions thrown will cause the \&\fIuser/index.html\fR template to be processed, \f(CW\*(C`dbi\*(C'\fR errors are handled by \fIerror/database\fR and all others by the \fIerror/default\fR template. Any \f(CW\*(C`PRE_PROCESS\*(C'\fR and/or \f(CW\*(C`POST_PROCESS\*(C'\fR templates will also be applied to these error templates. .PP Note that exception types are hierarchical and a \f(CW\*(C`foo\*(C'\fR handler will catch all \f(CW\*(C`foo.*\*(C'\fR errors (e.g. \f(CW\*(C`foo.bar\*(C'\fR, \f(CW\*(C`foo.bar.baz\*(C'\fR) if a more specific handler isn't defined. Be sure to quote any exception types that contain periods to prevent Perl concatenating them into a single string (i.e. \f(CW\*(C`user.passwd\*(C'\fR is parsed as \f(CW\*(Aquser\*(Aq.\*(Aqpasswd\*(Aq\fR). .PP .Vb 8 \& my $template = Template\->new({ \& ERROR => { \& \*(Aquser.login\*(Aq => \*(Aquser/login.html\*(Aq, \& \*(Aquser.passwd\*(Aq => \*(Aquser/badpasswd.html\*(Aq, \& \*(Aquser\*(Aq => \*(Aquser/index.html\*(Aq, \& \*(Aqdefault\*(Aq => \*(Aqerror/default\*(Aq, \& }, \& }); .Ve .PP In this example, any template processed by the \f(CW$template\fR object, or other templates or code called from within, can raise a \f(CW\*(C`user.login\*(C'\fR exception and have the service redirect to the \fIuser/login.html\fR template. Similarly, a \f(CW\*(C`user.passwd\*(C'\fR exception has a specific handling template, \fIuser/badpasswd.html\fR, while all other \f(CW\*(C`user\*(C'\fR or \&\f(CW\*(C`user.*\*(C'\fR exceptions cause a redirection to the \fIuser/index.html\fR page. All other exception types are handled by \fIerror/default\fR. .PP Exceptions can be raised in a template using the \f(CW\*(C`THROW\*(C'\fR directive, .PP .Vb 1 \& [% THROW user.login \*(Aqno user id: please login\*(Aq %] .Ve .PP or by calling the \fBthrow()\fR method on the current Template::Context object, .PP .Vb 2 \& $context\->throw(\*(Aquser.passwd\*(Aq, \*(AqIncorrect Password\*(Aq); \& $context\->throw(\*(AqIncorrect Password\*(Aq); # type \*(Aqundef\*(Aq .Ve .PP or from Perl code by calling \f(CW\*(C`die()\*(C'\fR with a Template::Exception object, .PP .Vb 1 \& die (Template::Exception\->new(\*(Aquser.denied\*(Aq, \*(AqInvalid User ID\*(Aq)); .Ve .PP or by simply calling \fBdie()\fR with an error string. This is automagically caught and converted to an exception of '\f(CW\*(C`undef\*(C'\fR' type which can then be handled in the usual way. .PP .Vb 1 \& die "I\*(Aqm sorry Dave, I can\*(Aqt do that"; .Ve .PP Note that the '\f(CW\*(C`undef\*(C'\fR' we're talking about here is a literal string rather than Perl's \f(CW\*(C`undef\*(C'\fR used to represent undefined values. .SH "Template Runtime Options" .IX Header "Template Runtime Options" .SS "\s-1EVAL_PERL\s0" .IX Subsection "EVAL_PERL" This flag is used to indicate if \f(CW\*(C`PERL\*(C'\fR and/or \f(CW\*(C`RAWPERL\*(C'\fR blocks should be evaluated. It is disabled by default and any \f(CW\*(C`PERL\*(C'\fR or \f(CW\*(C`RAWPERL\*(C'\fR blocks encountered will raise exceptions of type '\f(CW\*(C`perl\*(C'\fR' with the message \&'\f(CW\*(C`EVAL_PERL not set\*(C'\fR'. Note however that any \f(CW\*(C`RAWPERL\*(C'\fR blocks should always contain valid Perl code, regardless of the \f(CW\*(C`EVAL_PERL\*(C'\fR flag. The parser will fail to compile templates that contain invalid Perl code in \f(CW\*(C`RAWPERL\*(C'\fR blocks and will throw a '\f(CW\*(C`file\*(C'\fR' exception. .PP When using compiled templates (see \&\*(L"Caching and Compiling Options\*(R"), the \f(CW\*(C`EVAL_PERL\*(C'\fR has an affect when the template is compiled, and again when the templates is subsequently processed, possibly in a different context to the one that compiled it. .PP If the \f(CW\*(C`EVAL_PERL\*(C'\fR is set when a template is compiled, then all \f(CW\*(C`PERL\*(C'\fR and \&\f(CW\*(C`RAWPERL\*(C'\fR blocks will be included in the compiled template. If the \&\f(CW\*(C`EVAL_PERL\*(C'\fR option isn't set, then Perl code will be generated which \&\fBalways\fR throws a '\f(CW\*(C`perl\*(C'\fR' exception with the message '\f(CW\*(C`EVAL_PERL not set\*(C'\fR' \fBwhenever\fR the compiled template code is run. .PP Thus, you must have \f(CW\*(C`EVAL_PERL\*(C'\fR set if you want your compiled templates to include \f(CW\*(C`PERL\*(C'\fR and \f(CW\*(C`RAWPERL\*(C'\fR blocks. .PP At some point in the future, using a different invocation of the Template Toolkit, you may come to process such a pre-compiled template. Assuming the \f(CW\*(C`EVAL_PERL\*(C'\fR option was set at the time the template was compiled, then the output of any \f(CW\*(C`RAWPERL\*(C'\fR blocks will be included in the compiled template and will get executed when the template is processed. This will happen regardless of the runtime \&\f(CW\*(C`EVAL_PERL\*(C'\fR status. .PP Regular \f(CW\*(C`PERL\*(C'\fR blocks are a little more cautious, however. If the \&\f(CW\*(C`EVAL_PERL\*(C'\fR flag isn't set for the \fIcurrent\fR context, that is, the one which is trying to process it, then it will throw the familiar '\f(CW\*(C`perl\*(C'\fR' exception with the message, '\f(CW\*(C`EVAL_PERL not set\*(C'\fR'. .PP Thus you can compile templates to include \f(CW\*(C`PERL\*(C'\fR blocks, but optionally disable them when you process them later. Note however that it is possible for a \f(CW\*(C`PERL\*(C'\fR block to contain a Perl "\f(CW\*(C`BEGIN { # some code }\*(C'\fR" block which will always get run regardless of the runtime \f(CW\*(C`EVAL_PERL\*(C'\fR status. Thus, if you set \f(CW\*(C`EVAL_PERL\*(C'\fR when compiling templates, it is assumed that you trust the templates to Do The Right Thing. Otherwise you must accept the fact that there's no bulletproof way to prevent any included code from trampling around in the living room of the runtime environment, making a real nuisance of itself if it really wants to. If you don't like the idea of such uninvited guests causing a bother, then you can accept the default and keep \f(CW\*(C`EVAL_PERL\*(C'\fR disabled. .SS "\s-1OUTPUT\s0" .IX Subsection "OUTPUT" Default output location or handler. This may be specified as one of: a file name (relative to \f(CW\*(C`OUTPUT_PATH\*(C'\fR, if defined, or the current working directory if not specified absolutely); a file handle (e.g. \f(CW\*(C`GLOB\*(C'\fR or IO::Handle) opened for writing; a reference to a text string to which the output is appended (the string isn't cleared); a reference to a subroutine which is called, passing the output text as an argument; as a reference to an array, onto which the content will be \&\f(CW\*(C`push()\*(C'\fRed; or as a reference to any object that supports the \f(CW\*(C`print()\*(C'\fR method. This latter option includes the \f(CW\*(C`Apache::Request\*(C'\fR object which is passed as the argument to Apache/mod_perl handlers. .PP example 1 (file name): .PP .Vb 3 \& my $template = Template\->new({ \& OUTPUT => "/tmp/foo", \& }); .Ve .PP example 2 (text string): .PP .Vb 4 \& my $output = \*(Aq\*(Aq; \& my $template = Template\->new({ \& OUTPUT => \e$output, \& }); .Ve .PP example 3 (file handle): .PP .Vb 4 \& open (TOUT, ">", $file) || die "$file: $!\en"; \& my $template = Template\->new({ \& OUTPUT => \e*TOUT, \& }); .Ve .PP example 4 (subroutine): .PP .Vb 4 \& sub output { my $out = shift; print "OUTPUT: $out" } \& my $template = Template\->new({ \& OUTPUT => \e&output, \& }); .Ve .PP example 5 (array reference): .PP .Vb 3 \& my $template = Template\->new({ \& OUTPUT => \e@output, \& }) .Ve .PP example 6 (Apache/mod_perl handler): .PP .Vb 7 \& sub handler { \& my $r = shift; \& my $t = Template\->new({ \& OUTPUT => $r, \& }); \& ... \& } .Ve .PP The default \f(CW\*(C`OUTPUT\*(C'\fR location be overridden by passing a third parameter to the Template \fBprocess()\fR method. This can be specified as any of the above argument types. .PP .Vb 6 \& $t\->process($file, $vars, "/tmp/foo"); \& $t\->process($file, $vars, \e$output); \& $t\->process($file, $vars, \e*MYGLOB); \& $t\->process($file, $vars, \e@output); \& $t\->process($file, $vars, $r); # Apache::Request \& ... .Ve .SS "\s-1OUTPUT_PATH\s0" .IX Subsection "OUTPUT_PATH" The \f(CW\*(C`OUTPUT_PATH\*(C'\fR allows a directory to be specified into which output files should be written. An output file can be specified by the \&\f(CW\*(C`OUTPUT\*(C'\fR option, or passed by name as the third parameter to the Template \fBprocess()\fR method. .PP .Vb 4 \& my $template = Template\->new({ \& INCLUDE_PATH => "/tmp/src", \& OUTPUT_PATH => "/tmp/dest", \& }); \& \& my $vars = { \& ... \& }; \& \& foreach my $file (\*(Aqfoo.html\*(Aq, \*(Aqbar.html\*(Aq) { \& $template\->process($file, $vars, $file) \& || die $template\->error(); \& } .Ve .PP This example will read the input files \fI/tmp/src/foo.html\fR and \&\fI/tmp/src/bar.html\fR and write the processed output to \fI/tmp/dest/foo.html\fR and \fI/tmp/dest/bar.html\fR, respectively. .SS "\s-1STRICT\s0" .IX Subsection "STRICT" By default the Template Toolkit will silently ignore the use of undefined variables (a bad design decision that I regret). .PP When the \f(CW\*(C`STRICT\*(C'\fR option is set, the use of any undefined variables or values will cause an exception to be throw. The exception will have a \&\f(CW\*(C`type\*(C'\fR of \f(CW\*(C`var.undef\*(C'\fR and a message of the form \&\*(L"undefined variable: xxx\*(R". .PP .Vb 3 \& my $template = Template\->new( \& STRICT => 1 \& ); .Ve .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \f(CW\*(C`DEBUG\*(C'\fR option can be used to enable debugging within the various different modules that comprise the Template Toolkit. The Template::Constants module defines a set of \&\f(CW\*(C`DEBUG_XXXX\*(C'\fR constants which can be combined using the logical \s-1OR\s0 operator, '\f(CW\*(C`|\*(C'\fR'. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_PARSER | DEBUG_PROVIDER, \& }); .Ve .PP For convenience, you can also provide a string containing a list of lower case debug options, separated by any non-word characters. .PP .Vb 3 \& my $template = Template\->new({ \& DEBUG => \*(Aqparser, provider\*(Aq, \& }); .Ve .PP The following \f(CW\*(C`DEBUG_XXXX\*(C'\fR flags can be used: .IP "\s-1DEBUG_SERVICE\s0" 4 .IX Item "DEBUG_SERVICE" Enables general debugging messages for the Template::Service module. .IP "\s-1DEBUG_CONTEXT\s0" 4 .IX Item "DEBUG_CONTEXT" Enables general debugging messages for the Template::Context module. .IP "\s-1DEBUG_PROVIDER\s0" 4 .IX Item "DEBUG_PROVIDER" Enables general debugging messages for the Template::Provider module. .IP "\s-1DEBUG_PLUGINS\s0" 4 .IX Item "DEBUG_PLUGINS" Enables general debugging messages for the Template::Plugins module. .IP "\s-1DEBUG_FILTERS\s0" 4 .IX Item "DEBUG_FILTERS" Enables general debugging messages for the Template::Filters module. .IP "\s-1DEBUG_PARSER\s0" 4 .IX Item "DEBUG_PARSER" This flag causes the Template::Parser to generate debugging messages that show the Perl code generated by parsing and compiling each template. .IP "\s-1DEBUG_UNDEF\s0" 4 .IX Item "DEBUG_UNDEF" This option causes the Template Toolkit to throw an '\f(CW\*(C`undef\*(C'\fR' error whenever it encounters an undefined variable value. .IP "\s-1DEBUG_DIRS\s0" 4 .IX Item "DEBUG_DIRS" This option causes the Template Toolkit to generate comments indicating the source file, line and original text of each directive in the template. These comments are embedded in the template output using the format defined in the \f(CW\*(C`DEBUG_FORMAT\*(C'\fR configuration item, or a simple default format if unspecified. .Sp For example, the following template fragment: .Sp .Vb 1 \& Hello World .Ve .Sp would generate this output: .Sp .Vb 4 \& ## input text line 1 : ## \& Hello \& ## input text line 2 : World ## \& World .Ve .IP "\s-1DEBUG_ALL\s0" 4 .IX Item "DEBUG_ALL" Enables all debugging messages. .IP "\s-1DEBUG_CALLER\s0" 4 .IX Item "DEBUG_CALLER" This option causes all debug messages that aren't newline terminated to have the file name and line number of the caller appended to them. .SS "\s-1DEBUG_FORMAT\s0" .IX Subsection "DEBUG_FORMAT" The \f(CW\*(C`DEBUG_FORMAT\*(C'\fR option can be used to specify a format string for the debugging messages generated via the \f(CW\*(C`DEBUG_DIRS\*(C'\fR option described above. Any occurrences of \f(CW$file\fR, \f(CW$line\fR or \f(CW$text\fR will be replaced with the current file name, line or directive text, respectively. Notice how the format is single quoted to prevent Perl from interpolating those tokens as variables. .PP .Vb 4 \& my $template = Template\->new({ \& DEBUG => \*(Aqdirs\*(Aq, \& DEBUG_FORMAT => \*(Aq<!\-\- $file line $line : [% $text %] \-\->\*(Aq, \& }); .Ve .PP The following template fragment: .PP .Vb 2 \& [% foo = \*(AqWorld\*(Aq %] \& Hello [% foo %] .Ve .PP would then generate this output: .PP .Vb 2 \& <!\-\- input text line 2 : [% foo = \*(AqWorld\*(Aq %] \-\-> \& Hello <!\-\- input text line 3 : [% foo %] \-\->World .Ve .PP The \s-1DEBUG\s0 directive can also be used to set a debug format within a template. .PP .Vb 1 \& [% DEBUG format \*(Aq<!\-\- $file line $line : [% $text %] \-\->\*(Aq %] .Ve .SH "Caching and Compiling Options" .IX Header "Caching and Compiling Options" .SS "\s-1CACHE_SIZE\s0" .IX Subsection "CACHE_SIZE" The Template::Provider module caches compiled templates to avoid the need to re-parse template files or blocks each time they are used. The \f(CW\*(C`CACHE_SIZE\*(C'\fR option is used to limit the number of compiled templates that the module should cache. .PP By default, the \f(CW\*(C`CACHE_SIZE\*(C'\fR is undefined and all compiled templates are cached. When set to any positive value, the cache will be limited to storing no more than that number of compiled templates. When a new template is loaded and compiled and the cache is full (i.e. the number of entries == \f(CW\*(C`CACHE_SIZE\*(C'\fR), the least recently used compiled template is discarded to make room for the new one. .PP The \f(CW\*(C`CACHE_SIZE\*(C'\fR can be set to \f(CW0\fR to disable caching altogether. .PP .Vb 3 \& my $template = Template\->new({ \& CACHE_SIZE => 64, # only cache 64 compiled templates \& }); \& \& my $template = Template\->new({ \& CACHE_SIZE => 0, # don\*(Aqt cache any compiled templates \& }); .Ve .PP As well as caching templates as they are found, the Template::Provider also implements negative caching to keep track of templates that are \&\fInot\fR found. This allows the provider to quickly decline a request for a template that it has previously failed to locate, saving the effort of going to look for it again. This is useful when an \f(CW\*(C`INCLUDE_PATH\*(C'\fR includes multiple providers, ensuring that the request is passed down through the providers as quickly as possible. .SS "\s-1STAT_TTL\s0" .IX Subsection "STAT_TTL" This value can be set to control how long the Template::Provider will keep a template cached in memory before checking to see if the source template has changed. .PP .Vb 3 \& my $provider = Template::Provider\->new({ \& STAT_TTL => 60, # one minute \& }); .Ve .PP The default value is 1 (second). You'll probably want to set this to a higher value if you're running the Template Toolkit inside a persistent web server application (e.g. mod_perl). For example, set it to 60 and the provider will only look for changes to templates once a minute at most. However, during development (or any time you're making frequent changes to templates) you'll probably want to keep it set to a low value so that you don't have to wait for the provider to notice that your templates have changed. .SS "\s-1COMPILE_EXT\s0" .IX Subsection "COMPILE_EXT" From version 2 onwards, the Template Toolkit has the ability to compile templates to Perl code and save them to disk for subsequent use (i.e. cache persistence). The \f(CW\*(C`COMPILE_EXT\*(C'\fR option may be provided to specify a filename extension for compiled template files. It is undefined by default and no attempt will be made to read or write any compiled template files. .PP .Vb 3 \& my $template = Template\->new({ \& COMPILE_EXT => \*(Aq.ttc\*(Aq, \& }); .Ve .PP If \f(CW\*(C`COMPILE_EXT\*(C'\fR is defined (and \f(CW\*(C`COMPILE_DIR\*(C'\fR isn't, see below) then compiled template files with the \f(CW\*(C`COMPILE_EXT\*(C'\fR extension will be written to the same directory from which the source template files were loaded. .PP Compiling and subsequent reuse of templates happens automatically whenever the \f(CW\*(C`COMPILE_EXT\*(C'\fR or \f(CW\*(C`COMPILE_DIR\*(C'\fR options are set. The Template Toolkit will automatically reload and reuse compiled files when it finds them on disk. If the corresponding source file has been modified since the compiled version as written, then it will load and re-compile the source and write a new compiled version to disk. .PP This form of cache persistence offers significant benefits in terms of time and resources required to reload templates. Compiled templates can be reloaded by a simple call to Perl's \f(CW\*(C`require()\*(C'\fR, leaving Perl to handle all the parsing and compilation. This is a Good Thing. .SS "\s-1COMPILE_DIR\s0" .IX Subsection "COMPILE_DIR" The \f(CW\*(C`COMPILE_DIR\*(C'\fR option is used to specify an alternate directory root under which compiled template files should be saved. .PP .Vb 3 \& my $template = Template\->new({ \& COMPILE_DIR => \*(Aq/tmp/ttc\*(Aq, \& }); .Ve .PP The \f(CW\*(C`COMPILE_EXT\*(C'\fR option may also be specified to have a consistent file extension added to these files. .PP .Vb 4 \& my $template1 = Template\->new({ \& COMPILE_DIR => \*(Aq/tmp/ttc\*(Aq, \& COMPILE_EXT => \*(Aq.ttc1\*(Aq, \& }); \& \& my $template2 = Template\->new({ \& COMPILE_DIR => \*(Aq/tmp/ttc\*(Aq, \& COMPILE_EXT => \*(Aq.ttc2\*(Aq, \& }); .Ve .PP When \f(CW\*(C`COMPILE_EXT\*(C'\fR is undefined, the compiled template files have the same name as the original template files, but reside in a different directory tree. .PP Each directory in the \f(CW\*(C`INCLUDE_PATH\*(C'\fR is replicated in full beneath the \&\f(CW\*(C`COMPILE_DIR\*(C'\fR directory. This example: .PP .Vb 4 \& my $template = Template\->new({ \& COMPILE_DIR => \*(Aq/tmp/ttc\*(Aq, \& INCLUDE_PATH => \*(Aq/home/abw/templates:/usr/share/templates\*(Aq, \& }); .Ve .PP would create the following directory structure: .PP .Vb 2 \& /tmp/ttc/home/abw/templates/ \& /tmp/ttc/usr/share/templates/ .Ve .PP Files loaded from different \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories will have their compiled forms save in the relevant \f(CW\*(C`COMPILE_DIR\*(C'\fR directory. .PP On Win32 platforms a filename may by prefixed by a drive letter and colon. e.g. .PP .Vb 1 \& C:/My Templates/header .Ve .PP The colon will be silently stripped from the filename when it is added to the \f(CW\*(C`COMPILE_DIR\*(C'\fR value(s) to prevent illegal filename being generated. Any colon in \f(CW\*(C`COMPILE_DIR\*(C'\fR elements will be left intact. For example: .PP .Vb 6 \& # Win32 only \& my $template = Template\->new({ \& DELIMITER => \*(Aq;\*(Aq, \& COMPILE_DIR => \*(AqC:/TT2/Cache\*(Aq, \& INCLUDE_PATH => \*(AqC:/TT2/Templates;D:/My Templates\*(Aq, \& }); .Ve .PP This would create the following cache directories: .PP .Vb 2 \& C:/TT2/Cache/C/TT2/Templates \& C:/TT2/Cache/D/My Templates .Ve .SH "Plugins and Filters" .IX Header "Plugins and Filters" .SS "\s-1PLUGINS\s0" .IX Subsection "PLUGINS" The \f(CW\*(C`PLUGINS\*(C'\fR options can be used to provide a reference to a hash array that maps plugin names to Perl module names. A number of standard plugins are defined (e.g. \f(CW\*(C`table\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`cgi\*(C'\fR, etc.) which map to their corresponding \f(CW\*(C`Template::Plugin::*\*(C'\fR counterparts. These can be redefined by values in the \f(CW\*(C`PLUGINS\*(C'\fR hash. .PP .Vb 7 \& my $template = Template\->new({ \& PLUGINS => { \& cgi => \*(AqMyOrg::Template::Plugin::CGI\*(Aq, \& foo => \*(AqMyOrg::Template::Plugin::Foo\*(Aq, \& bar => \*(AqMyOrg::Template::Plugin::Bar\*(Aq, \& }, \& }); .Ve .PP The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified. .PP .Vb 1 \& [% USE Foo %] # look for \*(AqFoo\*(Aq then \*(Aqfoo\*(Aq .Ve .PP If you define all your \f(CW\*(C`PLUGINS\*(C'\fR with lower case names then they will be located regardless of how the user specifies the name in the \s-1USE\s0 directive. If, on the other hand, you define your \f(CW\*(C`PLUGINS\*(C'\fR with upper or mixed case names then the name specified in the \f(CW\*(C`USE\*(C'\fR directive must match the case exactly. .PP The \f(CW\*(C`USE\*(C'\fR directive is used to create plugin objects and does so by calling the \fBplugin()\fR method on the current Template::Context object. If the plugin name is defined in the \f(CW\*(C`PLUGINS\*(C'\fR hash then the corresponding Perl module is loaded via \f(CW\*(C`require()\*(C'\fR. The context then calls the \fBload()\fR class method which should return the class name (default and general case) or a prototype object against which the \fBnew()\fR method can be called to instantiate individual plugin objects. .PP If the plugin name is not defined in the \f(CW\*(C`PLUGINS\*(C'\fR hash then the \&\f(CW\*(C`PLUGIN_BASE\*(C'\fR and/or \f(CW\*(C`LOAD_PERL\*(C'\fR options come into effect. .SS "\s-1PLUGIN_BASE\s0" .IX Subsection "PLUGIN_BASE" If a plugin is not defined in the \f(CW\*(C`PLUGINS\*(C'\fR hash then the \f(CW\*(C`PLUGIN_BASE\*(C'\fR is used to attempt to construct a correct Perl module name which can be successfully loaded. .PP The \f(CW\*(C`PLUGIN_BASE\*(C'\fR can be specified as a reference to an array of module namespaces, or as a single value which is automatically converted to a list. The default \f(CW\*(C`PLUGIN_BASE\*(C'\fR value (\f(CW\*(C`Template::Plugin\*(C'\fR) is then added to the end of this list. .PP example 1: .PP .Vb 3 \& my $template = Template\->new({ \& PLUGIN_BASE => \*(AqMyOrg::Template::Plugin\*(Aq, \& }); \& \& [% USE Foo %] # => MyOrg::Template::Plugin::Foo \& or Template::Plugin::Foo .Ve .PP example 2: .PP .Vb 4 \& my $template = Template\->new({ \& PLUGIN_BASE => [ \*(AqMyOrg::Template::Plugin\*(Aq, \& \*(AqYourOrg::Template::Plugin\*(Aq ], \& }); .Ve .PP template: .PP .Vb 3 \& [% USE Foo %] # => MyOrg::Template::Plugin::Foo \& or YourOrg::Template::Plugin::Foo \& or Template::Plugin::Foo .Ve .PP If you don't want the default \f(CW\*(C`Template::Plugin\*(C'\fR namespace added to the end of the \f(CW\*(C`PLUGIN_BASE\*(C'\fR, then set the \f(CW$Template::Plugins::PLUGIN_BASE\fR variable to a false value before calling the \fBnew()\fR Template#\fBnew()\fR constructor method. This is shown in the example below where the \&\f(CW\*(C`Foo\*(C'\fR plugin is located as \f(CW\*(C`My::Plugin::Foo\*(C'\fR or \f(CW\*(C`Your::Plugin::Foo\*(C'\fR but not as \f(CW\*(C`Template::Plugin::Foo\*(C'\fR. .PP example 3: .PP .Vb 2 \& use Template::Plugins; \& $Template::Plugins::PLUGIN_BASE = \*(Aq\*(Aq; \& \& my $template = Template\->new({ \& PLUGIN_BASE => [ \*(AqMy::Plugin\*(Aq, \& \*(AqYour::Plugin\*(Aq ], \& }); .Ve .PP template: .PP .Vb 2 \& [% USE Foo %] # => My::Plugin::Foo \& or Your::Plugin::Foo .Ve .SS "\s-1LOAD_PERL\s0" .IX Subsection "LOAD_PERL" If a plugin cannot be loaded using the \f(CW\*(C`PLUGINS\*(C'\fR or \f(CW\*(C`PLUGIN_BASE\*(C'\fR approaches then the provider can make a final attempt to load the module without prepending any prefix to the module path. This allows regular Perl modules (i.e. those that don't reside in the Template::Plugin or some other such namespace) to be loaded and used as plugins. .PP By default, the \f(CW\*(C`LOAD_PERL\*(C'\fR option is set to \f(CW0\fR and no attempt will be made to load any Perl modules that aren't named explicitly in the \f(CW\*(C`PLUGINS\*(C'\fR hash or reside in a package as named by one of the \f(CW\*(C`PLUGIN_BASE\*(C'\fR components. .PP Plugins loaded using the \f(CW\*(C`PLUGINS\*(C'\fR or \f(CW\*(C`PLUGIN_BASE\*(C'\fR receive a reference to the current context object as the first argument to the \&\fBnew()\fR constructor. Modules loaded using \f(CW\*(C`LOAD_PERL\*(C'\fR are assumed to not conform to the plugin interface. They must provide a \f(CW\*(C`new()\*(C'\fR class method for instantiating objects but it will not receive a reference to the context as the first argument. .PP Plugin modules should provide a \fBload()\fR class method (or inherit the default one from the Template::Plugin base class) which is called the first time the plugin is loaded. Regular Perl modules need not. In all other respects, regular Perl objects and Template Toolkit plugins are identical. .PP If a particular Perl module does not conform to the common, but not unilateral, \f(CW\*(C`new()\*(C'\fR constructor convention then a simple plugin wrapper can be written to interface to it. .SS "\s-1FILTERS\s0" .IX Subsection "FILTERS" The \f(CW\*(C`FILTERS\*(C'\fR option can be used to specify custom filters which can then be used with the \f(CW\*(C`FILTER\*(C'\fR directive like any other. These are added to the standard filters which are available by default. Filters specified via this option will mask any standard filters of the same name. .PP The \f(CW\*(C`FILTERS\*(C'\fR option should be specified as a reference to a hash array in which each key represents the name of a filter. The corresponding value should contain a reference to an array containing a subroutine reference and a flag which indicates if the filter is static (\f(CW0\fR) or dynamic (\f(CW1\fR). A filter may also be specified as a solitary subroutine reference and is assumed to be static. .PP .Vb 7 \& $template = Template\->new({ \& FILTERS => { \& \*(Aqsfilt1\*(Aq => \e&static_filter, # static \& \*(Aqsfilt2\*(Aq => [ \e&static_filter, 0 ], # same as above \& \*(Aqdfilt1\*(Aq => [ \e&dyanamic_filter_factory, 1 ], \& }, \& }); .Ve .PP Additional filters can be specified at any time by calling the \&\fBdefine_filter()\fR method on the current Template::Context object. The method accepts a filter name, a reference to a filter subroutine and an optional flag to indicate if the filter is dynamic. .PP .Vb 3 \& my $context = $template\->context(); \& $context\->define_filter(\*(Aqnew_html\*(Aq, \e&new_html); \& $context\->define_filter(\*(Aqnew_repeat\*(Aq, \e&new_repeat, 1); .Ve .PP Static filters are those where a single subroutine reference is used for all invocations of a particular filter. Filters that don't accept any configuration parameters (e.g. \f(CW\*(C`html\*(C'\fR) can be implemented statically. The subroutine reference is simply returned when that particular filter is requested. The subroutine is called to filter the output of a template block which is passed as the only argument. The subroutine should return the modified text. .PP .Vb 5 \& sub static_filter { \& my $text = shift; \& # do something to modify $text... \& return $text; \& } .Ve .PP The following template fragment: .PP .Vb 3 \& [% FILTER sfilt1 %] \& Blah blah blah. \& [% END %] .Ve .PP is approximately equivalent to: .PP .Vb 1 \& &static_filter("\enBlah blah blah.\en"); .Ve .PP Filters that can accept parameters (e.g. \f(CW\*(C`truncate\*(C'\fR) should be implemented dynamically. In this case, the subroutine is taken to be a filter 'factory' that is called to create a unique filter subroutine each time one is requested. A reference to the current Template::Context object is passed as the first parameter, followed by any additional parameters specified. The subroutine should return another subroutine reference (usually a closure) which implements the filter. .PP .Vb 2 \& sub dynamic_filter_factory { \& my ($context, @args) = @_; \& \& return sub { \& my $text = shift; \& # do something to modify $text... \& return $text; \& } \& } .Ve .PP The following template fragment: .PP .Vb 3 \& [% FILTER dfilt1(123, 456) %] \& Blah blah blah \& [% END %] .Ve .PP is approximately equivalent to: .PP .Vb 2 \& my $filter = &dynamic_filter_factory($context, 123, 456); \& &$filter("\enBlah blah blah.\en"); .Ve .PP See the \f(CW\*(C`FILTER\*(C'\fR directive for further examples. .SH "Customisation and Extension" .IX Header "Customisation and Extension" .SS "\s-1LOAD_TEMPLATES\s0" .IX Subsection "LOAD_TEMPLATES" The \f(CW\*(C`LOAD_TEMPLATES\*(C'\fR option can be used to provide a reference to a list of Template::Provider objects or sub-classes thereof which will take responsibility for loading and compiling templates. .PP .Vb 6 \& my $template = Template\->new({ \& LOAD_TEMPLATES => [ \& MyOrg::Template::Provider\->new({ ... }), \& Template::Provider\->new({ ... }), \& ], \& }); .Ve .PP When a \f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`INCLUDE\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive is encountered, the named template may refer to a locally defined \f(CW\*(C`BLOCK\*(C'\fR or a file relative to the \f(CW\*(C`INCLUDE_PATH\*(C'\fR (or an absolute or relative path if the appropriate \&\f(CW\*(C`ABSOLUTE\*(C'\fR or \f(CW\*(C`RELATIVE\*(C'\fR options are set). If a \f(CW\*(C`BLOCK\*(C'\fR definition can't be found (see the Template::Context \fBtemplate()\fR method for a discussion of \f(CW\*(C`BLOCK\*(C'\fR locality) then each of the \&\f(CW\*(C`LOAD_TEMPLATES\*(C'\fR provider objects is queried in turn via the \&\fBfetch()\fR method to see if it can supply the required template. .PP Each provider can return a compiled template, an error, or decline to service the request in which case the responsibility is passed to the next provider. If none of the providers can service the request then a 'not found' error is returned. The same basic provider mechanism is also used for the \f(CW\*(C`INSERT\*(C'\fR directive but it bypasses any \f(CW\*(C`BLOCK\*(C'\fR definitions and doesn't attempt is to parse or process the contents of the template file. .PP If \f(CW\*(C`LOAD_TEMPLATES\*(C'\fR is undefined, a single default provider will be instantiated using the current configuration parameters. For example, the Template::Provider \f(CW\*(C`INCLUDE_PATH\*(C'\fR option can be specified in the Template configuration and will be correctly passed to the provider's constructor method. .PP .Vb 3 \& my $template = Template\->new({ \& INCLUDE_PATH => \*(Aq/here:/there\*(Aq, \& }); .Ve .SS "\s-1LOAD_PLUGINS\s0" .IX Subsection "LOAD_PLUGINS" The \f(CW\*(C`LOAD_PLUGINS\*(C'\fR options can be used to specify a list of provider objects (i.e. they implement the \fBfetch()\fR method) which are responsible for loading and instantiating template plugin objects. The Template::Context \fBplugin()\fR method queries each provider in turn in a \*(L"Chain of Responsibility\*(R" as per the \&\fBtemplate()\fR and \&\fBfilter()\fR methods. .PP .Vb 6 \& my $template = Template\->new({ \& LOAD_PLUGINS => [ \& MyOrg::Template::Plugins\->new({ ... }), \& Template::Plugins\->new({ ... }), \& ], \& }); .Ve .PP By default, a single Template::Plugins object is created using the current configuration hash. Configuration items destined for the Template::Plugins constructor may be added to the Template constructor. .PP .Vb 4 \& my $template = Template\->new({ \& PLUGIN_BASE => \*(AqMyOrg::Template::Plugins\*(Aq, \& LOAD_PERL => 1, \& }); .Ve .SS "\s-1LOAD_FILTERS\s0" .IX Subsection "LOAD_FILTERS" The \f(CW\*(C`LOAD_FILTERS\*(C'\fR option can be used to specify a list of provider objects (i.e. they implement the \fBfetch()\fR method) which are responsible for returning and/or creating filter subroutines. The Template::Context \fBfilter()\fR method queries each provider in turn in a \*(L"Chain of Responsibility\*(R" as per the \&\fBtemplate()\fR and \&\fBplugin()\fR methods. .PP .Vb 6 \& my $template = Template\->new({ \& LOAD_FILTERS => [ \& MyTemplate::Filters\->new(), \& Template::Filters\->new(), \& ], \& }); .Ve .PP By default, a single Template::Filters object is created for the \&\f(CW\*(C`LOAD_FILTERS\*(C'\fR list. .SS "\s-1TOLERANT\s0" .IX Subsection "TOLERANT" The \f(CW\*(C`TOLERANT\*(C'\fR flag is used by the various Template Toolkit provider modules (Template::Provider, Template::Plugins, Template::Filters) to control their behaviour when errors are encountered. By default, any errors are reported as such, with the request for the particular resource (\f(CW\*(C`template\*(C'\fR, \&\f(CW\*(C`plugin\*(C'\fR, \f(CW\*(C`filter\*(C'\fR) being denied and an exception raised. .PP When the \f(CW\*(C`TOLERANT\*(C'\fR flag is set to any true values, errors will be silently ignored and the provider will instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR. This allows a subsequent provider to take responsibility for providing the resource, rather than failing the request outright. If all providers decline to service the request, either through tolerated failure or a genuine disinclination to comply, then a '\f(CW\*(C`<resource> not found\*(C'\fR' exception is raised. .SS "\s-1SERVICE\s0" .IX Subsection "SERVICE" A reference to a Template::Service object, or sub-class thereof, to which the Template module should delegate. If unspecified, a Template::Service object is automatically created using the current configuration hash. .PP .Vb 3 \& my $template = Template\->new({ \& SERVICE => MyOrg::Template::Service\->new({ ... }), \& }); .Ve .SS "\s-1CONTEXT\s0" .IX Subsection "CONTEXT" A reference to a Template::Context object which is used to define a specific environment in which template are processed. A Template::Context object is passed as the only parameter to the Perl subroutines that represent \&\*(L"compiled\*(R" template documents. Template subroutines make callbacks into the context object to access Template Toolkit functionality, for example, to \&\f(CW\*(C`INCLUDE\*(C'\fR or \f(CW\*(C`PROCESS\*(C'\fR another template (\fBinclude()\fR and \&\fBprocess()\fR methods, respectively), to \f(CW\*(C`USE\*(C'\fR a plugin (\fBplugin()\fR) or instantiate a filter (\fBfilter()\fR) or to access the stash (\fBstash()\fR) which manages variable definitions via the \fBget()\fR and \fBset()\fR methods. .PP .Vb 3 \& my $template = Template\->new({ \& CONTEXT => MyOrg::Template::Context\->new({ ... }), \& }); .Ve .SS "\s-1STASH\s0" .IX Subsection "STASH" A reference to a Template::Stash object or sub-class which will take responsibility for managing template variables. .PP .Vb 4 \& my $stash = MyOrg::Template::Stash\->new({ ... }); \& my $template = Template\->new({ \& STASH => $stash, \& }); .Ve .PP If unspecified, a default stash object is created using the \f(CW\*(C`VARIABLES\*(C'\fR configuration item to initialise the stash variables. .PP .Vb 6 \& my $template = Template\->new({ \& VARIABLES => { \& id => \*(Aqabw\*(Aq, \& name => \*(AqAndy Wardley\*(Aq, \& }, \& }; .Ve .SS "\s-1PARSER\s0" .IX Subsection "PARSER" The Template::Parser module implements a parser object for compiling templates into Perl code which can then be executed. A default object of this class is created automatically and then used by the Template::Provider whenever a template is loaded and requires compilation. The \f(CW\*(C`PARSER\*(C'\fR option can be used to provide a reference to an alternate parser object. .PP .Vb 3 \& my $template = Template\->new({ \& PARSER => MyOrg::Template::Parser\->new({ ... }), \& }); .Ve .SS "\s-1GRAMMAR\s0" .IX Subsection "GRAMMAR" The \f(CW\*(C`GRAMMAR\*(C'\fR configuration item can be used to specify an alternate grammar for the parser. This allows a modified or entirely new template language to be constructed and used by the Template Toolkit. .PP Source templates are compiled to Perl code by the Template::Parser using the Template::Grammar (by default) to define the language structure and semantics. Compiled templates are thus inherently \&\*(L"compatible\*(R" with each other and there is nothing to prevent any number of different template languages being compiled and used within the same Template Toolkit processing environment (other than the usual time and memory constraints). .PP The Template::Grammar file is constructed from a \s-1YACC\s0 like grammar (using \f(CW\*(C`Parse::YAPP\*(C'\fR) and a skeleton module template. These files are provided, along with a small script to rebuild the grammar, in the \&\fIparser\fR sub-directory of the distribution. .PP You don't have to know or worry about these unless you want to hack on the template language or define your own variant. There is a \fI\s-1README\s0\fR file in the same directory which provides some small guidance but it is assumed that you know what you're doing if you venture herein. If you grok \s-1LALR\s0 parsers, then you should find it comfortably familiar. .PP By default, an instance of the default Template::Grammar will be created and used automatically if a \f(CW\*(C`GRAMMAR\*(C'\fR item isn't specified. .PP .Vb 1 \& use MyOrg::Template::Grammar; \& \& my $template = Template\->new({ \& GRAMMAR = MyOrg::Template::Grammar\->new(); \& }); .Ve PK � �[ɞ�,� � # man3/Template::Plugin::Iterator.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Iterator 3" .TH Template::Plugin::Iterator 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Iterator \- Plugin to create iterators (Template::Iterator) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE iterator(list, args) %] \& \& [% FOREACH item = iterator %] \& [% \*(Aq<ul>\*(Aq IF iterator.first %] \& <li>[% item %] \& [% \*(Aq</ul>\*(Aq IF iterator.last %] \& [% END %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The iterator plugin provides a way to create a Template::Iterator object to iterate over a data set. An iterator is implicitly automatically by the \&\s-1FOREACH\s0 directive. This plugin allows the iterator to be explicitly created with a given name. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Template::Iterator PK � �[z��A A man3/Template::Plugin::View.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::View 3" .TH Template::Plugin::View 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::View \- Plugin to create views (Template::View) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 8 \& [% USE view( \& prefix = \*(Aqsplash/\*(Aq # template prefix/suffix \& suffix = \*(Aq.tt2\*(Aq \& bgcol = \*(Aq#ffffff\*(Aq # and any other variables you \& style = \*(AqFancy HTML\*(Aq # care to define as view metadata, \& items = [ foo, bar.baz ] # including complex data and \& foo = bar ? baz : x.y.z # expressions \& %] \& \& [% view.title %] # access view metadata \& \& [% view.header(title = \*(AqFoo!\*(Aq) %] # view "methods" process blocks or \& [% view.footer %] # templates with prefix/suffix added .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin module creates Template::View objects. Views are an experimental feature and are subject to change in the near future. In the mean time, please consult Template::View for further info. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Template::View, Template::Manual::Views PK � �[T%� man3/Template::App::ttree.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::App::ttree 3" .TH Template::App::ttree 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::App::ttree \- Backend of ttree .SH "SYNOPSIS" .IX Header "SYNOPSIS" See Template::Tools::ttree. .SH "DESCRIPTION" .IX Header "DESCRIPTION" See Template::Tools::ttree. .SH "AUTHORS" .IX Header "AUTHORS" Andy Wardley <abw@wardley.org> .PP <http://www.wardley.org> .PP With contributions from Dylan William Hardison (support for dependencies), Bryce Harrington (\f(CW\*(C`absolute\*(C'\fR and \f(CW\*(C`relative\*(C'\fR options), Mark Anderson (\f(CW\*(C`suffix\*(C'\fR and \f(CW\*(C`debug\*(C'\fR options), Harald Joerg and Leon Brocard who gets everywhere, it seems. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Tools::ttree PK � �[=�r�2 2 man3/Template::Filters.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Filters 3" .TH Template::Filters 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Filters \- Post\-processing filters for template blocks .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Filters; \& \& $filters = Template::Filters\->new(\e%config); \& \& ($filter, $error) = $filters\->fetch($name, \e@args, $context); \& \& if ($filter) { \& print &$filter("some text"); \& } \& else { \& print "Could not fetch $name filter: $error\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Filters\*(C'\fR module implements a provider for creating subroutines that implement the standard filters. Additional custom filters may be provided via the \s-1FILTERS\s0 configuration option. .SH "METHODS" .IX Header "METHODS" .SS "new(\e%params)" .IX Subsection "new(%params)" Constructor method which instantiates and returns a reference to a \&\f(CW\*(C`Template::Filters\*(C'\fR object. A reference to a hash array of configuration items may be passed as a parameter. These are described below. .PP .Vb 3 \& my $filters = Template::Filters\->new({ \& FILTERS => { ... }, \& }); \& \& my $template = Template\->new({ \& LOAD_FILTERS => [ $filters ], \& }); .Ve .PP A default \f(CW\*(C`Template::Filters\*(C'\fR module is created by the Template module if the \s-1LOAD_FILTERS\s0 option isn't specified. All configuration parameters are forwarded to the constructor. .PP .Vb 3 \& $template = Template\->new({ \& FILTERS => { ... }, \& }); .Ve .ie n .SS "fetch($name, \e@args, $context)" .el .SS "fetch($name, \e@args, \f(CW$context\fP)" .IX Subsection "fetch($name, @args, $context)" Called to request that a filter of a given name be provided. The name of the filter should be specified as the first parameter. This should be one of the standard filters or one specified in the \s-1FILTERS\s0 configuration hash. The second argument should be a reference to an array containing configuration parameters for the filter. This may be specified as 0, or undef where no parameters are provided. The third argument should be a reference to the current Template::Context object. .PP The method returns a reference to a filter sub-routine on success. It may also return \f(CW\*(C`(undef, STATUS_DECLINE)\*(C'\fR to decline the request, to allow delegation onto other filter providers in the \s-1LOAD_FILTERS\s0 chain of responsibility. On error, \f(CW\*(C`($error, STATUS_ERROR)\*(C'\fR is returned where \f(CW$error\fR is an error message or Template::Exception object indicating the error that occurred. .PP When the \f(CW\*(C`TOLERANT\*(C'\fR option is set, errors are automatically downgraded to a \f(CW\*(C`STATUS_DECLINE\*(C'\fR response. .SS "\fBuse_html_entities()\fP" .IX Subsection "use_html_entities()" This class method can be called to configure the \f(CW\*(C`html_entity\*(C'\fR filter to use the HTML::Entities module. An error will be raised if it is not installed on your system. .PP .Vb 2 \& use Template::Filters; \& Template::Filters\->use_html_entities(); .Ve .SS "\fBuse_apache_util()\fP" .IX Subsection "use_apache_util()" This class method can be called to configure the \f(CW\*(C`html_entity\*(C'\fR filter to use the Apache::Util module. An error will be raised if it is not installed on your system. .PP .Vb 2 \& use Template::Filters; \& Template::Filters\->use_apache_util(); .Ve .SS "\fBuse_rfc2732()\fP" .IX Subsection "use_rfc2732()" This class method can be called to configure the \f(CW\*(C`uri\*(C'\fR and \f(CW\*(C`url\*(C'\fR filters to use the older \s-1RFC2732\s0 standard for matching unsafe characters. .SS "\fBuse_rfc3986()\fP" .IX Subsection "use_rfc3986()" This class method can be called to configure the \f(CW\*(C`uri\*(C'\fR and \f(CW\*(C`url\*(C'\fR filters to use the newer \s-1RFC3986\s0 standard for matching unsafe characters. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" The following list summarises the configuration options that can be provided to the \f(CW\*(C`Template::Filters\*(C'\fR \fBnew()\fR constructor. Please see Template::Manual::Config for further information about each option. .SS "\s-1FILTERS\s0" .IX Subsection "FILTERS" The \s-1FILTERS\s0 option can be used to specify custom filters which can then be used with the \&\s-1FILTER\s0 directive like any other. These are added to the standard filters which are available by default. .PP .Vb 6 \& $filters = Template::Filters\->new({ \& FILTERS => { \& \*(Aqsfilt1\*(Aq => \e&static_filter, \& \*(Aqdfilt1\*(Aq => [ \e&dyanamic_filter_factory, 1 ], \& }, \& }); .Ve .SS "\s-1TOLERANT\s0" .IX Subsection "TOLERANT" The \s-1TOLERANT\s0 flag can be set to indicate that the \f(CW\*(C`Template::Filters\*(C'\fR module should ignore any errors and instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR. .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \s-1DEBUG\s0 option can be used to enable debugging messages for the Template::Filters module by setting it to include the \f(CW\*(C`DEBUG_FILTERS\*(C'\fR value. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS, \& }); .Ve .SH "STANDARD FILTERS" .IX Header "STANDARD FILTERS" Please see Template::Manual::Filters for a list of the filters provided with the Template Toolkit, complete with examples of use. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-20202Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Manual::Filters, Template, Template::Context PK � �[���L< L< ! man3/Template::Plugin::String.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::String 3" .TH Template::Plugin::String 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::String \- Object oriented interface for string manipulation .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& # create String objects via USE directive \& [% USE String %] \& [% USE String \*(Aqinitial text\*(Aq %] \& [% USE String text => \*(Aqinitial text\*(Aq %] \& \& # or from an existing String via new() \& [% newstring = String.new %] \& [% newstring = String.new(\*(Aqnewstring text\*(Aq) %] \& [% newstring = String.new( text => \*(Aqnewstring text\*(Aq ) %] \& \& # or from an existing String via copy() \& [% newstring = String.copy %] \& \& # append text to string \& [% String.append(\*(Aqtext to append\*(Aq) %] \& \& # format left, right or center/centre padded \& [% String.left(20) %] \& [% String.right(20) %] \& [% String.center(20) %] # American spelling \& [% String.centre(20) %] # European spelling \& \& # and various other methods... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a \f(CW\*(C`String\*(C'\fR class for doing stringy things to text in an object-oriented way. .PP You can create a \f(CW\*(C`String\*(C'\fR object via the \f(CW\*(C`USE\*(C'\fR directive, adding any initial text value as an argument or as the named parameter \f(CW\*(C`text\*(C'\fR. .PP .Vb 3 \& [% USE String %] \& [% USE String \*(Aqinitial text\*(Aq %] \& [% USE String text=\*(Aqinitial text\*(Aq %] .Ve .PP The object created will be referenced as \f(CW\*(C`String\*(C'\fR by default, but you can provide a different variable name for the object to be assigned to: .PP .Vb 1 \& [% USE greeting = String \*(AqHello World\*(Aq %] .Ve .PP Once you've got a \f(CW\*(C`String\*(C'\fR object, you can use it as a prototype to create other \f(CW\*(C`String\*(C'\fR objects with the \f(CW\*(C`new()\*(C'\fR method. .PP .Vb 2 \& [% USE String %] \& [% greeting = String.new(\*(AqHello World\*(Aq) %] .Ve .PP The \f(CW\*(C`new()\*(C'\fR method also accepts an initial text string as an argument or the named parameter \f(CW\*(C`text\*(C'\fR. .PP .Vb 1 \& [% greeting = String.new( text => \*(AqHello World\*(Aq ) %] .Ve .PP You can also call \f(CW\*(C`copy()\*(C'\fR to create a new \f(CW\*(C`String\*(C'\fR as a copy of the original. .PP .Vb 1 \& [% greet2 = greeting.copy %] .Ve .PP The \f(CW\*(C`String\*(C'\fR object has a \f(CW\*(C`text()\*(C'\fR method to return the content of the string. .PP .Vb 1 \& [% greeting.text %] .Ve .PP However, it is sufficient to simply print the string and let the overloaded stringification operator call the \f(CW\*(C`text()\*(C'\fR method automatically for you. .PP .Vb 1 \& [% greeting %] .Ve .PP Thus, you can treat \f(CW\*(C`String\*(C'\fR objects pretty much like any regular piece of text, interpolating it into other strings, for example: .PP .Vb 1 \& [% msg = "It printed \*(Aq$greeting\*(Aq and then dumped core\en" %] .Ve .PP You also have the benefit of numerous other methods for manipulating the string. .PP .Vb 1 \& [% msg.append("PS Don\*(Aqt eat the yellow snow") %] .Ve .PP Note that all methods operate on and mutate the contents of the string itself. If you want to operate on a copy of the string then simply take a copy first: .PP .Vb 1 \& [% msg.copy.append("PS Don\*(Aqt eat the yellow snow") %] .Ve .PP These methods return a reference to the \f(CW\*(C`String\*(C'\fR object itself. This allows you to chain multiple methods together. .PP .Vb 1 \& [% msg.copy.append(\*(Aqfoo\*(Aq).right(72) %] .Ve .PP It also means that in the above examples, the \f(CW\*(C`String\*(C'\fR is returned which causes the \f(CW\*(C`text()\*(C'\fR method to be called, which results in the new value of the string being printed. To suppress printing of the string, you can use the \f(CW\*(C`CALL\*(C'\fR directive. .PP .Vb 1 \& [% foo = String.new(\*(Aqfoo\*(Aq) %] \& \& [% foo.append(\*(Aqbar\*(Aq) %] # prints "foobar" \& \& [% CALL foo.append(\*(Aqbar\*(Aq) %] # nothing .Ve .SH "CONSTRUCTOR METHODS" .IX Header "CONSTRUCTOR METHODS" These methods are used to create new \f(CW\*(C`String\*(C'\fR objects. .SS "\fBnew()\fP" .IX Subsection "new()" Creates a new string using an initial value passed as a positional argument or the named parameter \f(CW\*(C`text\*(C'\fR. .PP .Vb 3 \& [% USE String %] \& [% msg = String.new(\*(AqHello World\*(Aq) %] \& [% msg = String.new( text => \*(AqHello World\*(Aq ) %] .Ve .SS "\fBcopy()\fP" .IX Subsection "copy()" Creates a new \f(CW\*(C`String\*(C'\fR object which contains a copy of the original string. .PP .Vb 1 \& [% msg2 = msg.copy %] .Ve .SH "INSPECTOR METHODS" .IX Header "INSPECTOR METHODS" These methods are used to examine the string. .SS "\fBtext()\fP" .IX Subsection "text()" Returns the internal text value of the string. The stringification operator is overloaded to call this method. Thus the following are equivalent: .PP .Vb 2 \& [% msg.text %] \& [% msg %] .Ve .SS "\fBlength()\fP" .IX Subsection "length()" Returns the length of the string. .PP .Vb 2 \& [% USE String("foo") %] \& [% String.length %] # => 3 .Ve .SS "search($pattern)" .IX Subsection "search($pattern)" Searches the string for the regular expression specified in \f(CW$pattern\fR returning true if found or false otherwise. .PP .Vb 2 \& [% item = String.new(\*(Aqfoo bar baz wiz waz woz\*(Aq) %] \& [% item.search(\*(Aqwiz\*(Aq) ? \*(AqWIZZY! :\-)\*(Aq : \*(Aqnot wizzy :\-(\*(Aq %] .Ve .ie n .SS "split($pattern, $limit)" .el .SS "split($pattern, \f(CW$limit\fP)" .IX Subsection "split($pattern, $limit)" Splits the string based on the delimiter \f(CW$pattern\fR and optional \f(CW$limit\fR. Delegates to Perl's internal \f(CW\*(C`split()\*(C'\fR so the parameters are exactly the same. .PP .Vb 3 \& [% FOREACH item.split %] \& ... \& [% END %] \& \& [% FOREACH item.split(\*(Aqbaz|waz\*(Aq) %] \& ... \& [% END %] .Ve .SH "MUTATOR METHODS" .IX Header "MUTATOR METHODS" These methods modify the internal value of the string. For example: .PP .Vb 2 \& [% USE str=String(\*(Aqfoobar\*(Aq) %] \& [% str.append(\*(Aq.html\*(Aq) %] # str => \*(Aqfoobar.html\*(Aq .Ve .PP The value of \f(CW\*(C`str\*(C'\fR is now '\f(CW\*(C`foobar.html\*(C'\fR'. If you don't want to modify the string then simply take a copy first. .PP .Vb 1 \& [% str.copy.append(\*(Aq.html\*(Aq) %] .Ve .PP These methods all return a reference to the \f(CW\*(C`String\*(C'\fR object itself. This has two important benefits. The first is that when used as above, the \&\f(CW\*(C`String\*(C'\fR object '\f(CW\*(C`str\*(C'\fR' returned by the \f(CW\*(C`append()\*(C'\fR method will be stringified with a call to its \f(CW\*(C`text()\*(C'\fR method. This will return the newly modified string content. In other words, a directive like: .PP .Vb 1 \& [% str.append(\*(Aq.html\*(Aq) %] .Ve .PP will update the string and also print the new value. If you just want to update the string but not print the new value then use \f(CW\*(C`CALL\*(C'\fR. .PP .Vb 1 \& [% CALL str.append(\*(Aq.html\*(Aq) %] .Ve .PP The other benefit of these methods returning a reference to the \f(CW\*(C`String\*(C'\fR is that you can chain as many different method calls together as you like. For example: .PP .Vb 1 \& [% String.append(\*(Aq.html\*(Aq).trim.format(href) %] .Ve .PP Here are the methods: .SS "push($suffix, ...) / append($suffix, ...)" .IX Subsection "push($suffix, ...) / append($suffix, ...)" Appends all arguments to the end of the string. The \&\f(CW\*(C`append()\*(C'\fR method is provided as an alias for \f(CW\*(C`push()\*(C'\fR. .PP .Vb 2 \& [% msg.push(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq) %] \& [% msg.append(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq) %] .Ve .SS "pop($suffix)" .IX Subsection "pop($suffix)" Removes the suffix passed as an argument from the end of the String. .PP .Vb 2 \& [% USE String \*(Aqfoo bar\*(Aq %] \& [% String.pop(\*(Aq bar\*(Aq) %] # => \*(Aqfoo\*(Aq .Ve .SS "unshift($prefix, ...) / prepend($prefix, ...)" .IX Subsection "unshift($prefix, ...) / prepend($prefix, ...)" Prepends all arguments to the beginning of the string. The \&\f(CW\*(C`prepend()\*(C'\fR method is provided as an alias for \f(CW\*(C`unshift()\*(C'\fR. .PP .Vb 2 \& [% msg.unshift(\*(Aqfoo \*(Aq, \*(Aqbar \*(Aq) %] \& [% msg.prepend(\*(Aqfoo \*(Aq, \*(Aqbar \*(Aq) %] .Ve .SS "shift($prefix)" .IX Subsection "shift($prefix)" Removes the prefix passed as an argument from the start of the String. .PP .Vb 2 \& [% USE String \*(Aqfoo bar\*(Aq %] \& [% String.shift(\*(Aqfoo \*(Aq) %] # => \*(Aqbar\*(Aq .Ve .SS "left($pad)" .IX Subsection "left($pad)" If the length of the string is less than \f(CW$pad\fR then the string is left formatted and padded with spaces to \f(CW$pad\fR length. .PP .Vb 1 \& [% msg.left(20) %] .Ve .SS "right($pad)" .IX Subsection "right($pad)" As per \fBleft()\fR but right padding the \f(CW\*(C`String\*(C'\fR to a length of \f(CW$pad\fR. .PP .Vb 1 \& [% msg.right(20) %] .Ve .SS "center($pad) / centre($pad)" .IX Subsection "center($pad) / centre($pad)" As per \fBleft()\fR and \fBright()\fR but formatting the \f(CW\*(C`String\*(C'\fR to be centered within a space padded string of length \f(CW$pad\fR. The \f(CW\*(C`centre()\*(C'\fR method is provided as an alias for \f(CW\*(C`center()\*(C'\fR. .PP .Vb 2 \& [% msg.center(20) %] # American spelling \& [% msg.centre(20) %] # European spelling .Ve .SS "format($format)" .IX Subsection "format($format)" Apply a format in the style of \f(CW\*(C`sprintf()\*(C'\fR to the string. .PP .Vb 2 \& [% USE String("world") %] \& [% String.format("Hello %s\en") %] # => "Hello World\en" .Ve .SS "\fBupper()\fP" .IX Subsection "upper()" Converts the string to upper case. .PP .Vb 2 \& [% USE String("foo") %] \& [% String.upper %] # => \*(AqFOO\*(Aq .Ve .SS "\fBlower()\fP" .IX Subsection "lower()" Converts the string to lower case .PP .Vb 2 \& [% USE String("FOO") %] \& [% String.lower %] # => \*(Aqfoo\*(Aq .Ve .SS "\fBcapital()\fP" .IX Subsection "capital()" Converts the first character of the string to upper case. .PP .Vb 2 \& [% USE String("foo") %] \& [% String.capital %] # => \*(AqFoo\*(Aq .Ve .PP The remainder of the string is left untouched. To force the string to be all lower case with only the first letter capitalised, you can do something like this: .PP .Vb 2 \& [% USE String("FOO") %] \& [% String.lower.capital %] # => \*(AqFoo\*(Aq .Ve .SS "\fBchop()\fP" .IX Subsection "chop()" Removes the last character from the string. .PP .Vb 2 \& [% USE String("foop") %] \& [% String.chop %] # => \*(Aqfoo\*(Aq .Ve .SS "\fBchomp()\fP" .IX Subsection "chomp()" Removes the trailing newline from the string. .PP .Vb 2 \& [% USE String("foo\en") %] \& [% String.chomp %] # => \*(Aqfoo\*(Aq .Ve .SS "\fBtrim()\fP" .IX Subsection "trim()" Removes all leading and trailing whitespace from the string .PP .Vb 2 \& [% USE String(" foo \en\en ") %] \& [% String.trim %] # => \*(Aqfoo\*(Aq .Ve .SS "\fBcollapse()\fP" .IX Subsection "collapse()" Removes all leading and trailing whitespace and collapses any sequences of multiple whitespace to a single space. .PP .Vb 2 \& [% USE String(" \en\er \et foo \en \en bar \en") %] \& [% String.collapse %] # => "foo bar" .Ve .ie n .SS "truncate($length, $suffix)" .el .SS "truncate($length, \f(CW$suffix\fP)" .IX Subsection "truncate($length, $suffix)" Truncates the string to \f(CW$length\fR characters. .PP .Vb 2 \& [% USE String(\*(Aqlong string\*(Aq) %] \& [% String.truncate(4) %] # => \*(Aqlong\*(Aq .Ve .PP If \f(CW$suffix\fR is specified then it will be appended to the truncated string. In this case, the string will be further shortened by the length of the suffix to ensure that the newly constructed string complete with suffix is exactly \f(CW$length\fR characters long. .PP .Vb 2 \& [% USE msg = String(\*(AqHello World\*(Aq) %] \& [% msg.truncate(8, \*(Aq...\*(Aq) %] # => \*(AqHello...\*(Aq .Ve .ie n .SS "replace($search, $replace)" .el .SS "replace($search, \f(CW$replace\fP)" .IX Subsection "replace($search, $replace)" Replaces all occurrences of \f(CW$search\fR in the string with \f(CW$replace\fR. .PP .Vb 2 \& [% USE String(\*(Aqfoo bar foo baz\*(Aq) %] \& [% String.replace(\*(Aqfoo\*(Aq, \*(Aqwiz\*(Aq) %] # => \*(Aqwiz bar wiz baz\*(Aq .Ve .SS "remove($search)" .IX Subsection "remove($search)" Remove all occurrences of \f(CW$search\fR in the string. .PP .Vb 2 \& [% USE String(\*(Aqfoo bar foo baz\*(Aq) %] \& [% String.remove(\*(Aqfoo \*(Aq) %] # => \*(Aqbar baz\*(Aq .Ve .SS "repeat($count)" .IX Subsection "repeat($count)" Repeats the string \f(CW$count\fR times. .PP .Vb 2 \& [% USE String(\*(Aqfoo \*(Aq) %] \& [% String.repeat(3) %] # => \*(Aqfoo foo foo \*(Aq .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[��'�* �* ! man3/Template::Plugin::Filter.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Filter 3" .TH Template::Plugin::Filter 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Filter \- Base class for plugin filters .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& package MyOrg::Template::Plugin::MyFilter; \& \& use Template::Plugin::Filter; \& use base qw( Template::Plugin::Filter ); \& \& sub filter { \& my ($self, $text) = @_; \& \& # ...mungify $text... \& \& return $text; \& } \& \& # now load it... \& [% USE MyFilter %] \& \& # ...and use the returned object as a filter \& [% FILTER $MyFilter %] \& ... \& [% END %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a base class for plugin filters. It hides the underlying complexity involved in creating and using filters that get defined and made available by loading a plugin. .PP To use the module, simply create your own plugin module that is inherited from the \f(CW\*(C`Template::Plugin::Filter\*(C'\fR class. .PP .Vb 1 \& package MyOrg::Template::Plugin::MyFilter; \& \& use Template::Plugin::Filter; \& use base qw( Template::Plugin::Filter ); .Ve .PP Then simply define your \f(CW\*(C`filter()\*(C'\fR method. When called, you get passed a reference to your plugin object (\f(CW$self\fR) and the text to be filtered. .PP .Vb 2 \& sub filter { \& my ($self, $text) = @_; \& \& # ...mungify $text... \& \& return $text; \& } .Ve .PP To use your custom plugin, you have to make sure that the Template Toolkit knows about your plugin namespace. .PP .Vb 3 \& my $tt2 = Template\->new({ \& PLUGIN_BASE => \*(AqMyOrg::Template::Plugin\*(Aq, \& }); .Ve .PP Or for individual plugins you can do it like this: .PP .Vb 5 \& my $tt2 = Template\->new({ \& PLUGINS => { \& MyFilter => \*(AqMyOrg::Template::Plugin::MyFilter\*(Aq, \& }, \& }); .Ve .PP Then you \f(CW\*(C`USE\*(C'\fR your plugin in the normal way. .PP .Vb 1 \& [% USE MyFilter %] .Ve .PP The object returned is stored in the variable of the same name, \&'\f(CW\*(C`MyFilter\*(C'\fR'. When you come to use it as a \f(CW\*(C`FILTER\*(C'\fR, you should add a dollar prefix. This indicates that you want to use the filter stored in the variable '\f(CW\*(C`MyFilter\*(C'\fR' rather than the filter named \&'\f(CW\*(C`MyFilter\*(C'\fR', which is an entirely different thing (see later for information on defining filters by name). .PP .Vb 3 \& [% FILTER $MyFilter %] \& ...text to be filtered... \& [% END %] .Ve .PP You can, of course, assign it to a different variable. .PP .Vb 1 \& [% USE blat = MyFilter %] \& \& [% FILTER $blat %] \& ...text to be filtered... \& [% END %] .Ve .PP Any configuration parameters passed to the plugin constructor from the \&\f(CW\*(C`USE\*(C'\fR directive are stored internally in the object for inspection by the \f(CW\*(C`filter()\*(C'\fR method (or indeed any other method). Positional arguments are stored as a reference to a list in the \f(CW\*(C`_ARGS\*(C'\fR item while named configuration parameters are stored as a reference to a hash array in the \f(CW\*(C`_CONFIG\*(C'\fR item. .PP For example, loading a plugin as shown here: .PP .Vb 1 \& [% USE blat = MyFilter \*(Aqfoo\*(Aq \*(Aqbar\*(Aq baz = \*(Aqblam\*(Aq %] .Ve .PP would allow the \f(CW\*(C`filter()\*(C'\fR method to do something like this: .PP .Vb 2 \& sub filter { \& my ($self, $text) = @_; \& \& my $args = $self\->{ _ARGS }; # [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] \& my $conf = $self\->{ _CONFIG }; # { baz => \*(Aqblam\*(Aq } \& \& # ...munge $text... \& \& return $text; \& } .Ve .PP By default, plugins derived from this module will create static filters. A static filter is created once when the plugin gets loaded via the \f(CW\*(C`USE\*(C'\fR directive and re-used for all subsequent \&\f(CW\*(C`FILTER\*(C'\fR operations. That means that any argument specified with the \f(CW\*(C`FILTER\*(C'\fR directive are ignored. .PP Dynamic filters, on the other hand, are re-created each time they are used by a \f(CW\*(C`FILTER\*(C'\fR directive. This allows them to act on any parameters passed from the \f(CW\*(C`FILTER\*(C'\fR directive and modify their behaviour accordingly. .PP There are two ways to create a dynamic filter. The first is to define a \f(CW$DYNAMIC\fR class variable set to a true value. .PP .Vb 3 \& package MyOrg::Template::Plugin::MyFilter; \& use base \*(AqTemplate::Plugin::Filter\*(Aq; \& our $DYNAMIC = 1; .Ve .PP The other way is to set the internal \f(CW\*(C`_DYNAMIC\*(C'\fR value within the \f(CW\*(C`init()\*(C'\fR method which gets called by the \f(CW\*(C`new()\*(C'\fR constructor. .PP .Vb 5 \& sub init { \& my $self = shift; \& $self\->{ _DYNAMIC } = 1; \& return $self; \& } .Ve .PP When this is set to a true value, the plugin will automatically create a dynamic filter. The outcome is that the \f(CW\*(C`filter()\*(C'\fR method will now also get passed a reference to an array of positional arguments and a reference to a hash array of named parameters. .PP So, using a plugin filter like this: .PP .Vb 1 \& [% FILTER $blat \*(Aqfoo\*(Aq \*(Aqbar\*(Aq baz = \*(Aqblam\*(Aq %] .Ve .PP would allow the \f(CW\*(C`filter()\*(C'\fR method to work like this: .PP .Vb 2 \& sub filter { \& my ($self, $text, $args, $conf) = @_; \& \& # $args = [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] \& # $conf = { baz => \*(Aqblam\*(Aq } \& } .Ve .PP In this case can pass parameters to both the \s-1USE\s0 and \s-1FILTER\s0 directives, so your \fBfilter()\fR method should probably take that into account. .PP .Vb 1 \& [% USE MyFilter \*(Aqfoo\*(Aq wiz => \*(Aqwaz\*(Aq %] \& \& [% FILTER $MyFilter \*(Aqbar\*(Aq biz => \*(Aqbaz\*(Aq %] \& ... \& [% END %] .Ve .PP You can use the \f(CW\*(C`merge_args()\*(C'\fR and \f(CW\*(C`merge_config()\*(C'\fR methods to do a quick and easy job of merging the local (e.g. \f(CW\*(C`FILTER\*(C'\fR) parameters with the internal (e.g. \f(CW\*(C`USE\*(C'\fR) values and returning new sets of conglomerated data. .PP .Vb 2 \& sub filter { \& my ($self, $text, $args, $conf) = @_; \& \& $args = $self\->merge_args($args); \& $conf = $self\->merge_config($conf); \& \& # $args = [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] \& # $conf = { wiz => \*(Aqwaz\*(Aq, biz => \*(Aqbaz\*(Aq } \& ... \& } .Ve .PP You can also have your plugin install itself as a named filter by calling the \f(CW\*(C`install_filter()\*(C'\fR method from the \f(CW\*(C`init()\*(C'\fR method. You should provide a name for the filter, something that you might like to make a configuration option. .PP .Vb 6 \& sub init { \& my $self = shift; \& my $name = $self\->{ _CONFIG }\->{ name } || \*(Aqmyfilter\*(Aq; \& $self\->install_filter($name); \& return $self; \& } .Ve .PP This allows the plugin filter to be used as follows: .PP .Vb 1 \& [% USE MyFilter %] \& \& [% FILTER myfilter %] \& ... \& [% END %] .Ve .PP or .PP .Vb 1 \& [% USE MyFilter name = \*(Aqswipe\*(Aq %] \& \& [% FILTER swipe %] \& ... \& [% END %] .Ve .PP Alternately, you can allow a filter name to be specified as the first positional argument. .PP .Vb 6 \& sub init { \& my $self = shift; \& my $name = $self\->{ _ARGS }\->[0] || \*(Aqmyfilter\*(Aq; \& $self\->install_filter($name); \& return $self; \& } \& \& [% USE MyFilter \*(Aqswipe\*(Aq %] \& \& [% FILTER swipe %] \& ... \& [% END %] .Ve .SH "EXAMPLE" .IX Header "EXAMPLE" Here's a complete example of a plugin filter module. .PP .Vb 3 \& package My::Template::Plugin::Change; \& use Template::Plugin::Filter; \& use base qw( Template::Plugin::Filter ); \& \& sub init { \& my $self = shift; \& \& $self\->{ _DYNAMIC } = 1; \& \& # first arg can specify filter name \& $self\->install_filter($self\->{ _ARGS }\->[0] || \*(Aqchange\*(Aq); \& \& return $self; \& } \& \& sub filter { \& my ($self, $text, $args, $config) = @_; \& \& $config = $self\->merge_config($config); \& my $regex = join(\*(Aq|\*(Aq, keys %$config); \& \& $text =~ s/($regex)/$config\->{ $1 }/ge; \& \& return $text; \& } \& \& 1; .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Template::Filters, Template::Manual::Filters PK � �[�% � � man3/Template::Config.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Config 3" .TH Template::Config 3 "2024-10-22" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Config \- Factory module for instantiating other TT2 modules .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Config; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements various methods for loading and instantiating other modules that comprise the Template Toolkit. It provides a consistent way to create toolkit components and allows custom modules to be used in place of the regular ones. .PP Package variables such as \f(CW$STASH\fR, \f(CW$SERVICE\fR, \f(CW$CONTEXT\fR, etc., contain the default module/package name for each component (Template::Stash, Template::Service and Template::Context, respectively) and are used by the various factory methods (\fBstash()\fR, \fBservice()\fR and \fBcontext()\fR) to load the appropriate module. Changing these package variables will cause subsequent calls to the relevant factory method to load and instantiate an object from the new class. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .SS "load($module)" .IX Subsection "load($module)" Load a module using Perl's \fBrequire()\fR. Any occurrences of '\f(CW\*(C`::\*(C'\fR' in the module name are be converted to '\f(CW\*(C`/\*(C'\fR', and '\f(CW\*(C`.pm\*(C'\fR' is appended. Returns 1 on success or undef on error. Use \f(CW\*(C`$class\->error()\*(C'\fR to examine the error string. .SS "\fBpreload()\fP" .IX Subsection "preload()" This method preloads all the other \f(CW\*(C`Template::*\*(C'\fR modules that are likely to be used. It is called automatically by the Template module when running under mod_perl (\f(CW$ENV{MOD_PERL}\fR is set). .SS "parser(\e%config)" .IX Subsection "parser(%config)" Instantiate a new parser object of the class whose name is denoted by the package variable \f(CW$PARSER\fR (default: Template::Parser). Returns a reference to a newly instantiated parser object or undef on error. .SS "provider(\e%config)" .IX Subsection "provider(%config)" Instantiate a new template provider object (default: Template::Provider). Returns an object reference or undef on error, as above. .SS "plugins(\e%config)" .IX Subsection "plugins(%config)" Instantiate a new plugins provider object (default: Template::Plugins). Returns an object reference or undef on error, as above. .SS "filters(\e%config)" .IX Subsection "filters(%config)" Instantiate a new filter provider object (default: Template::Filters). Returns an object reference or undef on error, as above. .SS "stash(\e%vars)" .IX Subsection "stash(%vars)" Instantiate a new stash object (Template::Stash or Template::Stash::XS depending on the default set at installation time) using the contents of the optional hash array passed by parameter as initial variable definitions. Returns an object reference or undef on error, as above. .SS "context(\e%config)" .IX Subsection "context(%config)" Instantiate a new template context object (default: Template::Context). Returns an object reference or undef on error, as above. .SS "service(\e%config)" .IX Subsection "service(%config)" Instantiate a new template service object (default: Template::Service). Returns an object reference or undef on error, as above. .SS "iterator(\e%config)" .IX Subsection "iterator(%config)" Instantiate a new template iterator object (default: Template::Iterator). Returns an object reference or undef on error, as above. .SS "constants(\e%config)" .IX Subsection "constants(%config)" Instantiate a new namespace handler for compile time constant folding (default: Template::Namespace::Constants). Returns an object reference or undef on error, as above. .SS "instdir($dir)" .IX Subsection "instdir($dir)" Returns the root directory of the Template Toolkit installation under which optional components are installed. Any relative directory specified as an argument will be appended to the returned directory. .PP .Vb 3 \& # e.g. returns \*(Aq/usr/local/tt2\*(Aq \& my $ttroot = Template::Config\->instdir() \& || die "$Template::Config::ERROR\en"; \& \& # e.g. returns \*(Aq/usr/local/tt2/templates\*(Aq \& my $template = Template::Config\->instdir(\*(Aqtemplates\*(Aq) \& || die "$Template::Config::ERROR\en"; .Ve .PP Returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$Template::Config::ERROR\fR appropriately if the optional components of the Template Toolkit have not been installed. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template PK � �[����� � % man3/Template::Plugin::Procedural.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Procedural 3" .TH Template::Plugin::Procedural 3 "2022-04-26" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Procedural \- Base class for procedural plugins .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& package Template::Plugin::LWPSimple; \& use base qw(Template::Plugin::Procedural); \& use LWP::Simple; # exports \*(Aqget\*(Aq \& 1; \& \& [% USE LWPSimple %] \& [% LWPSimple.get("http://www.tt2.org/") %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`Template::Plugin::Procedural\*(C'\fR is a base class for Template Toolkit plugins that causes defined subroutines to be called directly rather than as a method. Essentially this means that subroutines will not receive the class name or object as its first argument. .PP This is most useful when creating plugins for modules that normally work by exporting subroutines that do not expect such additional arguments. .PP Despite the fact that subroutines will not be called in an \s-1OO\s0 manner, inheritance still function as normal. A class that uses \&\f(CW\*(C`Template::Plugin::Procedural\*(C'\fR can be subclassed and both subroutines defined in the subclass and subroutines defined in the original class will be available to the Template Toolkit and will be called without the class/object argument. .SH "AUTHOR" .IX Header "AUTHOR" Mark Fowler <mark@twoshortplanks.com> <http://www.twoshortplanks.com> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2002 Mark Fowler <mark@twoshortplanks.com> .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Plugin PK � �[r�m� � ! man3/Template::Stash::Context.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Stash::Context 3" .TH Template::Stash::Context 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Stash::Context \- Experimetal stash allowing list/scalar context definition .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Template; \& use Template::Stash::Context; \& \& my $stash = Template::Stash::Context\->new(\e%vars); \& my $tt2 = Template\->new({ STASH => $stash }); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is an alternate stash object which includes a patch from Craig Barratt to implement various new virtual methods to allow dotted template variable to denote if object methods and subroutines should be called in scalar or list context. It adds a little overhead to each stash call and I'm a little wary of applying that to the core default stash without investigating the effects first. So for now, it's implemented as a separate stash module which will allow us to test it out, benchmark it and switch it in or out as we require. .PP This is what Craig has to say about it: .PP Here's a better set of features for the core. Attached is a new version of Stash.pm (based on \s-1TT2.02\s0) that: .PP * supports the special op \*(L"scalar\*(R" that forces scalar context on function calls, eg: .PP .Vb 1 \& cgi.param("foo").scalar .Ve .PP calls cgi.param(\*(L"foo\*(R") in scalar context (unlike my wimpy scalar op from last night). Array context is the default. .PP With non-function operands, scalar behaves like the perl version (eg: no-op for scalar, size for arrays, etc). .PP * supports the special op \*(L"ref\*(R" that behaves like the perl ref. If applied to a function the function is not called. Eg: .PP .Vb 1 \& cgi.param("foo").ref .Ve .PP does *not* call cgi.param and evaluates to \*(L"\s-1CODE\*(R".\s0 Similarly, \&\s-1HASH\s0.ref, \s-1ARRAY\s0.ref return what you expect. .PP * adds a new scalar and list op called \*(L"array\*(R" that is a no-op for arrays and promotes scalars to one-element arrays. .PP * allows scalar ops to be applied to arrays and hashes in place, eg: \s-1\fBARRAY\s0.repeat\fR\|(3) repeats each element in place. .PP * allows list ops to be applied to scalars by promoting the scalars to one-element arrays (like an implicit \*(L"array\*(R"). So you can do things like \s-1SCALAR\s0.size, \s-1SCALAR\s0.join and get a useful result. .PP This also means you can now use x.0 to safely get the first element whether x is an array or scalar. .PP The new Stash.pm passes the \s-1TT2.02\s0 test suite. But I haven't tested the new features very much. One nagging implementation problem is that the \&\*(L"scalar\*(R" and \*(L"ref\*(R" ops have higher precedence than user variable names. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> .PP <http://wardley.org/> .SH "VERSION" .IX Header "VERSION" 1.63, distributed as part of the Template Toolkit version 3.100, released on 30 March 2020. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Stash PK � �[��Vlj` �` man3/Template::Context.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Context 3" .TH Template::Context 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Context \- Runtime context in which templates are processed .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Context; \& \& # constructor \& $context = Template::Context\->new(\e%config) \& || die $Template::Context::ERROR; \& \& # fetch (load and compile) a template \& $template = $context\->template($template_name); \& \& # fetch (load and instantiate) a plugin object \& $plugin = $context\->plugin($name, \e@args); \& \& # fetch (return or create) a filter subroutine \& $filter = $context\->filter($name, \e@args, $alias); \& \& # process/include a template, errors are thrown via die() \& $output = $context\->process($template, \e%vars); \& $output = $context\->include($template, \e%vars); \& \& # raise an exception via die() \& $context\->throw($error_type, $error_message, \e$output_buffer); \& \& # catch an exception, clean it up and fix output buffer \& $exception = $context\->catch($exception, \e$output_buffer); \& \& # save/restore the stash to effect variable localisation \& $new_stash = $context\->localise(\e%vars); \& $old_stash = $context\->delocalise(); \& \& # add new BLOCK or FILTER definitions \& $context\->define_block($name, $block); \& $context\->define_filter($name, \e&filtersub, $is_dynamic); \& \& # reset context, clearing any imported BLOCK definitions \& $context\->reset(); \& \& # methods for accessing internal items \& $stash = $context\->stash(); \& $tflag = $context\->trim(); \& $epflag = $context\->eval_perl(); \& $providers = $context\->templates(); \& $providers = $context\->plugins(); \& $providers = $context\->filters(); \& ... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Context\*(C'\fR module defines an object class for representing a runtime context in which templates are processed. It provides an interface to the fundamental operations of the Template Toolkit processing engine through which compiled templates (i.e. Perl code constructed from the template source) can process templates, load plugins and filters, raise exceptions and so on. .PP A default \f(CW\*(C`Template::Context\*(C'\fR object is created by the Template module. Any \f(CW\*(C`Template::Context\*(C'\fR options may be passed to the Template \&\fBnew()\fR constructor method and will be forwarded to the \&\f(CW\*(C`Template::Context\*(C'\fR constructor. .PP .Vb 1 \& use Template; \& \& my $template = Template\->new({ \& TRIM => 1, \& EVAL_PERL => 1, \& BLOCKS => { \& header => \*(AqThis is the header\*(Aq, \& footer => \*(AqThis is the footer\*(Aq, \& }, \& }); .Ve .PP Similarly, the \f(CW\*(C`Template::Context\*(C'\fR constructor will forward all configuration parameters onto other default objects (e.g. Template::Provider, Template::Plugins, Template::Filters, etc.) that it may need to instantiate. .PP .Vb 4 \& $context = Template::Context\->new({ \& INCLUDE_PATH => \*(Aq/home/abw/templates\*(Aq, # provider option \& TAG_STYLE => \*(Aqhtml\*(Aq, # parser option \& }); .Ve .PP A \f(CW\*(C`Template::Context\*(C'\fR object (or subclass) can be explicitly instantiated and passed to the Template \fBnew()\fR constructor method as the \&\f(CW\*(C`CONTEXT\*(C'\fR configuration item. .PP .Vb 2 \& use Template; \& use Template::Context; \& \& my $context = Template::Context\->new({ TRIM => 1 }); \& my $template = Template\->new({ CONTEXT => $context }); .Ve .PP The Template module uses the Template::Config \&\fBcontext()\fR factory method to create a default context object when required. The \f(CW$Template::Config::CONTEXT\fR package variable may be set to specify an alternate context module. This will be loaded automatically and its \fBnew()\fR constructor method called by the \&\fBcontext()\fR factory method when a default context object is required. .PP .Vb 1 \& use Template; \& \& $Template::Config::CONTEXT = \*(AqMyOrg::Template::Context\*(Aq; \& \& my $template = Template\->new({ \& EVAL_PERL => 1, \& EXTRA_MAGIC => \*(Aqred hot\*(Aq, # your extra config items \& ... \& }); .Ve .SH "METHODS" .IX Header "METHODS" .SS "new(\e%params)" .IX Subsection "new(%params)" The \f(CW\*(C`new()\*(C'\fR constructor method is called to instantiate a \&\f(CW\*(C`Template::Context\*(C'\fR object. Configuration parameters may be specified as a \&\s-1HASH\s0 reference or as a list of \f(CW\*(C`name => value\*(C'\fR pairs. .PP .Vb 4 \& my $context = Template::Context\->new({ \& INCLUDE_PATH => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }); \& \& my $context = Template::Context\->new( EVAL_PERL => 1 ); .Ve .PP The \f(CW\*(C`new()\*(C'\fR method returns a \f(CW\*(C`Template::Context\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR on error. In the latter case, a relevant error message can be retrieved by the \&\fBerror()\fR class method or directly from the \&\f(CW$Template::Context::ERROR\fR package variable. .PP .Vb 2 \& my $context = Template::Context\->new(\e%config) \& || die Template::Context\->error(); \& \& my $context = Template::Context\->new(\e%config) \& || die $Template::Context::ERROR; .Ve .PP The following configuration items may be specified. Please see Template::Manual::Config for further details. .PP \fI\s-1VARIABLES\s0\fR .IX Subsection "VARIABLES" .PP The \s-1VARIABLES\s0 option can be used to specify a hash array of template variables. .PP .Vb 7 \& my $context = Template::Context\->new({ \& VARIABLES => { \& title => \*(AqA Demo Page\*(Aq, \& author => \*(AqJoe Random Hacker\*(Aq, \& version => 3.14, \& }, \& }; .Ve .PP \fI\s-1BLOCKS\s0\fR .IX Subsection "BLOCKS" .PP The \s-1BLOCKS\s0 option can be used to pre-define a default set of template blocks. .PP .Vb 7 \& my $context = Template::Context\->new({ \& BLOCKS => { \& header => \*(AqThe Header. [% title %]\*(Aq, \& footer => sub { return $some_output_text }, \& another => Template::Document\->new({ ... }), \& }, \& }); .Ve .PP \fI\s-1VIEWS\s0\fR .IX Subsection "VIEWS" .PP The \s-1VIEWS\s0 option can be used to pre-define one or more Template::View objects. .PP .Vb 7 \& my $context = Template::Context\->new({ \& VIEWS => [ \& bottom => { prefix => \*(Aqbottom/\*(Aq }, \& middle => { prefix => \*(Aqmiddle/\*(Aq, base => \*(Aqbottom\*(Aq }, \& top => { prefix => \*(Aqtop/\*(Aq, base => \*(Aqmiddle\*(Aq }, \& ], \& }); .Ve .PP \fI\s-1TRIM\s0\fR .IX Subsection "TRIM" .PP The \s-1TRIM\s0 option can be set to have any leading and trailing whitespace automatically removed from the output of all template files and \f(CW\*(C`BLOCK\*(C'\fRs. .PP example: .PP .Vb 1 \& [% BLOCK foo %] \& \& Line 1 of foo \& \& [% END %] \& \& before \& [% INCLUDE foo %] \& after .Ve .PP output: .PP .Vb 3 \& before \& Line 1 of foo \& after .Ve .PP \fI\s-1EVAL_PERL\s0\fR .IX Subsection "EVAL_PERL" .PP The \s-1EVAL_PERL\s0 is used to indicate if \&\f(CW\*(C`PERL\*(C'\fR and/or \f(CW\*(C`RAWPERL\*(C'\fR blocks should be evaluated. It is disabled by default. .PP \fI\s-1RECURSION\s0\fR .IX Subsection "RECURSION" .PP The \s-1RECURSION\s0 can be set to allow templates to recursively process themselves, either directly (e.g. template \f(CW\*(C`foo\*(C'\fR calls \f(CW\*(C`INCLUDE foo\*(C'\fR) or indirectly (e.g. \&\f(CW\*(C`foo\*(C'\fR calls \f(CW\*(C`INCLUDE bar\*(C'\fR which calls \f(CW\*(C`INCLUDE foo\*(C'\fR). .PP \fI\s-1LOAD_TEMPLATES\s0\fR .IX Subsection "LOAD_TEMPLATES" .PP The \s-1LOAD_TEMPLATES\s0 option can be used to provide a reference to a list of Template::Provider objects or sub-classes thereof which will take responsibility for loading and compiling templates. .PP .Vb 6 \& my $context = Template::Context\->new({ \& LOAD_TEMPLATES => [ \& MyOrg::Template::Provider\->new({ ... }), \& Template::Provider\->new({ ... }), \& ], \& }); .Ve .PP \fI\s-1LOAD_PLUGINS\s0\fR .IX Subsection "LOAD_PLUGINS" .PP The \s-1LOAD_PLUGINS\s0 options can be used to specify a list of provider objects responsible for loading and instantiating template plugin objects. .PP .Vb 6 \& my $context = Template::Context\->new({ \& LOAD_PLUGINS => [ \& MyOrg::Template::Plugins\->new({ ... }), \& Template::Plugins\->new({ ... }), \& ], \& }); .Ve .PP \fI\s-1LOAD_FILTERS\s0\fR .IX Subsection "LOAD_FILTERS" .PP The \s-1LOAD_FILTERS\s0 option can be used to specify a list of provider objects for returning and/or creating filter subroutines. .PP .Vb 6 \& my $context = Template::Context\->new({ \& LOAD_FILTERS => [ \& MyTemplate::Filters\->new(), \& Template::Filters\->new(), \& ], \& }); .Ve .PP \fI\s-1STASH\s0\fR .IX Subsection "STASH" .PP The \s-1STASH\s0 option can be used to specify a Template::Stash object or sub-class which will take responsibility for managing template variables. .PP .Vb 4 \& my $stash = MyOrg::Template::Stash\->new({ ... }); \& my $context = Template::Context\->new({ \& STASH => $stash, \& }); .Ve .PP \fI\s-1DEBUG\s0\fR .IX Subsection "DEBUG" .PP The \s-1DEBUG\s0 option can be used to enable various debugging features of the Template::Context module. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_CONTEXT | DEBUG_DIRS, \& }); .Ve .SS "template($name)" .IX Subsection "template($name)" Returns a compiled template by querying each of the \s-1LOAD_TEMPLATES\s0 providers (instances of Template::Provider, or sub-class) in turn. .PP .Vb 1 \& $template = $context\->template(\*(Aqheader\*(Aq); .Ve .PP On error, a Template::Exception object of type '\f(CW\*(C`file\*(C'\fR' is thrown via \&\f(CW\*(C`die()\*(C'\fR. This can be caught by enclosing the call to \f(CW\*(C`template()\*(C'\fR in an \&\f(CW\*(C`eval\*(C'\fR block and examining \f(CW$@\fR. .PP .Vb 4 \& eval { $template = $context\->template(\*(Aqheader\*(Aq) }; \& if ($@) { \& print "failed to fetch template: $@\en"; \& } .Ve .SS "plugin($name, \e@args)" .IX Subsection "plugin($name, @args)" Instantiates a plugin object by querying each of the \s-1LOAD_PLUGINS\s0 providers. The default \s-1LOAD_PLUGINS\s0 provider is a Template::Plugins object which attempts to load plugin modules, according the various configuration items such as \s-1PLUGIN_BASE\s0, \&\s-1LOAD_PERL\s0, etc., and then instantiate an object via \fBnew()\fR. A reference to a list of constructor arguments may be passed as the second parameter. These are forwarded to the plugin constructor. .PP Returns a reference to a plugin (which is generally an object, but doesn't have to be). Errors are thrown as Template::Exception objects with the type set to '\f(CW\*(C`plugin\*(C'\fR'. .PP .Vb 1 \& $plugin = $context\->plugin(\*(AqDBI\*(Aq, \*(Aqdbi:msql:mydbname\*(Aq); .Ve .ie n .SS "filter($name, \e@args, $alias)" .el .SS "filter($name, \e@args, \f(CW$alias\fP)" .IX Subsection "filter($name, @args, $alias)" Instantiates a filter subroutine by querying the \s-1LOAD_FILTERS\s0 providers. The default \s-1LOAD_FILTERS\s0 provider is a Template::Filters object. .PP Additional arguments may be passed by list reference along with an optional alias under which the filter will be cached for subsequent use. The filter is cached under its own \f(CW$name\fR if \f(CW$alias\fR is undefined. Subsequent calls to \&\f(CW\*(C`filter($name)\*(C'\fR will return the cached entry, if defined. Specifying arguments bypasses the caching mechanism and always creates a new filter. Errors are thrown as Template::Exception objects with the type set to '\f(CW\*(C`filter\*(C'\fR'. .PP .Vb 2 \& # static filter (no args) \& $filter = $context\->filter(\*(Aqhtml\*(Aq); \& \& # dynamic filter (args) aliased to \*(Aqpadright\*(Aq \& $filter = $context\->filter(\*(Aqformat\*(Aq, \*(Aq%60s\*(Aq, \*(Aqpadright\*(Aq); \& \& # retrieve previous filter via \*(Aqpadright\*(Aq alias \& $filter = $context\->filter(\*(Aqpadright\*(Aq); .Ve .SS "process($template, \e%vars)" .IX Subsection "process($template, %vars)" Processes a template named or referenced by the first parameter and returns the output generated. An optional reference to a hash array may be passed as the second parameter, containing variable definitions which will be set before the template is processed. The template is processed in the current context, with no localisation of variables performed. Errors are thrown as Template::Exception objects via \f(CW\*(C`die()\*(C'\fR. .PP .Vb 1 \& $output = $context\->process(\*(Aqheader\*(Aq, { title => \*(AqHello World\*(Aq }); .Ve .SS "include($template, \e%vars)" .IX Subsection "include($template, %vars)" Similar to \fBprocess()\fR, but using localised variables. Changes made to any variables will only persist until the \f(CW\*(C`include()\*(C'\fR method completes. .PP .Vb 1 \& $output = $context\->include(\*(Aqheader\*(Aq, { title => \*(AqHello World\*(Aq }); .Ve .SS "insert($template)" .IX Subsection "insert($template)" This method returns the source content of a template file without performing any evaluation. It is used to implement the \f(CW\*(C`INSERT\*(C'\fR directive. .ie n .SS "throw($error_type, $error_message, \e$output)" .el .SS "throw($error_type, \f(CW$error_message\fP, \e$output)" .IX Subsection "throw($error_type, $error_message, $output)" Raises an exception in the form of a Template::Exception object by calling \&\f(CW\*(C`die()\*(C'\fR. This method may be passed a reference to an existing Template::Exception object; a single value containing an error message which is used to instantiate a Template::Exception of type '\f(CW\*(C`undef\*(C'\fR'; or a pair of values representing the exception \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR from which a Template::Exception object is instantiated. e.g. .PP .Vb 3 \& $context\->throw($exception); \& $context\->throw("I\*(Aqm sorry Dave, I can\*(Aqt do that"); \& $context\->throw(\*(Aqdenied\*(Aq, "I\*(Aqm sorry Dave, I can\*(Aqt do that"); .Ve .PP The optional third parameter may be a reference to the current output buffer. This is then stored in the exception object when created, allowing the catcher to examine and use the output up to the point at which the exception was raised. .PP .Vb 3 \& $output .= \*(Aqblah blah blah\*(Aq; \& $output .= \*(Aqmore rhubarb\*(Aq; \& $context\->throw(\*(Aqyack\*(Aq, \*(AqToo much yacking\*(Aq, \e$output); .Ve .SS "catch($exception, \e$output)" .IX Subsection "catch($exception, $output)" Catches an exception thrown, either as a reference to a Template::Exception object or some other value. In the latter case, the error string is promoted to a Template::Exception object of '\f(CW\*(C`undef\*(C'\fR' type. This method also accepts a reference to the current output buffer which is passed to the Template::Exception constructor, or is appended to the output buffer stored in an existing Template::Exception object, if unique (i.e. not the same reference). By this process, the correct state of the output buffer can be reconstructed for simple or nested throws. .ie n .SS "define_block($name, $block)" .el .SS "define_block($name, \f(CW$block\fP)" .IX Subsection "define_block($name, $block)" Adds a new block definition to the internal \s-1BLOCKS\s0 cache. The first argument should contain the name of the block and the second a reference to a Template::Document object or template sub-routine, or template text which is automatically compiled into a template sub-routine. .PP Returns a true value (the sub-routine or Template::Document reference) on success or undef on failure. The relevant error message can be retrieved by calling the \fBerror()\fR method. .ie n .SS "define_filter($name, \e&filter, $is_dynamic)" .el .SS "define_filter($name, \e&filter, \f(CW$is_dynamic\fP)" .IX Subsection "define_filter($name, &filter, $is_dynamic)" Adds a new filter definition by calling the \&\fBstore()\fR method on each of the \s-1LOAD_FILTERS\s0 providers until accepted (in the usual case, this is accepted straight away by the one and only Template::Filters provider). The first argument should contain the name of the filter and the second a reference to a filter subroutine. The optional third argument can be set to any true value to indicate that the subroutine is a dynamic filter factory. .PP Returns a true value or throws a '\f(CW\*(C`filter\*(C'\fR' exception on error. .ie n .SS "define_vmethod($type, $name, $code)" .el .SS "define_vmethod($type, \f(CW$name\fP, \f(CW$code\fP)" .IX Subsection "define_vmethod($type, $name, $code)" This method is a wrapper around the Template::Stash \&\fBdefine_vmethod()\fR method. It can be used to define new virtual methods. .PP .Vb 7 \& # define a new scalar (item) virtual method \& $context\->define_vmethod( \& item => ucfirst => sub { \& my $text = shift; \& return ucfirst $text; \& } \& ) .Ve .SS "define_view($name, \e%params)" .IX Subsection "define_view($name, %params)" This method allows you to define a named view. .PP .Vb 5 \& $context\->define_view( \& my_view => { \& prefix => \*(Aqmy_templates/\*(Aq \& } \& ); .Ve .PP The view is then accessible as a template variable. .PP .Vb 1 \& [% my_view.print(some_data) %] .Ve .SS "define_views($views)" .IX Subsection "define_views($views)" This method allows you to define multiple named views. A reference to a hash array or list reference should be passed as an argument. .PP .Vb 8 \& $context\->define_view({ # hash reference \& my_view_one => { \& prefix => \*(Aqmy_templates_one/\*(Aq \& }, \& my_view_two => { \& prefix => \*(Aqmy_templates_two/\*(Aq \& } \& }); .Ve .PP If you're defining multiple views of which one or more are based on other views in the same definition then you should pass them as a list reference. This ensures that they get created in the right order (Perl does not preserve the order of items defined in a hash reference so you can't guarantee that your base class view will be defined before your subclass view). .PP .Vb 9 \& $context\->define_view([ # list referenence \& my_view_one => { \& prefix => \*(Aqmy_templates_one/\*(Aq \& }, \& my_view_two => { \& prefix => \*(Aqmy_templates_two/\*(Aq , \& base => \*(Aqmy_view_one\*(Aq, \& } \& ]); .Ve .PP The views are then accessible as template variables. .PP .Vb 2 \& [% my_view_one.print(some_data) %] \& [% my_view_two.print(some_data) %] .Ve .PP See also the \s-1VIEWS\s0 option. .SS "\fBstash()\fP" .IX Subsection "stash()" This method returns the Template::Stash object used internally to manage template variables. .SS "localise(\e%vars)" .IX Subsection "localise(%vars)" Clones the stash to create a context with localised variables. Returns a reference to the newly cloned stash object which is also stored internally. .PP .Vb 1 \& $stash = $context\->localise(); .Ve .SS "\fBdelocalise()\fP" .IX Subsection "delocalise()" Restore the stash to its state prior to localisation. .PP .Vb 1 \& $stash = $context\->delocalise(); .Ve .SS "visit(\e%blocks)" .IX Subsection "visit(%blocks)" This method is called by Template::Document objects immediately before they process their content. It is called to register any local \f(CW\*(C`BLOCK\*(C'\fR definitions with the context object so that they may be subsequently delivered on request. .SS "\fBleave()\fP" .IX Subsection "leave()" Compliment to the \fBvisit()\fR method. Called by Template::Document objects immediately after they process their content. .SS "\fBview()\fP" .IX Subsection "view()" This method creates a Template::View object bound to the context. .SS "\fBreset()\fP" .IX Subsection "reset()" Clears the local \s-1BLOCKS\s0 cache of any \f(CW\*(C`BLOCK\*(C'\fR definitions. Any initial set of \&\s-1BLOCKS\s0 specified as a configuration item to the constructor will be reinstated. .ie n .SS "debugging($flag, @args)" .el .SS "debugging($flag, \f(CW@args\fP)" .IX Subsection "debugging($flag, @args)" This method is used to control debugging output. It is used to implement the \s-1DEBUG\s0 directive. .PP The first argument can be \f(CW\*(C`on\*(C'\fR or \f(CW\*(C`off\*(C'\fR to enable or disable debugging respectively. The numerical values \f(CW0\fR and \f(CW1\fR can also be used if you prefer. .PP .Vb 1 \& $context\->debugging(\*(Aqon\*(Aq); .Ve .PP Alternately, the first argument can be \f(CW\*(C`format\*(C'\fR to define a new debug message format. The second argument should be the format string which can contain any of the \f(CW$file\fR, \f(CW$line\fR or \f(CW$text\fR symbols to indicate where the relevant values should be inserted. .PP .Vb 2 \& # note single quotes to prevent interpolated of variables \& $context\->debugging( format => \*(Aq## $file line $line: $text\*(Aq ); .Ve .PP The final use of this method is to generate debugging messages themselves. The first argument should be \f(CW\*(C`msg\*(C'\fR, followed by a reference to a hash array of value to insert into the debugging format string. .PP .Vb 7 \& $context\->debugging( \& msg => { \& line => 20, \& file => \*(Aqexample.tt\*(Aq, \& text => \*(AqTrampoline! Trampoline!\*(Aq, \& } \& ); .Ve .SS "\s-1AUTOLOAD\s0" .IX Subsection "AUTOLOAD" An \f(CW\*(C`AUTOLOAD\*(C'\fR method provides access to context configuration items. .PP .Vb 4 \& $stash = $context\->stash(); \& $tflag = $context\->trim(); \& $epflag = $context\->eval_perl(); \& ... .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Document, Template::Exception, Template::Filters, Template::Plugins, Template::Provider, Template::Service, Template::Stash PK � �[y�^+S$ S$ man3/Template::Plugin::Table.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Table 3" .TH Template::Plugin::Table 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Table \- Plugin to present data in a table .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE table(list, rows=n, cols=n, overlap=n, pad=0) %] \& \& [% FOREACH item IN table.row(n) %] \& [% item %] \& [% END %] \& \& [% FOREACH item IN table.col(n) %] \& [% item %] \& [% END %] \& \& [% FOREACH row IN table.rows %] \& [% FOREACH item IN row %] \& [% item %] \& [% END %] \& [% END %] \& \& [% FOREACH col IN table.cols %] \& [% col.first %] \- [% col.last %] ([% col.size %] entries) \& [% END %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Table\*(C'\fR plugin allows you to format a list of data items into a virtual table. When you create a \f(CW\*(C`Table\*(C'\fR plugin via the \f(CW\*(C`USE\*(C'\fR directive, simply pass a list reference as the first parameter and then specify a fixed number of rows or columns. .PP .Vb 2 \& [% USE Table(list, rows=5) %] \& [% USE table(list, cols=5) %] .Ve .PP The \f(CW\*(C`Table\*(C'\fR plugin name can also be specified in lower case as shown in the second example above. You can also specify an alternative variable name for the plugin as per regular Template Toolkit syntax. .PP .Vb 1 \& [% USE mydata = table(list, rows=5) %] .Ve .PP The plugin then presents a table based view on the data set. The data isn't actually reorganised in any way but is available via the \f(CW\*(C`row()\*(C'\fR, \&\f(CW\*(C`col()\*(C'\fR, \f(CW\*(C`rows()\*(C'\fR and \f(CW\*(C`cols()\*(C'\fR as if formatted into a simple two dimensional table of \f(CW\*(C`n\*(C'\fR rows x \f(CW\*(C`n\*(C'\fR columns. .PP So if we had a sample \f(CW\*(C`alphabet\*(C'\fR list contained the letters '\f(CW\*(C`a\*(C'\fR' to '\f(CW\*(C`z\*(C'\fR', the above \f(CW\*(C`USE\*(C'\fR directives would create plugins that represented the following views of the alphabet. .PP .Vb 1 \& [% USE table(alphabet, ... %] \& \& rows=5 cols=5 \& a f k p u z a g m s y \& b g l q v b h n t z \& c h m r w c i o u \& d i n s x d j p v \& e j o t y e k q w \& f l r x .Ve .PP We can request a particular row or column using the \f(CW\*(C`row()\*(C'\fR and \f(CW\*(C`col()\*(C'\fR methods. .PP .Vb 4 \& [% USE table(alphabet, rows=5) %] \& [% FOREACH item = table.row(0) %] \& # [% item %] set to each of [ a f k p u z ] in turn \& [% END %] \& \& [% FOREACH item = table.col(2) %] \& # [% item %] set to each of [ m n o p q r ] in turn \& [% END %] .Ve .PP Data in rows is returned from left to right, columns from top to bottom. The first row/column is 0. By default, rows or columns that contain empty values will be padded with the undefined value to fill it to the same size as all other rows or columns. .PP For example, the last row (row 4) in the first example would contain the values \f(CW\*(C`[ e j o t y undef ]\*(C'\fR. The Template Toolkit will safely accept these undefined values and print a empty string. You can also use the \s-1IF\s0 directive to test if the value is set. .PP .Vb 5 \& [% FOREACH item = table.row(4) %] \& [% IF item %] \& Item: [% item %] \& [% END %] \& [% END %] .Ve .PP You can explicitly disable the \f(CW\*(C`pad\*(C'\fR option when creating the plugin to returned shortened rows/columns where the data is empty. .PP .Vb 4 \& [% USE table(alphabet, cols=5, pad=0) %] \& [% FOREACH item = table.col(4) %] \& # [% item %] set to each of \*(Aqy z\*(Aq \& [% END %] .Ve .PP The \f(CW\*(C`rows()\*(C'\fR method returns all rows/columns in the table as a reference to a list of rows (themselves list references). The \f(CW\*(C`row()\*(C'\fR methods when called without any arguments calls \f(CW\*(C`rows()\*(C'\fR to return all rows in the table. .PP Ditto for \f(CW\*(C`cols()\*(C'\fR and \f(CW\*(C`col()\*(C'\fR. .PP .Vb 6 \& [% USE table(alphabet, cols=5) %] \& [% FOREACH row = table.rows %] \& [% FOREACH item = row %] \& [% item %] \& [% END %] \& [% END %] .Ve .PP The Template Toolkit provides the \f(CW\*(C`first\*(C'\fR, \f(CW\*(C`last\*(C'\fR and \f(CW\*(C`size\*(C'\fR virtual methods that can be called on list references to return the first/last entry or the number of entries in a list. The following example shows how we might use this to provide an alphabetical index split into 3 even parts. .PP .Vb 4 \& [% USE table(alphabet, cols=3, pad=0) %] \& [% FOREACH group = table.col %] \& [ [% group.first %] \- [% group.last %] ([% group.size %] letters) ] \& [% END %] .Ve .PP This produces the following output: .PP .Vb 3 \& [ a \- i (9 letters) ] \& [ j \- r (9 letters) ] \& [ s \- z (8 letters) ] .Ve .PP We can also use the general purpose \f(CW\*(C`join\*(C'\fR virtual method which joins the items of the list using the connecting string specified. .PP .Vb 4 \& [% USE table(alphabet, cols=5) %] \& [% FOREACH row = table.rows %] \& [% row.join(\*(Aq \- \*(Aq) %] \& [% END %] .Ve .PP Data in the table is ordered downwards rather than across but can easily be transformed on output. For example, to format our data in 5 columns with data ordered across rather than down, we specify \f(CW\*(C`rows=5\*(C'\fR to order the data as such: .PP .Vb 5 \& a f . . \& b g . \& c h \& d i \& e j .Ve .PP and then iterate down through each column (a\-e, f\-j, etc.) printing the data across. .PP .Vb 4 \& a b c d e \& f g h i j \& . . \& . .Ve .PP Example code to do so would be much like the following: .PP .Vb 6 \& [% USE table(alphabet, rows=3) %] \& [% FOREACH cols = table.cols %] \& [% FOREACH item = cols %] \& [% item %] \& [% END %] \& [% END %] .Ve .PP Output: .PP .Vb 5 \& a b c \& d e f \& g h i \& j . . \& . .Ve .PP In addition to a list reference, the \f(CW\*(C`Table\*(C'\fR plugin constructor may be passed a reference to a Template::Iterator object or subclass thereof. The Template::Iterator \fBget_all()\fR method is first called on the iterator to return all remaining items. These are then available via the usual Table interface. .PP .Vb 1 \& [% USE DBI(dsn,user,pass) \-%] \& \& # query() returns an iterator \& [% results = DBI.query(\*(AqSELECT * FROM alphabet ORDER BY letter\*(Aq) %] \& \& # pass into Table plugin \& [% USE table(results, rows=8 overlap=1 pad=0) \-%] \& \& [% FOREACH row = table.cols \-%] \& [% row.first.letter %] \- [% row.last.letter %]: \& [% row.join(\*(Aq, \*(Aq) %] \& [% END %] .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[K](�z �z $ man3/Template::Manual::Variables.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Variables 3" .TH Template::Manual::Variables 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Variables \- Template variables and code bindings .SH "Template Variables" .IX Header "Template Variables" A reference to a hash array may be passed as the second argument to the \&\fBprocess()\fR method, containing definitions of template variables. The \f(CW\*(C`VARIABLES\*(C'\fR (a.k.a. \f(CW\*(C`PRE_DEFINE\*(C'\fR) option can also be used to pre-define variables for all templates processed by the object. .PP .Vb 6 \& my $tt = Template\->new({ \& VARIABLES => { \& version => 3.14, \& release => \*(AqSahara\*(Aq, \& }, \& }); \& \& my $vars = { \& serial_no => 271828, \& }; \& \& $tt\->process(\*(Aqmyfile\*(Aq, $vars); .Ve .PP \&\fImyfile\fR template: .PP .Vb 2 \& This is version [% version %] ([% release %]). \& Serial number: [% serial_no %] .Ve .PP Generated Output: .PP .Vb 2 \& This is version 3.14 (Sahara) \& Serial number: 271828 .Ve .PP Variable names may contain any alphanumeric characters or underscores. They may be lower, upper or mixed case although the usual convention is to use lower case. The case \fIis\fR significant however, and '\f(CW\*(C`foo\*(C'\fR', '\f(CW\*(C`Foo\*(C'\fR' and \&'\f(CW\*(C`FOO\*(C'\fR' are all different variables. Upper case variable names are permitted, but not recommended due to a possible conflict with an existing or future reserved word. As of version 2.00, these are: .PP .Vb 5 \& GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER \& IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE \& USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META \& TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP \& CLEAR TO STEP AND OR NOT MOD DIV END .Ve .PP The variable values may be of virtually any Perl type, including simple scalars, references to lists, hash arrays, subroutines or objects. The Template Toolkit will automatically apply the correct procedure to accessing these values as they are used in the template. .PP Example data: .PP .Vb 11 \& my $vars = { \& article => \*(AqThe Third Shoe\*(Aq, \& person => { \& id => 314, \& name => \*(AqMr. Blue\*(Aq, \& email => \*(Aqblue@nowhere.org\*(Aq, \& }, \& primes => [ 2, 3, 5, 7, 11, 13 ], \& wizard => sub { return join(\*(Aq \*(Aq, \*(AqAbracadabra!\*(Aq, @_) }, \& cgi => CGI\->new(\*(Aqmode=submit&debug=1\*(Aq), \& }; .Ve .PP Example template: .PP .Vb 1 \& [% article %] \& \& [% person.id %]: [% person.name %] <[% person.email %]> \& \& [% primes.first %] \- [% primes.last %], including [% primes.3 %] \& [% primes.size %] prime numbers: [% primes.join(\*(Aq, \*(Aq) %] \& \& [% wizard %] \& [% wizard(\*(AqHocus Pocus!\*(Aq) %] \& \& [% cgi.param(\*(Aqmode\*(Aq) %] .Ve .PP Generated output: .PP .Vb 1 \& The Third Shoe \& \& 314: Mr. Blue <blue@nowhere.org> \& \& 2 \- 13, including 7 \& 6 prime numbers: 2, 3, 5, 7, 11, 13 \& \& Abracadabra! \& Abracadabra! Hocus Pocus! \& \& submit .Ve .SS "Scalar Values" .IX Subsection "Scalar Values" Regular scalar variables are accessed by simply specifying their name. As these are just entries in the top-level variable hash they can be considered special cases of hash array referencing as described below, with the main namespace hash automatically implied. .PP .Vb 1 \& [% article %] .Ve .SS "Hash Array References" .IX Subsection "Hash Array References" Members of hash arrays are accessed by specifying the hash reference and key separated by the dot '\f(CW\*(C`.\*(C'\fR' operator. .PP Example data: .PP .Vb 8 \& my $vars = { \& \*(Aqhome\*(Aq => \*(Aqhttp://www.myserver.com/homepage.html\*(Aq, \& \*(Aqpage\*(Aq => { \& \*(Aqthis\*(Aq => \*(Aqmypage.html\*(Aq, \& \*(Aqnext\*(Aq => \*(Aqnextpage.html\*(Aq, \& \*(Aqprev\*(Aq => \*(Aqprevpage.html\*(Aq, \& }, \& }; .Ve .PP Example template: .PP .Vb 3 \& <a href="[% home %]">Home</a> \& <a href="[% page.prev %]">Previous Page</a> \& <a href="[% page.next %]">Next Page</a> .Ve .PP Generated output: .PP .Vb 3 \& <a href="http://www.myserver.com/homepage.html">Home</a> \& <a href="prevpage.html">Previous Page</a> \& <a href="nextpage.html">Next Page</a> .Ve .PP Any key in a hash which starts with a '\f(CW\*(C`_\*(C'\fR' or '\f(CW\*(C`.\*(C'\fR' character will be considered private and cannot be evaluated or updated from within a template. The undefined value will be returned for any such variable accessed which the Template Toolkit will silently ignore (unless the \&\f(CW\*(C`DEBUG\*(C'\fR option is enabled). .PP Example data: .PP .Vb 9 \& my $vars = { \& message => \*(AqHello World!\*(Aq, \& _secret => "On the Internet, no\-one knows you\*(Aqre a dog", \& thing => { \& public => 123, \& _private => 456, \& \*(Aq.hidden\*(Aq => 789, \& }, \& }; .Ve .PP Example template: .PP .Vb 5 \& [% message %] # outputs "Hello World!" \& [% _secret %] # no output \& [% thing.public %] # outputs "123" \& [% thing._private %] # no output \& [% thing..hidden %] # ERROR: unexpected token (..) .Ve .PP You can disable this feature by setting the \f(CW$Template::Stash::PRIVATE\fR package variable to a false value. .PP .Vb 1 \& $Template::Stash::PRIVATE = undef; # now you can thing._private .Ve .PP To access a hash entry using a key stored in another variable, prefix the key variable with '\f(CW\*(C`$\*(C'\fR' to have it interpolated before use (see \&\*(L"Variable Interpolation\*(R"). .PP .Vb 2 \& [% pagename = \*(Aqnext\*(Aq %] \& [% page.$pagename %] # same as [% page.next %] .Ve .PP You can also access hash entry using \f(CW\*(C`item()\*(C'\fR method. This might be helpful if you have complex key name. .PP .Vb 3 \& <pre> \& [% files.item(\*(Aqexample.txt\*(Aq).content %] \& </pre> .Ve .PP See Template::Manual::VMethods for more info. .PP When you assign to a variable that contains multiple namespace elements (i.e. it has one or more '\f(CW\*(C`.\*(C'\fR' characters in the name), any hashes required to represent intermediate namespaces will be created automatically. In this following example, the \f(CW\*(C`product\*(C'\fR variable automatically springs into life as a hash array unless otherwise defined. .PP .Vb 4 \& [% product.id = \*(AqXYZ\-2000\*(Aq \& product.desc = \*(AqBogon Generator\*(Aq \& product.price = 666 \& %] \& \& The [% product.id %] [% product.desc %] \& costs $[% product.price %].00 .Ve .PP Generated output: .PP .Vb 2 \& The XYZ\-2000 Bogon Generator \& costs $666.00 .Ve .PP You can use Perl's familiar \f(CW\*(C`{\*(C'\fR ... \f(CW\*(C`}\*(C'\fR construct to explicitly create a hash and assign it to a variable. Note that commas are optional between key/value pairs and \f(CW\*(C`=\*(C'\fR can be used in place of \f(CW\*(C`=>\*(C'\fR. .PP .Vb 7 \& # minimal TT style \& [% product = { \& id = \*(AqXYZ\-2000\*(Aq \& desc = \*(AqBogon Generator\*(Aq \& price = 666 \& } \& %] \& \& # perl style \& [% product = { \& id => \*(AqXYZ\-2000\*(Aq, \& desc => \*(AqBogon Generator\*(Aq, \& price => 666, \& } \& %] .Ve .SS "List References" .IX Subsection "List References" Items in lists are also accessed by use of the dot operator. .PP Example data: .PP .Vb 3 \& my $vars = { \& people => [ \*(AqTom\*(Aq, \*(AqDick\*(Aq, \*(AqLarry\*(Aq ], \& }; .Ve .PP Example template: .PP .Vb 3 \& [% people.0 %] # Tom \& [% people.1 %] # Dick \& [% people.2 %] # Larry .Ve .PP The \f(CW\*(C`FOREACH\*(C'\fR directive can be used to iterate through items in a list. .PP .Vb 3 \& [% FOREACH person IN people %] \& Hello [% person %] \& [% END %] .Ve .PP Generated output: .PP .Vb 3 \& Hello Tom \& Hello Dick \& Hello Larry .Ve .PP Lists can be constructed in-situ using the regular anonymous list \&\f(CW\*(C`[\*(C'\fR ... \f(CW\*(C`]\*(C'\fR construct. Commas between items are optional. .PP .Vb 1 \& [% cols = [ \*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq ] %] \& \& [% FOREACH c IN cols %] \& [% c %] \& [% END %] .Ve .PP or: .PP .Vb 3 \& [% FOREACH c IN [ \*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq ] %] \& [% c %] \& [% END %] .Ve .PP You can also create simple numerical sequences using the \f(CW\*(C`..\*(C'\fR range operator: .PP .Vb 1 \& [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ] \& \& [% x = 4 \& y = 8 \& z = [x..y] # z is [ 4, 5, 6, 7, 8 ] \& %] .Ve .SS "Subroutines" .IX Subsection "Subroutines" Template variables can contain references to Perl subroutines. When the variable is used, the Template Toolkit will automatically call the subroutine, passing any additional arguments specified. The return value from the subroutine is used as the variable value and inserted into the document output. .PP .Vb 3 \& my $vars = { \& wizard => sub { return join(\*(Aq \*(Aq, \*(AqAbracadabra!\*(Aq, @_) }, \& }; .Ve .PP Example template: .PP .Vb 2 \& [% wizard %] # Abracadabra! \& [% wizard(\*(AqHocus Pocus!\*(Aq) %] # Abracadabra! Hocus Pocus! .Ve .SS "Objects" .IX Subsection "Objects" Template variables can also contain references to Perl objects. Methods are called using the dot operator to specify the method against the object variable. Additional arguments can be specified as with subroutines. .PP .Vb 1 \& use CGI; \& \& my $vars = { \& # hard coded CGI params for purpose of example \& cgi => CGI\->new(\*(Aqmode=submit&debug=1\*(Aq), \& }; .Ve .PP Example template: .PP .Vb 3 \& [% FOREACH p IN cgi.param %] # returns list of param keys \& [% p %] => [% cgi.param(p) %] # fetch each param value \& [% END %] .Ve .PP Generated output: .PP .Vb 2 \& mode => submit \& debug => 1 .Ve .PP Object methods can also be called as lvalues. That is, they can appear on the left side of an assignment. The method will be called passing the assigning value as an argument. .PP .Vb 1 \& [% myobj.method = 10 %] .Ve .PP equivalent to: .PP .Vb 1 \& [% myobj.method(10) %] .Ve .SS "Passing Parameters and Returning Values" .IX Subsection "Passing Parameters and Returning Values" Subroutines and methods will be passed any arguments specified in the template. Any template variables in the argument list will first be evaluated and their resultant values passed to the code. .PP .Vb 3 \& my $vars = { \& mycode => sub { return \*(Aqreceived \*(Aq . join(\*(Aq, \*(Aq, @_) }, \& }; .Ve .PP template: .PP .Vb 2 \& [% foo = 10 %] \& [% mycode(foo, 20) %] # received 10, 20 .Ve .PP Named parameters may also be specified. These are automatically collected into a single hash array which is passed by reference as the \fBlast\fR parameter to the sub-routine. Named parameters can be specified using either \f(CW\*(C`=>\*(C'\fR or \f(CW\*(C`=\*(C'\fR and can appear anywhere in the argument list. .PP .Vb 3 \& my $vars = { \& myjoin => \e&myjoin, \& }; \& \& sub myjoin { \& # look for hash ref as last argument \& my $params = ref $_[\-1] eq \*(AqHASH\*(Aq ? pop : { }; \& return join($params\->{ joint } || \*(Aq + \*(Aq, @_); \& } .Ve .PP Example template: .PP .Vb 3 \& [% myjoin(10, 20, 30) %] \& [% myjoin(10, 20, 30, joint = \*(Aq \- \*(Aq %] \& [% myjoin(joint => \*(Aq * \*(Aq, 10, 20, 30 %] .Ve .PP Generated output: .PP .Vb 3 \& 10 + 20 + 30 \& 10 \- 20 \- 30 \& 10 * 20 * 30 .Ve .PP Parenthesised parameters may be added to any element of a variable, not just those that are bound to code or object methods. At present, parameters will be ignored if the variable isn't \*(L"callable\*(R" but are supported for future extensions. Think of them as \*(L"hints\*(R" to that variable, rather than just arguments passed to a function. .PP .Vb 2 \& [% r = \*(AqRomeo\*(Aq %] \& [% r(100, 99, s, t, v) %] # outputs "Romeo" .Ve .PP User code should return a value for the variable it represents. This can be any of the Perl data types described above: a scalar, or reference to a list, hash, subroutine or object. Where code returns a list of multiple values the items will automatically be folded into a list reference which can be accessed as per normal. .PP .Vb 5 \& my $vars = { \& # either is OK, first is recommended \& items1 => sub { return [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] }, \& items2 => sub { return ( \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ) }, \& }; .Ve .PP Example template: .PP .Vb 3 \& [% FOREACH i IN items1 %] \& ... \& [% END %] \& \& [% FOREACH i IN items2 %] \& ... \& [% END %] .Ve .SS "Error Handling" .IX Subsection "Error Handling" Errors can be reported from user code by calling \f(CW\*(C`die()\*(C'\fR. Errors raised in this way are caught by the Template Toolkit and converted to structured exceptions which can be handled from within the template. A reference to the exception object is then available as the \f(CW\*(C`error\*(C'\fR variable. .PP .Vb 5 \& my $vars = { \& barf => sub { \& die "a sick error has occurred\en"; \& }, \& }; .Ve .PP Example template: .PP .Vb 5 \& [% TRY %] \& [% barf %] # calls sub which throws error via die() \& [% CATCH %] \& [% error.info %] # outputs "a sick error has occurred\en" \& [% END %] .Ve .PP Error messages thrown via \f(CW\*(C`die()\*(C'\fR are converted to exceptions of type \&\f(CW\*(C`undef\*(C'\fR (the literal string \*(L"undef\*(R" rather than the undefined value). Exceptions of user-defined types can be thrown by calling \f(CW\*(C`die()\*(C'\fR with a reference to a Template::Exception object. .PP .Vb 1 \& use Template::Exception; \& \& my $vars = { \& login => sub { \& ...do something... \& die Template::Exception\->new( badpwd => \*(Aqpassword too silly\*(Aq ); \& }, \& }; .Ve .PP Example template: .PP .Vb 7 \& [% TRY %] \& [% login %] \& [% CATCH badpwd %] \& Bad password: [% error.info %] \& [% CATCH %] \& Some other \*(Aq[% error.type %]\*(Aq error: [% error.info %] \& [% END %] .Ve .PP The exception types \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`return\*(C'\fR are used to implement the \&\f(CW\*(C`STOP\*(C'\fR and \f(CW\*(C`RETURN\*(C'\fR directives. Throwing an exception as: .PP .Vb 1 \& die (Template::Exception\->new(\*(Aqstop\*(Aq)); .Ve .PP has the same effect as the directive: .PP .Vb 1 \& [% STOP %] .Ve .SH "Virtual Methods" .IX Header "Virtual Methods" The Template Toolkit implements a number of \*(L"virtual methods\*(R" which can be applied to scalars, hashes or lists. For example: .PP .Vb 2 \& [% mylist = [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] %] \& [% newlist = mylist.sort %] .Ve .PP Here \f(CW\*(C`mylist\*(C'\fR is a regular reference to a list, and 'sort' is a virtual method that returns a new list of the items in sorted order. You can chain multiple virtual methods together. For example: .PP .Vb 1 \& [% mylist.sort.join(\*(Aq, \*(Aq) %] .Ve .PP Here the \f(CW\*(C`join\*(C'\fR virtual method is called to join the sorted list into a single string, generating the following output: .PP .Vb 1 \& bar, baz, foo .Ve .PP See Template::Manual::VMethods for details of all the virtual methods available. .SH "Variable Interpolation" .IX Header "Variable Interpolation" The Template Toolkit uses \f(CW\*(C`$\*(C'\fR consistently to indicate that a variable should be interpolated in position. Most frequently, you see this in double-quoted strings: .PP .Vb 1 \& [% fullname = "$honorific $firstname $surname" %] .Ve .PP Or embedded in plain text when the \f(CW\*(C`INTERPOLATE\*(C'\fR option is set: .PP .Vb 1 \& Dear $honorific $firstname $surname, .Ve .PP The same rules apply within directives. If a variable is prefixed with a \f(CW\*(C`$\*(C'\fR then it is replaced with its value before being used. The most common use is to retrieve an element from a hash where the key is stored in a variable. .PP .Vb 2 \& [% uid = \*(Aqabw\*(Aq %] \& [% users.$uid %] # same as \*(Aqusers.abw\*(Aq .Ve .PP Curly braces can be used to delimit interpolated variable names where necessary. .PP .Vb 1 \& [% users.${me.id}.name %] .Ve .PP Directives such as \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR, etc., that accept a template name as the first argument, will automatically quote it for convenience. .PP .Vb 1 \& [% INCLUDE foo/bar.txt %] .Ve .PP The above example is equivalent to: .PP .Vb 1 \& [% INCLUDE "foo/bar.txt" %] .Ve .PP To \f(CW\*(C`INCLUDE\*(C'\fR a template whose name is stored in a variable, simply prefix the variable name with \f(CW\*(C`$\*(C'\fR to have it interpolated. .PP .Vb 2 \& [% myfile = \*(Aqheader\*(Aq %] \& [% INCLUDE $myfile %] .Ve .PP This is equivalent to: .PP .Vb 1 \& [% INCLUDE header %] .Ve .PP Note also that a variable containing a reference to a Template::Document object can also be processed in this way. .PP .Vb 3 \& my $vars = { \& header => Template::Document\->new({ ... }), \& }; .Ve .PP Example template: .PP .Vb 1 \& [% INCLUDE $header %] .Ve .SH "Local and Global Variables" .IX Header "Local and Global Variables" Any simple variables that you create, or any changes you make to existing variables, will only persist while the template is being processed. The top-level variable hash is copied before processing begins and any changes to variables are made in this copy, leaving the original intact. .PP The same thing happens when you \f(CW\*(C`INCLUDE\*(C'\fR another template. The current namespace hash is cloned to prevent any variable changes made in the included template from interfering with existing variables. The \f(CW\*(C`PROCESS\*(C'\fR option bypasses the localisation step altogether making it slightly faster, but requiring greater attention to the possibility of side effects caused by creating or changing any variables within the processed template. .PP .Vb 3 \& [% BLOCK change_name %] \& [% name = \*(Aqbar\*(Aq %] \& [% END %] \& \& [% name = \*(Aqfoo\*(Aq %] \& [% INCLUDE change_name %] \& [% name %] # foo \& [% PROCESS change_name %] \& [% name %] # bar .Ve .PP Dotted compound variables behave slightly differently because the localisation process is only skin deep. The current variable namespace hash is copied, but no attempt is made to perform a deep-copy of other structures within it (hashes, arrays, objects, etc). A variable referencing a hash, for example, will be copied to create a new reference but which points to the same hash. Thus, the general rule is that simple variables (undotted variables) are localised, but existing complex structures (dotted variables) are not. .PP .Vb 4 \& [% BLOCK all_change %] \& [% x = 20 %] # changes copy \& [% y.z = \*(Aqzulu\*(Aq %] # changes original \& [% END %] \& \& [% x = 10 \& y = { z => \*(Aqzebra\*(Aq } \& %] \& [% INCLUDE all_change %] \& [% x %] # still \*(Aq10\*(Aq \& [% y.z %] # now \*(Aqzulu\*(Aq .Ve .PP If you create a complex structure such as a hash or list reference within a local template context then it will cease to exist when the template is finished processing. .PP .Vb 5 \& [% BLOCK new_stuff %] \& [% # define a new \*(Aqy\*(Aq hash array in local context \& y = { z => \*(Aqzulu\*(Aq } \& %] \& [% END %] \& \& [% x = 10 %] \& [% INCLUDE new_stuff %] \& [% x %] # outputs \*(Aq10\*(Aq \& [% y %] # nothing, y is undefined .Ve .PP Similarly, if you update an element of a compound variable which \&\fIdoesn't\fR already exists then a hash will be created automatically and deleted again at the end of the block. .PP .Vb 3 \& [% BLOCK new_stuff %] \& [% y.z = \*(Aqzulu\*(Aq %] \& [% END %] .Ve .PP However, if the hash \fIdoes\fR already exist then you will modify the original with permanent effect. To avoid potential confusion, it is recommended that you don't update elements of complex variables from within blocks or templates included by another. .PP If you want to create or update truly global variables then you can use the 'global' namespace. This is a hash array automatically created in the top-level namespace which all templates, localised or otherwise see the same reference to. Changes made to variables within this hash are visible across all templates. .PP .Vb 1 \& [% global.version = 123 %] .Ve .SH "Compile Time Constant Folding" .IX Header "Compile Time Constant Folding" In addition to variables that get resolved each time a template is processed, you can also define variables that get resolved just once when the template is compiled. This generally results in templates processing faster because there is less work to be done. .PP To define compile-time constants, specify a \f(CW\*(C`CONSTANTS\*(C'\fR hash as a constructor item as per \f(CW\*(C`VARIABLES\*(C'\fR. The \f(CW\*(C`CONSTANTS\*(C'\fR hash can contain any kind of complex, nested, or dynamic data structures, just like regular variables. .PP .Vb 10 \& my $tt = Template\->new({ \& CONSTANTS => { \& version => 3.14, \& release => \*(Aqskyrocket\*(Aq, \& col => { \& back => \*(Aq#ffffff\*(Aq, \& fore => \*(Aq#000000\*(Aq, \& }, \& myobj => My::Object\->new(), \& mysub => sub { ... }, \& joint => \*(Aq, \*(Aq, \& }, \& }); .Ve .PP Within a template, you access these variables using the \f(CW\*(C`constants\*(C'\fR namespace prefix. .PP .Vb 2 \& Version [% constants.version %] ([% constants.release %]) \& Background: [% constants.col.back %] .Ve .PP When the template is compiled, these variable references are replaced with the corresponding value. No further variable lookup is then required when the template is processed. .PP You can call subroutines, object methods, and even virtual methods on constant variables. .PP .Vb 3 \& [% constants.mysub(10, 20) %] \& [% constants.myobj(30, 40) %] \& [% constants.col.keys.sort.join(\*(Aq, \*(Aq) %] .Ve .PP One important proviso is that any arguments you pass to subroutines or methods must also be literal values or compile time constants. .PP For example, these are both fine: .PP .Vb 2 \& # literal argument \& [% constants.col.keys.sort.join(\*(Aq, \*(Aq) %] \& \& # constant argument \& [% constants.col.keys.sort.join(constants.joint) %] .Ve .PP But this next example will raise an error at parse time because \&\f(CW\*(C`joint\*(C'\fR is a runtime variable and cannot be determined at compile time. .PP .Vb 2 \& # ERROR: runtime variable argument! \& [% constants.col.keys.sort.join(joint) %] .Ve .PP The \f(CW\*(C`CONSTANTS_NAMESPACE\*(C'\fR option can be used to provide a different namespace prefix for constant variables. For example: .PP .Vb 7 \& my $tt = Template\->new({ \& CONSTANTS => { \& version => 3.14, \& # ...etc... \& }, \& CONSTANTS_NAMESPACE => \*(Aqconst\*(Aq, \& }); .Ve .PP Constants would then be referenced in templates as: .PP .Vb 1 \& [% const.version %] .Ve .SH "Special Variables" .IX Header "Special Variables" A number of special variables are automatically defined by the Template Toolkit. .SS "template" .IX Subsection "template" The \f(CW\*(C`template\*(C'\fR variable contains a reference to the main template being processed, in the form of a Template::Document object. This variable is correctly defined within \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates, allowing standard headers, footers, etc., to access metadata items from the main template. The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`modtime\*(C'\fR metadata items are automatically provided, giving the template name and modification time in seconds since the epoch. .PP Note that the \f(CW\*(C`template\*(C'\fR variable always references the top-level template, even when processing other template components via \f(CW\*(C`INCLUDE\*(C'\fR, \&\f(CW\*(C`PROCESS\*(C'\fR, etc. .SS "component" .IX Subsection "component" The \f(CW\*(C`component\*(C'\fR variable is like \f(CW\*(C`template\*(C'\fR but always contains a reference to the current, innermost template component being processed. In the main template, the \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR variable will reference the same Template::Document object. In any other template component called from the main template, the \f(CW\*(C`template\*(C'\fR variable will remain unchanged, but \f(CW\*(C`component\*(C'\fR will contain a new reference to the current component. .PP This example should demonstrate the difference: .PP .Vb 2 \& $template\->process(\*(Aqfoo\*(Aq) \& || die $template\->error(), "\en"; .Ve .PP \&\fIfoo\fR template: .PP .Vb 3 \& [% template.name %] # foo \& [% component.name %] # foo \& [% PROCESS footer %] .Ve .PP \&\fIfooter\fR template: .PP .Vb 2 \& [% template.name %] # foo \& [% component.name %] # footer .Ve .PP Additionally, the \f(CW\*(C`component\*(C'\fR variable has two special fields: \&\f(CW\*(C`caller\*(C'\fR and \f(CW\*(C`callers\*(C'\fR. \f(CW\*(C`caller\*(C'\fR contains the name of the template that called the current template (or undef if the values of \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR are the same). \f(CW\*(C`callers\*(C'\fR contains a reference to a list of all the templates that have been called on the road to calling the current component template (like a call stack), with the outer-most template first. .PP Here's an example: .PP \&\fIouter.tt2\fR template: .PP .Vb 4 \& [% component.name %] # \*(Aqouter.tt2\*(Aq \& [% component.caller %] # undef \& [% component.callers %] # undef \& [% PROCESS \*(Aqmiddle.tt2\*(Aq %] .Ve .PP \&\fImiddle.tt2\fR template: .PP .Vb 4 \& [% component.name %] # \*(Aqmiddle.tt2\*(Aq \& [% component.caller %] # \*(Aqouter.tt2\*(Aq \& [% component.callers %] # [ \*(Aqouter.tt2\*(Aq ] \& [% PROCESS \*(Aqinner.tt2\*(Aq %] .Ve .PP \&\fIinner.tt2\fR template: .PP .Vb 3 \& [% component.name %] # \*(Aqinner.tt2\*(Aq \& [% component.caller %] # \*(Aqmiddle.tt2\*(Aq \& [% component.callers %] # [ \*(Aqouter.tt2\*(Aq, \*(Aqmiddle.tt2\*(Aq ] .Ve .SS "loop" .IX Subsection "loop" Within a \f(CW\*(C`FOREACH\*(C'\fR loop, the \f(CW\*(C`loop\*(C'\fR variable references the Template::Iterator object responsible for controlling the loop. .PP .Vb 4 \& [% FOREACH item = [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] \-%] \& [% "Items:\en" IF loop.first \-%] \& [% loop.count %]/[% loop.size %]: [% item %] \& [% END %] .Ve .SS "error" .IX Subsection "error" Within a \f(CW\*(C`CATCH\*(C'\fR block, the \f(CW\*(C`error\*(C'\fR variable contains a reference to the Template::Exception object thrown from within the \f(CW\*(C`TRY\*(C'\fR block. The \&\f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR methods can be called or the variable itself can be printed for automatic stringification into a message of the form "\f(CW\*(C`$type error \- $info\*(C'\fR". See Template::Exception for further details. .PP .Vb 5 \& [% TRY %] \& ... \& [% CATCH %] \& [% error %] \& [% END %] .Ve .SS "content" .IX Subsection "content" The \f(CW\*(C`WRAPPER\*(C'\fR method captures the output from a template block and then includes a named template, passing the captured output as the 'content' variable. .PP .Vb 4 \& [% WRAPPER box %] \& Be not afeard; the isle is full of noises, \& Sounds and sweet airs, that give delight and hurt not. \& [% END %] \& \& [% BLOCK box %] \& <blockquote class="prose"> \& [% content %] \& </blockquote> \& [% END %] .Ve .SH "Compound Variables" .IX Header "Compound Variables" Compound 'dotted' variables may contain any number of separate elements. Each element may evaluate to any of the permitted variable types and the processor will then correctly use this value to evaluate the rest of the variable. Arguments may be passed to any of the intermediate elements. .PP .Vb 1 \& [% myorg.people.sort(\*(Aqsurname\*(Aq).first.fullname %] .Ve .PP Intermediate variables may be used and will behave entirely as expected. .PP .Vb 2 \& [% sorted = myorg.people.sort(\*(Aqsurname\*(Aq) %] \& [% sorted.first.fullname %] .Ve .PP This simplified dotted notation has the benefit of hiding the implementation details of your data. For example, you could implement a data structure as a hash array one day and then change it to an object the next without requiring any change to the templates. PK � �[�|�"e' e' man3/Template::Stash.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Stash 3" .TH Template::Stash 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Stash \- Magical storage for template variables .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Stash; \& \& my $stash = Template::Stash\->new(\e%vars); \& \& # get variable values \& $value = $stash\->get($variable); \& $value = $stash\->get(\e@compound); \& \& # set variable value \& $stash\->set($variable, $value); \& $stash\->set(\e@compound, $value); \& \& # default variable value \& $stash\->set($variable, $value, 1); \& $stash\->set(\e@compound, $value, 1); \& \& # set variable values en masse \& $stash\->update(\e%new_vars) \& \& # methods for (de\-)localising variables \& $stash = $stash\->clone(\e%new_vars); \& $stash = $stash\->declone(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Stash\*(C'\fR module defines an object class which is used to store variable values for the runtime use of the template processor. Variable values are stored internally in a hash reference (which itself is blessed to create the object) and are accessible via the \fBget()\fR and \fBset()\fR methods. .PP Variables may reference hash arrays, lists, subroutines and objects as well as simple values. The stash automatically performs the right magic when dealing with variables, calling code or object methods, indexing into lists, hashes, etc. .PP The stash has \fBclone()\fR and \fBdeclone()\fR methods which are used by the template processor to make temporary copies of the stash for localising changes made to variables. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .SS "new(\e%params)" .IX Subsection "new(%params)" The \f(CW\*(C`new()\*(C'\fR constructor method creates and returns a reference to a new \&\f(CW\*(C`Template::Stash\*(C'\fR object. .PP .Vb 1 \& my $stash = Template::Stash\->new(); .Ve .PP A hash reference may be passed to provide variables and values which should be used to initialise the stash. .PP .Vb 2 \& my $stash = Template::Stash\->new({ var1 => \*(Aqvalue1\*(Aq, \& var2 => \*(Aqvalue2\*(Aq }); .Ve .SS "get($variable)" .IX Subsection "get($variable)" The \f(CW\*(C`get()\*(C'\fR method retrieves the variable named by the first parameter. .PP .Vb 1 \& $value = $stash\->get(\*(Aqvar1\*(Aq); .Ve .PP Dotted compound variables can be retrieved by specifying the variable elements by reference to a list. Each node in the variable occupies two entries in the list. The first gives the name of the variable element, the second is a reference to a list of arguments for that element, or \f(CW0\fR if none. .PP .Vb 1 \& [% foo.bar(10).baz(20) %] \& \& $stash\->get([ \*(Aqfoo\*(Aq, 0, \*(Aqbar\*(Aq, [ 10 ], \*(Aqbaz\*(Aq, [ 20 ] ]); .Ve .ie n .SS "set($variable, $value, $default)" .el .SS "set($variable, \f(CW$value\fP, \f(CW$default\fP)" .IX Subsection "set($variable, $value, $default)" The \f(CW\*(C`set()\*(C'\fR method sets the variable name in the first parameter to the value specified in the second. .PP .Vb 1 \& $stash\->set(\*(Aqvar1\*(Aq, \*(Aqvalue1\*(Aq); .Ve .PP If the third parameter evaluates to a true value, the variable is set only if it did not have a true value before. .PP .Vb 1 \& $stash\->set(\*(Aqvar2\*(Aq, \*(Aqdefault_value\*(Aq, 1); .Ve .PP Dotted compound variables may be specified as per \fBget()\fR above. .PP .Vb 1 \& [% foo.bar = 30 %] \& \& $stash\->set([ \*(Aqfoo\*(Aq, 0, \*(Aqbar\*(Aq, 0 ], 30); .Ve .PP The magical variable '\f(CW\*(C`IMPORT\*(C'\fR' can be specified whose corresponding value should be a hash reference. The contents of the hash array are copied (i.e. imported) into the current namespace. .PP .Vb 2 \& # foo.bar = baz, foo.wiz = waz \& $stash\->set(\*(Aqfoo\*(Aq, { \*(Aqbar\*(Aq => \*(Aqbaz\*(Aq, \*(Aqwiz\*(Aq => \*(Aqwaz\*(Aq }); \& \& # import \*(Aqfoo\*(Aq into main namespace: bar = baz, wiz = waz \& $stash\->set(\*(AqIMPORT\*(Aq, $stash\->get(\*(Aqfoo\*(Aq)); .Ve .SS "update($variables)" .IX Subsection "update($variables)" This method can be used to set or update several variables in one go. .PP .Vb 4 \& $stash\->update({ \& foo => 10, \& bar => 20, \& }); .Ve .SS "getref($variable)" .IX Subsection "getref($variable)" This undocumented feature returns a closure which can be called to get the value of a variable. It is used to implement variable references which are evaluated lazily. .PP .Vb 2 \& [% x = \efoo.bar.baz %] # x is a reference to foo.bar.baz \& [% x %] # evalautes foo.bar.baz .Ve .SS "clone(\e%params)" .IX Subsection "clone(%params)" The \f(CW\*(C`clone()\*(C'\fR method creates and returns a new \f(CW\*(C`Template::Stash\*(C'\fR object which represents a localised copy of the parent stash. Variables can be freely updated in the cloned stash and when \fBdeclone()\fR is called, the original stash is returned with all its members intact and in the same state as they were before \f(CW\*(C`clone()\*(C'\fR was called. .PP For convenience, a hash of parameters may be passed into \f(CW\*(C`clone()\*(C'\fR which is used to update any simple variable (i.e. those that don't contain any namespace elements like \f(CW\*(C`foo\*(C'\fR and \f(CW\*(C`bar\*(C'\fR but not \f(CW\*(C`foo.bar\*(C'\fR) variables while cloning the stash. For adding and updating complex variables, the \fBset()\fR method should be used after calling \f(CW\*(C`clone().\*(C'\fR This will correctly resolve and/or create any necessary namespace hashes. .PP A cloned stash maintains a reference to the stash that it was copied from in its \f(CW\*(C`_PARENT\*(C'\fR member. .SS "\fBdeclone()\fP" .IX Subsection "declone()" The \f(CW\*(C`declone()\*(C'\fR method returns the \f(CW\*(C`_PARENT\*(C'\fR reference and can be used to restore the state of a stash as described above. .ie n .SS "define_vmethod($type, $name, $code)" .el .SS "define_vmethod($type, \f(CW$name\fP, \f(CW$code\fP)" .IX Subsection "define_vmethod($type, $name, $code)" This method can be used to define new virtual methods. The first argument should be either \f(CW\*(C`scalar\*(C'\fR or \f(CW\*(C`item\*(C'\fR to define scalar virtual method, \f(CW\*(C`hash\*(C'\fR to define hash virtual methods, or either \f(CW\*(C`array\*(C'\fR or \f(CW\*(C`list\*(C'\fR for list virtual methods. The second argument should be the name of the new method. The third argument should be a reference to a subroutine implementing the method. The data item on which the virtual method is called is passed to the subroutine as the first argument. .PP .Vb 6 \& $stash\->define_vmethod( \& item => ucfirst => sub { \& my $text = shift; \& return ucfirst $text \& } \& ); .Ve .SH "INTERNAL METHODS" .IX Header "INTERNAL METHODS" .ie n .SS "dotop($root, $item, \e@args, $lvalue)" .el .SS "dotop($root, \f(CW$item\fP, \e@args, \f(CW$lvalue\fP)" .IX Subsection "dotop($root, $item, @args, $lvalue)" This is the core \f(CW\*(C`dot\*(C'\fR operation method which evaluates elements of variables against their root. .ie n .SS "undefined($ident, $args)" .el .SS "undefined($ident, \f(CW$args\fP)" .IX Subsection "undefined($ident, $args)" This method is called when \fBget()\fR encounters an undefined value. If the \&\s-1STRICT\s0 option is in effect then it will throw an exception indicating the use of an undefined value. Otherwise it will silently return an empty string. .PP The method can be redefined in a subclass to implement alternate handling of undefined values. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Context PK � �[ޚh� � man3/Template::Plugin::Pod.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Pod 3" .TH Template::Plugin::Pod 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Pod \- Plugin interface to Pod::POM (Pod Object Model) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& [% USE Pod(podfile) %] \& \& [% FOREACH head1 = Pod.head1; \& FOREACH head2 = head1/head2; \& ... \& END; \& END \& %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin is an interface to the Pod::POM module. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin, Pod::POM PK � �[�nf� ! man3/Template::Plugin::Format.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin::Format 3" .TH Template::Plugin::Format 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin::Format \- Plugin to create formatting functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& [% USE format %] \& [% commented = format(\*(Aq# %s\*(Aq) %] \& [% commented(\*(AqThe cat sat on the mat\*(Aq) %] \& \& [% USE bold = format(\*(Aq<b>%s</b>\*(Aq) %] \& [% bold(\*(AqHello\*(Aq) %] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The format plugin constructs sub-routines which format text according to a \f(CW\*(C`printf()\*(C'\fR\-like format string. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[o���@ @ man3/Template::VMethods.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::VMethods 3" .TH Template::VMethods 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::VMethods \- Virtual methods for variables .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::VMethods\*(C'\fR module implements the virtual methods that can be applied to variables. .PP Please see Template::Manual::VMethods for further information. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Stash, Template::Manual::VMethods PK � �[ q� N N man3/Template::Exception.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Exception 3" .TH Template::Exception 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Exception \- Exception handling class module .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Exception; \& \& my $exception = Template::Exception\->new($type, $info); \& $type = $exception\->type; \& $info = $exception\->info; \& ($type, $info) = $exception\->type_info; \& \& print $exception\->as_string(); \& \& $handler = $exception\->select_handler(\e@candidates); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Exception\*(C'\fR module defines an object class for representing exceptions within the template processing life cycle. Exceptions can be raised by modules within the Template Toolkit, or can be generated and returned by user code bound to template variables. .PP Exceptions can be raised in a template using the \f(CW\*(C`THROW\*(C'\fR directive, .PP .Vb 1 \& [% THROW user.login \*(Aqno user id: please login\*(Aq %] .Ve .PP or by calling the \fBthrow()\fR method on the current Template::Context object, .PP .Vb 2 \& $context\->throw(\*(Aquser.passwd\*(Aq, \*(AqIncorrect Password\*(Aq); \& $context\->throw(\*(AqIncorrect Password\*(Aq); # type \*(Aqundef\*(Aq .Ve .PP or from Perl code by calling \f(CW\*(C`die()\*(C'\fR with a \f(CW\*(C`Template::Exception\*(C'\fR object, .PP .Vb 1 \& die (Template::Exception\->new(\*(Aquser.denied\*(Aq, \*(AqInvalid User ID\*(Aq)); .Ve .PP or by simply calling \f(CW\*(C`die()\*(C'\fR with an error string. This is automagically caught and converted to an exception of '\f(CW\*(C`undef\*(C'\fR' type (that's the literal string '\f(CW\*(C`undef\*(C'\fR' rather than Perl's undefined value) which can then be handled in the usual way. .PP .Vb 1 \& die "I\*(Aqm sorry Dave, I can\*(Aqt do that"; .Ve .PP Each exception is defined by its type and a information component (e.g. error message). The type can be any identifying string and may contain dotted components (e.g. '\f(CW\*(C`foo\*(C'\fR', '\f(CW\*(C`foo.bar\*(C'\fR', '\f(CW\*(C`foo.bar.baz\*(C'\fR'). Exception types are considered to be hierarchical such that '\f(CW\*(C`foo.bar\*(C'\fR' would be a specific type of the more general '\f(CW\*(C`foo\*(C'\fR' type. .SH "METHODS" .IX Header "METHODS" .SS "\fBtype()\fP" .IX Subsection "type()" Returns the exception type. .SS "\fBinfo()\fP" .IX Subsection "info()" Returns the exception information. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Context PK � �[L<�� � man3/Template::Plugins.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugins 3" .TH Template::Plugins 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugins \- Plugin provider module .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Plugins; \& \& $plugin_provider = Template::Plugins\->new(\e%options); \& \& ($plugin, $error) = $plugin_provider\->fetch($name, @args); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Plugins\*(C'\fR module defines a provider class which can be used to load and instantiate Template Toolkit plugin modules. .SH "METHODS" .IX Header "METHODS" .SS "new(\e%params)" .IX Subsection "new(%params)" Constructor method which instantiates and returns a reference to a \&\f(CW\*(C`Template::Plugins\*(C'\fR object. A reference to a hash array of configuration items may be passed as a parameter. These are described below. .PP Note that the Template front-end module creates a \f(CW\*(C`Template::Plugins\*(C'\fR provider, passing all configuration items. Thus, the examples shown below in the form: .PP .Vb 5 \& $plugprov = Template::Plugins\->new({ \& PLUGIN_BASE => \*(AqMyTemplate::Plugin\*(Aq, \& LOAD_PERL => 1, \& ... \& }); .Ve .PP can also be used via the Template module as: .PP .Vb 5 \& $ttengine = Template\->new({ \& PLUGIN_BASE => \*(AqMyTemplate::Plugin\*(Aq, \& LOAD_PERL => 1, \& ... \& }); .Ve .PP as well as the more explicit form of: .PP .Vb 5 \& $plugprov = Template::Plugins\->new({ \& PLUGIN_BASE => \*(AqMyTemplate::Plugin\*(Aq, \& LOAD_PERL => 1, \& ... \& }); \& \& $ttengine = Template\->new({ \& LOAD_PLUGINS => [ $plugprov ], \& }); .Ve .ie n .SS "fetch($name, @args)" .el .SS "fetch($name, \f(CW@args\fP)" .IX Subsection "fetch($name, @args)" Called to request that a plugin of a given name be provided. The relevant module is first loaded (if necessary) and the \&\fBload()\fR class method called to return the factory class name (usually the same package name) or a factory object (a prototype). The \fBnew()\fR method is then called as a class or object method against the factory, passing all remaining parameters. .PP Returns a reference to a new plugin object or \f(CW\*(C`($error, STATUS_ERROR)\*(C'\fR on error. May also return \f(CW\*(C`(undef, STATUS_DECLINED)\*(C'\fR to decline to serve the request. If \f(CW\*(C`TOLERANT\*(C'\fR is set then all errors will be returned as declines. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" The following list summarises the configuration options that can be provided to the \f(CW\*(C`Template::Plugins\*(C'\fR \fBnew()\fR constructor. Please consult Template::Manual::Config for further details and examples of each configuration option in use. .SS "\s-1PLUGINS\s0" .IX Subsection "PLUGINS" The \s-1PLUGINS\s0 option can be used to provide a reference to a hash array that maps plugin names to Perl module names. .PP .Vb 7 \& my $plugins = Template::Plugins\->new({ \& PLUGINS => { \& cgi => \*(AqMyOrg::Template::Plugin::CGI\*(Aq, \& foo => \*(AqMyOrg::Template::Plugin::Foo\*(Aq, \& bar => \*(AqMyOrg::Template::Plugin::Bar\*(Aq, \& }, \& }); .Ve .SS "\s-1PLUGIN_BASE\s0" .IX Subsection "PLUGIN_BASE" If a plugin is not defined in the \s-1PLUGINS\s0 hash then the \s-1PLUGIN_BASE\s0 is used to attempt to construct a correct Perl module name which can be successfully loaded. .PP .Vb 4 \& # single value PLUGIN_BASE \& my $plugins = Template::Plugins\->new({ \& PLUGIN_BASE => \*(AqMyOrg::Template::Plugin\*(Aq, \& }); \& \& # multiple value PLUGIN_BASE \& my $plugins = Template::Plugins\->new({ \& PLUGIN_BASE => [ \*(AqMyOrg::Template::Plugin\*(Aq, \& \*(AqYourOrg::Template::Plugin\*(Aq ], \& }); .Ve .SS "\s-1LOAD_PERL\s0" .IX Subsection "LOAD_PERL" The \s-1LOAD_PERL\s0 option can be set to allow you to load regular Perl modules (i.e. those that don't reside in the \&\f(CW\*(C`Template::Plugin\*(C'\fR or another user-defined namespace) as plugins. .PP If a plugin cannot be loaded using the \&\s-1PLUGINS\s0 or \&\s-1PLUGIN_BASE\s0 approaches then, if the \s-1LOAD_PERL\s0 is set, the provider will make a final attempt to load the module without prepending any prefix to the module path. .PP Unlike regular plugins, modules loaded using \s-1LOAD_PERL\s0 do not receive a Template::Context reference as the first argument to the \&\f(CW\*(C`new()\*(C'\fR constructor method. .SS "\s-1TOLERANT\s0" .IX Subsection "TOLERANT" The \s-1TOLERANT\s0 flag can be set to indicate that the \f(CW\*(C`Template::Plugins\*(C'\fR module should ignore any errors encountered while loading a plugin and instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR. .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \s-1DEBUG\s0 option can be used to enable debugging messages for the \f(CW\*(C`Template::Plugins\*(C'\fR module by setting it to include the \f(CW\*(C`DEBUG_PLUGINS\*(C'\fR value. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS, \& }); .Ve .SH "TEMPLATE TOOLKIT PLUGINS" .IX Header "TEMPLATE TOOLKIT PLUGINS" Please see Template::Manual::Plugins For a complete list of all the plugin modules distributed with the Template Toolkit. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Manual::Plugins, Template::Plugin, Template::Context, Template. PK � �[ʬ�DQ# Q# man3/Template::Plugin.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Plugin 3" .TH Template::Plugin 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Plugin \- Base class for Template Toolkit plugins .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& package MyOrg::Template::Plugin::MyPlugin; \& use base qw( Template::Plugin ); \& use Template::Plugin; \& use MyModule; \& \& sub new { \& my $class = shift; \& my $context = shift; \& bless { \& ... \& }, $class; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A \*(L"plugin\*(R" for the Template Toolkit is simply a Perl module which exists in a known package location (e.g. \f(CW\*(C`Template::Plugin::*\*(C'\fR) and conforms to a regular standard, allowing it to be loaded and used automatically. .PP The \f(CW\*(C`Template::Plugin\*(C'\fR module defines a base class from which other plugin modules can be derived. A plugin does not have to be derived from Template::Plugin but should at least conform to its object-oriented interface. .PP It is recommended that you create plugins in your own package namespace to avoid conflict with toolkit plugins. e.g. .PP .Vb 1 \& package MyOrg::Template::Plugin::FooBar; .Ve .PP Use the \s-1PLUGIN_BASE\s0 option to specify the namespace that you use. e.g. .PP .Vb 4 \& use Template; \& my $template = Template\->new({ \& PLUGIN_BASE => \*(AqMyOrg::Template::Plugin\*(Aq, \& }); .Ve .SH "METHODS" .IX Header "METHODS" The following methods form the basic interface between the Template Toolkit and plugin modules. .SS "load($context)" .IX Subsection "load($context)" This method is called by the Template Toolkit when the plugin module is first loaded. It is called as a package method and thus implicitly receives the package name as the first parameter. A reference to the Template::Context object loading the plugin is also passed. The default behaviour for the \f(CW\*(C`load()\*(C'\fR method is to simply return the class name. The calling context then uses this class name to call the \f(CW\*(C`new()\*(C'\fR package method. .PP .Vb 1 \& package MyPlugin; \& \& sub load { # called as MyPlugin\->load($context) \& my ($class, $context) = @_; \& return $class; # returns \*(AqMyPlugin\*(Aq \& } .Ve .ie n .SS "new($context, @params)" .el .SS "new($context, \f(CW@params\fP)" .IX Subsection "new($context, @params)" This method is called to instantiate a new plugin object for the \f(CW\*(C`USE\*(C'\fR directive. It is called as a package method against the class name returned by \&\fBload()\fR. A reference to the Template::Context object creating the plugin is passed, along with any additional parameters specified in the \f(CW\*(C`USE\*(C'\fR directive. .PP .Vb 6 \& sub new { # called as MyPlugin\->new($context) \& my ($class, $context, @params) = @_; \& bless { \& _CONTEXT => $context, \& }, $class; # returns blessed MyPlugin object \& } .Ve .SS "error($error)" .IX Subsection "error($error)" This method, inherited from the Template::Base module, is used for reporting and returning errors. It can be called as a package method to set/return the \f(CW$ERROR\fR package variable, or as an object method to set/return the object \f(CW\*(C`_ERROR\*(C'\fR member. When called with an argument, it sets the relevant variable and returns \f(CW\*(C`undef.\*(C'\fR When called without an argument, it returns the value of the variable. .PP .Vb 2 \& package MyPlugin; \& use base \*(AqTemplate::Plugin\*(Aq; \& \& sub new { \& my ($class, $context, $dsn) = @_; \& \& return $class\->error(\*(AqNo data source specified\*(Aq) \& unless $dsn; \& \& bless { \& _DSN => $dsn, \& }, $class; \& } \& \& package main; \& \& my $something = MyPlugin\->new() \& || die MyPlugin\->error(), "\en"; \& \& $something\->do_something() \& || die $something\->error(), "\en"; .Ve .SH "DEEPER MAGIC" .IX Header "DEEPER MAGIC" The Template::Context object that handles the loading and use of plugins calls the \fBnew()\fR and \fBerror()\fR methods against the package name returned by the \fBload()\fR method. In pseudo-code terms looks something like this: .PP .Vb 1 \& $class = MyPlugin\->load($context); # returns \*(AqMyPlugin\*(Aq \& \& $object = $class\->new($context, @params) # MyPlugin\->new(...) \& || die $class\->error(); # MyPlugin\->error() .Ve .PP The \fBload()\fR method may alternately return a blessed reference to an object instance. In this case, \fBnew()\fR and \fBerror()\fR are then called as \&\fIobject\fR methods against that prototype instance. .PP .Vb 1 \& package YourPlugin; \& \& sub load { \& my ($class, $context) = @_; \& bless { \& _CONTEXT => $context, \& }, $class; \& } \& \& sub new { \& my ($self, $context, @params) = @_; \& return $self; \& } .Ve .PP In this example, we have implemented a 'Singleton' plugin. One object gets created when \fBload()\fR is called and this simply returns itself for each call to \fBnew()\fR. .PP Another implementation might require individual objects to be created for every call to \fBnew()\fR, but with each object sharing a reference to some other object to maintain cached data, database handles, etc. This pseudo-code example demonstrates the principle. .PP .Vb 1 \& package MyServer; \& \& sub load { \& my ($class, $context) = @_; \& bless { \& _CONTEXT => $context, \& _CACHE => { }, \& }, $class; \& } \& \& sub new { \& my ($self, $context, @params) = @_; \& MyClient\->new($self, @params); \& } \& \& sub add_to_cache { ... } \& \& sub get_from_cache { ... } \& \& package MyClient; \& \& sub new { \& my ($class, $server, $blah) = @_; \& bless { \& _SERVER => $server, \& _BLAH => $blah, \& }, $class; \& } \& \& sub get { \& my $self = shift; \& $self\->{ _SERVER }\->get_from_cache(@_); \& } \& \& sub put { \& my $self = shift; \& $self\->{ _SERVER }\->add_to_cache(@_); \& } .Ve .PP When the plugin is loaded, a \f(CW\*(C`MyServer\*(C'\fR instance is created. The \fBnew()\fR method is called against this object which instantiates and returns a \f(CW\*(C`MyClient\*(C'\fR object, primed to communicate with the creating \f(CW\*(C`MyServer\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Plugins, Template::Context PK � �[�S&� � man3/Template::Parser.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Parser 3" .TH Template::Parser 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Parser \- LALR(1) parser for compiling template documents .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Template::Parser; \& \& $parser = Template::Parser\->new(\e%config); \& $template = $parser\->parse($text) \& || die $parser\->error(), "\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Parser\*(C'\fR module implements a \s-1\fBLALR\s0\fR\|(1) parser and associated methods for parsing template documents into Perl code. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .SS "new(\e%params)" .IX Subsection "new(%params)" The \f(CW\*(C`new()\*(C'\fR constructor creates and returns a reference to a new \&\f(CW\*(C`Template::Parser\*(C'\fR object. .PP A reference to a hash may be supplied as a parameter to provide configuration values. See \*(L"\s-1CONFIGURATION OPTIONS\*(R"\s0 below for a summary of these options and Template::Manual::Config for full details. .PP .Vb 4 \& my $parser = Template::Parser\->new({ \& START_TAG => quotemeta(\*(Aq<+\*(Aq), \& END_TAG => quotemeta(\*(Aq+>\*(Aq), \& }); .Ve .SS "parse($text)" .IX Subsection "parse($text)" The \f(CW\*(C`parse()\*(C'\fR method parses the text passed in the first parameter and returns a reference to a hash array of data defining the compiled representation of the template text, suitable for passing to the Template::Document \fBnew()\fR constructor method. On error, undef is returned. .PP .Vb 2 \& $data = $parser\->parse($text) \& || die $parser\->error(); .Ve .PP The \f(CW$data\fR hash reference returned contains a \f(CW\*(C`BLOCK\*(C'\fR item containing the compiled Perl code for the template, a \f(CW\*(C`DEFBLOCKS\*(C'\fR item containing a reference to a hash array of sub-template \f(CW\*(C`BLOCK\*(C'\fRs defined within in the template, and a \f(CW\*(C`METADATA\*(C'\fR item containing a reference to a hash array of metadata values defined in \f(CW\*(C`META\*(C'\fR tags. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" The \f(CW\*(C`Template::Parser\*(C'\fR module accepts the following configuration options. Please see Template::Manual::Config for further details on each option. .SS "\s-1START_TAG, END_TAG\s0" .IX Subsection "START_TAG, END_TAG" The \s-1START_TAG\s0 and \&\s-1END_TAG\s0 options are used to specify character sequences or regular expressions that mark the start and end of a template directive. .PP .Vb 4 \& my $parser = Template::Parser\->new({ \& START_TAG => quotemeta(\*(Aq<+\*(Aq), \& END_TAG => quotemeta(\*(Aq+>\*(Aq), \& }); .Ve .SS "\s-1TAG_STYLE\s0" .IX Subsection "TAG_STYLE" The \s-1TAG_STYLE\s0 option can be used to set both \s-1START_TAG\s0 and \s-1END_TAG\s0 according to pre-defined tag styles. .PP .Vb 3 \& my $parser = Template::Parser\->new({ \& TAG_STYLE => \*(Aqstar\*(Aq, # [* ... *] \& }); .Ve .SS "\s-1PRE_CHOMP, POST_CHOMP\s0" .IX Subsection "PRE_CHOMP, POST_CHOMP" The \s-1PRE_CHOMP\s0 and \&\s-1POST_CHOMP\s0 can be set to remove any whitespace before or after a directive tag, respectively. .PP .Vb 4 \& my $parser = Template::Parser\-E<gt>new({ \& PRE_CHOMP => 1, \& POST_CHOMP => 1, \& }); .Ve .SS "\s-1INTERPOLATE\s0" .IX Subsection "INTERPOLATE" The \s-1INTERPOLATE\s0 flag can be set to allow variables to be embedded in plain text blocks. .PP .Vb 3 \& my $parser = Template::Parser\->new({ \& INTERPOLATE => 1, \& }); .Ve .PP Variables should be prefixed by a \f(CW\*(C`$\*(C'\fR to identify them, using curly braces to explicitly scope the variable name where necessary. .PP .Vb 1 \& Hello ${name}, \& \& The day today is ${day.today}. .Ve .SS "\s-1ANYCASE\s0" .IX Subsection "ANYCASE" The \s-1ANYCASE\s0 option can be set to allow directive keywords to be specified in any case. .PP .Vb 4 \& # with ANYCASE set to 1 \& [% INCLUDE foobar %] # OK \& [% include foobar %] # OK \& [% include = 10 %] # ERROR, \*(Aqinclude\*(Aq is a reserved word .Ve .SS "\s-1GRAMMAR\s0" .IX Subsection "GRAMMAR" The \s-1GRAMMAR\s0 configuration item can be used to specify an alternate grammar for the parser. This allows a modified or entirely new template language to be constructed and used by the Template Toolkit. .PP .Vb 1 \& use MyOrg::Template::Grammar; \& \& my $parser = Template::Parser\->new({ \& GRAMMAR = MyOrg::Template::Grammar\->new(); \& }); .Ve .PP By default, an instance of the default Template::Grammar will be created and used automatically if a \f(CW\*(C`GRAMMAR\*(C'\fR item isn't specified. .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \s-1DEBUG\s0 option can be used to enable various debugging features of the \f(CW\*(C`Template::Parser\*(C'\fR module. .PP .Vb 1 \& use Template::Constants qw( :debug ); \& \& my $template = Template\->new({ \& DEBUG => DEBUG_PARSER | DEBUG_DIRS, \& }); .Ve .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The main parsing loop of the \f(CW\*(C`Template::Parser\*(C'\fR module was derived from a standalone parser generated by version 0.16 of the \f(CW\*(C`Parse::Yapp\*(C'\fR module. The following copyright notice appears in the \f(CW\*(C`Parse::Yapp\*(C'\fR documentation. .PP .Vb 3 \& The Parse::Yapp module and its related modules and shell \& scripts are copyright (c) 1998 Francois Desarmenien, \& France. All rights reserved. \& \& You may use and distribute them under the terms of either \& the GNU General Public License or the Artistic License, as \& specified in the Perl README file. .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Template, Template::Grammar, Template::Directive PK � �[ôc�� � man3/Template::Directive.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Directive 3" .TH Template::Directive 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Directive \- Perl code generator for template directives .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # no user serviceable parts inside .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Directive\*(C'\fR module defines a number of methods that generate Perl code for the runtime representation of the various Template Toolkit directives. .PP It is used internally by the Template::Parser module. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Parser PK � �[H����% �% man3/Template::Iterator.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Iterator 3" .TH Template::Iterator 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Iterator \- Data iterator used by the FOREACH directive .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& my $iter = Template::Iterator\->new(\e@data, \e%options); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Template::Iterator\*(C'\fR module defines a generic data iterator for use by the \f(CW\*(C`FOREACH\*(C'\fR directive. .PP It may be used as the base class for custom iterators. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .SS "new($data)" .IX Subsection "new($data)" Constructor method. A reference to a list of values is passed as the first parameter. Subsequent calls to \fBget_first()\fR and \fBget_next()\fR calls will return each element from the list. .PP .Vb 1 \& my $iter = Template::Iterator\->new([ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ]); .Ve .PP The constructor will also accept a reference to a hash array and will expand it into a list in which each entry is a hash array containing a '\f(CW\*(C`key\*(C'\fR' and '\f(CW\*(C`value\*(C'\fR' item, sorted according to the hash keys. .PP .Vb 4 \& my $iter = Template::Iterator\->new({ \& foo => \*(AqFoo Item\*(Aq, \& bar => \*(AqBar Item\*(Aq, \& }); .Ve .PP This is equivalent to: .PP .Vb 4 \& my $iter = Template::Iterator\->new([ \& { key => \*(Aqbar\*(Aq, value => \*(AqBar Item\*(Aq }, \& { key => \*(Aqfoo\*(Aq, value => \*(AqFoo Item\*(Aq }, \& ]); .Ve .PP When passed a single item which is not an array reference, the constructor will automatically create a list containing that single item. .PP .Vb 1 \& my $iter = Template::Iterator\->new(\*(Aqfoo\*(Aq); .Ve .PP This is equivalent to: .PP .Vb 1 \& my $iter = Template::Iterator\->new([ \*(Aqfoo\*(Aq ]); .Ve .PP Note that a single item which is an object based on a blessed \s-1ARRAY\s0 references will \s-1NOT\s0 be treated as an array and will be folded into a list containing that one object reference. .PP .Vb 2 \& my $list = bless [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ], \*(AqMyListClass\*(Aq; \& my $iter = Template::Iterator\->new($list); .Ve .PP equivalent to: .PP .Vb 1 \& my $iter = Template::Iterator\->new([ $list ]); .Ve .PP If the object provides an \f(CW\*(C`as_list()\*(C'\fR method then the Template::Iterator constructor will call that method to return the list of data. For example: .PP .Vb 1 \& package MyListObject; \& \& sub new { \& my $class = shift; \& bless [ @_ ], $class; \& } \& \& package main; \& \& my $list = MyListObject\->new(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq); \& my $iter = Template::Iterator\->new($list); .Ve .PP This is then functionally equivalent to: .PP .Vb 1 \& my $iter = Template::Iterator\->new([ $list ]); .Ve .PP The iterator will return only one item, a reference to the \f(CW\*(C`MyListObject\*(C'\fR object, \f(CW$list\fR. .PP By adding an \f(CW\*(C`as_list()\*(C'\fR method to the \f(CW\*(C`MyListObject\*(C'\fR class, we can force the \f(CW\*(C`Template::Iterator\*(C'\fR constructor to treat the object as a list and use the data contained within. .PP .Vb 1 \& package MyListObject; \& \& ... \& \& sub as_list { \& my $self = shift; \& return $self; \& } \& \& package main; \& \& my $list = MyListObject\->new(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq); \& my $iter = Template::Iterator\->new($list); .Ve .PP The iterator will now return the two items, '\f(CW\*(C`foo\*(C'\fR' and '\f(CW\*(C`bar\*(C'\fR', which the \&\f(CW\*(C`MyObjectList\*(C'\fR encapsulates. .SS "\fBget_first()\fP" .IX Subsection "get_first()" Returns a \f(CW\*(C`($value, $error)\*(C'\fR pair for the first item in the iterator set. The \f(CW$error\fR returned may be zero or undefined to indicate a valid datum was successfully returned. Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if the list is empty. .SS "\fBget_next()\fP" .IX Subsection "get_next()" Returns a \f(CW\*(C`($value, $error)\*(C'\fR pair for the next item in the iterator set. Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if all items in the list have been visited. .SS "\fBget_all()\fP" .IX Subsection "get_all()" Returns a \f(CW\*(C`(\e@values, $error)\*(C'\fR pair for all remaining items in the iterator set. Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if all items in the list have been visited. .SS "\fBsize()\fP" .IX Subsection "size()" Returns the size of the data set or undef if unknown. .SS "\fBmax()\fP" .IX Subsection "max()" Returns the maximum index number (i.e. the index of the last element) which is equivalent to \fBsize()\fR \- \f(CW1\fR. .SS "\fBindex()\fP" .IX Subsection "index()" Returns the current index number which is in the range \f(CW0\fR to \fBmax()\fR. .SS "\fBcount()\fP" .IX Subsection "count()" Returns the current iteration count in the range \f(CW1\fR to \fBsize()\fR. This is equivalent to \fBindex()\fR + \f(CW1\fR. .SS "\fBfirst()\fP" .IX Subsection "first()" Returns a boolean value to indicate if the iterator is currently on the first iteration of the set. .SS "\fBlast()\fP" .IX Subsection "last()" Returns a boolean value to indicate if the iterator is currently on the last iteration of the set. .SS "\fBprev()\fP" .IX Subsection "prev()" Returns the previous item in the data set, or \f(CW\*(C`undef\*(C'\fR if the iterator is on the first item. .SS "\fBnext()\fP" .IX Subsection "next()" Returns the next item in the data set or \f(CW\*(C`undef\*(C'\fR if the iterator is on the last item. .SS "\fBnumber()\fP" .IX Subsection "number()" This is an alias to 'count' to provide backward compatibility. View count. .SS "\fBparity()\fP" .IX Subsection "parity()" Returns the text string \f(CW\*(C`even\*(C'\fR or \f(CW\*(C`odd\*(C'\fR to indicate the parity of the current iteration count (starting at 1). This is typically used to create striped \fIzebra tables\fR. .PP .Vb 7 \& <table> \& [% FOREACH name IN [\*(AqArthur\*(Aq, \*(AqFord\*(Aq, \*(AqTrillian\*(Aq] \-%] \& <tr class="[% loop.parity %]"> \& <td>[% name %]</td> \& </tr> \& [% END %] \& </table> .Ve .PP This will produce the following output: .PP .Vb 11 \& <table> \& <tr class="odd"> \& <td>Arthur</td> \& </tr> \& <tr class="even"> \& <td>Ford</td> \& </tr> \& <tr class="odd"> \& <td>Trillian</td> \& </tr> \& </table> .Ve .PP You can then style the \f(CW\*(C`tr.odd\*(C'\fR and \f(CW\*(C`tr.even\*(C'\fR elements using \s-1CSS:\s0 .PP .Vb 4 \& tr.odd td { \& background\-color: black; \& color: white; \& } \& \& tr.even td { \& background\-color: white; \& color: black; \& } .Ve .SS "\fBodd()\fP" .IX Subsection "odd()" Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an odd number. In other words, this will return a true value for the first iterator, the third, fifth, and so on. .SS "\fBeven()\fP" .IX Subsection "even()" Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an even number. In other words, this will return a true value for the second iteration, the fourth, sixth, and so on. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template PK � �[��>2�% �% % man3/Template::Manual::Directives.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Directives 3" .TH Template::Manual::Directives 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Directives \- Template directives .SH "Accessing and Updating Template Variables" .IX Header "Accessing and Updating Template Variables" .SS "\s-1GET\s0" .IX Subsection "GET" The \f(CW\*(C`GET\*(C'\fR directive retrieves and outputs the value of the named variable. .PP .Vb 1 \& [% GET foo %] .Ve .PP The \f(CW\*(C`GET\*(C'\fR keyword is optional. A variable can be specified in a directive tag by itself. .PP .Vb 1 \& [% foo %] .Ve .PP The variable can have an unlimited number of elements, each separated by a dot. Each element can have arguments specified within parentheses. .PP .Vb 4 \& [% foo %] \& [% bar.baz %] \& [% biz.baz(10) %] \& ...etc... .Ve .PP See Template::Manual::Variables for a full discussion on template variables. .PP You can also specify expressions using the logical (\f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR, \f(CW\*(C`not\*(C'\fR, \f(CW\*(C`?\*(C'\fR, \f(CW\*(C`:\*(C'\fR) and mathematic operators (\f(CW\*(C`+\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`/\*(C'\fR, \f(CW\*(C`%\*(C'\fR, \f(CW\*(C`mod\*(C'\fR, \f(CW\*(C`div\*(C'\fR). .PP .Vb 1 \& [% template.title or default.title %] \& \& [% score * 100 %] \& \& [% order.nitems ? checkout(order.total) : \*(Aqno items\*(Aq %] .Ve .PP The \f(CW\*(C`div\*(C'\fR operator returns the integer result of division. Both \f(CW\*(C`%\*(C'\fR and \&\f(CW\*(C`mod\*(C'\fR return the modulus (i.e. remainder) of division. .PP .Vb 3 \& [% 15 / 6 %] # 2.5 \& [% 15 div 6 %] # 2 \& [% 15 mod 6 %] # 3 .Ve .SS "\s-1CALL\s0" .IX Subsection "CALL" The \f(CW\*(C`CALL\*(C'\fR directive is similar to \f(CW\*(C`GET\*(C'\fR in evaluating the variable named, but doesn't print the result returned. This can be useful when a variable is bound to a sub-routine or object method which you want to call but aren't interested in the value returned. .PP .Vb 1 \& [% CALL dbi.disconnect %] \& \& [% CALL inc_page_counter(page_count) %] .Ve .SS "\s-1SET\s0" .IX Subsection "SET" The \f(CW\*(C`SET\*(C'\fR directive allows you to assign new values to existing variables or create new temporary variables. .PP .Vb 1 \& [% SET title = \*(AqHello World\*(Aq %] .Ve .PP The \f(CW\*(C`SET\*(C'\fR keyword is also optional. .PP .Vb 1 \& [% title = \*(AqHello World\*(Aq %] .Ve .PP Variables may be assigned the values of other variables, unquoted numbers (2.718), literal text ('single quotes') or quoted text (\*(L"double quotes\*(R"). In the latter case, any variable references within the text will be interpolated when the string is evaluated. Variables should be prefixed by \f(CW\*(C`$\*(C'\fR, using curly braces to explicitly scope the variable name where necessary. .PP .Vb 4 \& [% foo = \*(AqFoo\*(Aq %] # literal value \*(AqFoo\*(Aq \& [% bar = foo %] # value of variable \*(Aqfoo\*(Aq \& [% cost = \*(Aq$100\*(Aq %] # literal value \*(Aq$100\*(Aq \& [% item = "$bar: ${cost}.00" %] # value "Foo: $100.00" .Ve .PP Multiple variables may be assigned in the same directive and are evaluated in the order specified. Thus, the above could have been written: .PP .Vb 5 \& [% foo = \*(AqFoo\*(Aq \& bar = foo \& cost = \*(Aq$100\*(Aq \& item = "$bar: ${cost}.00" \& %] .Ve .PP Simple expressions can also be used, as per \f(CW\*(C`GET\*(C'\fR. .PP .Vb 7 \& [% ten = 10 \& twenty = 20 \& thirty = twenty + ten \& forty = 2 * twenty \& fifty = 100 div 2 \& six = twenty mod 7 \& %] .Ve .PP You can concatenate strings together using the \f(CW\*(Aq_\*(Aq\fR underscore operator. In Perl 5, the \f(CW\*(C`.\*(C'\fR dot is used for string concatenation, but in Perl 6, as in the Template Toolkit, the \f(CW\*(C`.\*(C'\fR dot will be used as the method calling operator and \f(CW\*(Aq_\*(Aq\fR underscore will be used for string concatenation. Note that the operator must be specified with surrounding whitespace which, as Larry says, is construed as a feature: .PP .Vb 1 \& [% copyright = \*(Aq(C) Copyright\*(Aq _ year _ \*(Aq \*(Aq _ author %] .Ve .PP You can, of course, achieve a similar effect with double quoted string interpolation. .PP .Vb 1 \& [% copyright = "(C) Copyright $year $author" %] .Ve .SS "\s-1DEFAULT\s0" .IX Subsection "DEFAULT" The \f(CW\*(C`DEFAULT\*(C'\fR directive is similar to \f(CW\*(C`SET\*(C'\fR but only updates variables that are currently undefined or have no \*(L"true\*(R" value (in the Perl sense). .PP .Vb 4 \& [% DEFAULT \& name = \*(AqJohn Doe\*(Aq \& id = \*(Aqjdoe\*(Aq \& %] .Ve .PP This can be particularly useful in common template components to ensure that some sensible default are provided for otherwise undefined variables. .PP .Vb 10 \& [% DEFAULT \& title = \*(AqHello World\*(Aq \& bgcol = \*(Aq#ffffff\*(Aq \& %] \& <html> \& <head> \& <title>[% title %]</title> \& </head> \& <body bgcolor="[% bgcol %]"> \& ...etc... .Ve .SH "Processing Template Files and Blocks" .IX Header "Processing Template Files and Blocks" .SS "\s-1INSERT\s0" .IX Subsection "INSERT" The \f(CW\*(C`INSERT\*(C'\fR directive is used to insert the contents of an external file at the current position. .PP .Vb 1 \& [% INSERT myfile %] .Ve .PP No attempt to parse or process the file is made. The contents, possibly including any embedded template directives, are inserted intact. .PP The filename specified should be relative to one of the \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories. Absolute (i.e. starting with \f(CW\*(C`/\*(C'\fR) and relative (i.e. starting with \f(CW\*(C`.\*(C'\fR) filenames may be used if the \f(CW\*(C`ABSOLUTE\*(C'\fR and \&\f(CW\*(C`RELATIVE\*(C'\fR options are set, respectively. Both these options are disabled by default. .PP .Vb 3 \& my $template = Template\->new({ \& INCLUDE_PATH => \*(Aq/here:/there\*(Aq, \& }); \& \& $template\->process(\*(Aqmyfile\*(Aq); .Ve .PP \&\fImyfile\fR: .PP .Vb 3 \& [% INSERT foo %] # looks for /here/foo then /there/foo \& [% INSERT /etc/passwd %] # file error: ABSOLUTE not set \& [% INSERT ../secret %] # file error: RELATIVE not set .Ve .PP For convenience, the filename does not need to be quoted as long as it contains only alphanumeric characters, underscores, dots or forward slashes. Names containing any other characters should be quoted. .PP .Vb 2 \& [% INSERT misc/legalese.txt %] \& [% INSERT \*(Aqdos98/Program Files/stupid\*(Aq %] .Ve .PP To evaluate a variable to specify a filename, you should explicitly prefix it with a \f(CW\*(C`$\*(C'\fR or use double-quoted string interpolation. .PP .Vb 3 \& [% language = \*(Aqen\*(Aq \& legalese = \*(Aqmisc/legalese.txt\*(Aq \& %] \& \& [% INSERT $legalese %] # misc/legalese.txt \& [% INSERT "$language/$legalese" %] # en/misc/legalese.txt .Ve .PP Multiple files can be specified using \f(CW\*(C`+\*(C'\fR as a delimiter. All files should be unquoted names or quoted strings. Any variables should be interpolated into double-quoted strings. .PP .Vb 2 \& [% INSERT legalese.txt + warning.txt %] \& [% INSERT "$legalese" + warning.txt %] # requires quoting .Ve .SS "\s-1INCLUDE\s0" .IX Subsection "INCLUDE" The \f(CW\*(C`INCLUDE\*(C'\fR directive is used to process and include the output of another template file or block. .PP .Vb 1 \& [% INCLUDE header %] .Ve .PP If a \f(CW\*(C`BLOCK\*(C'\fR of the specified name is defined in the same file, or in a file from which the current template has been called (i.e. a parent template) then it will be used in preference to any file of the same name. .PP .Vb 1 \& [% INCLUDE table %] # uses BLOCK defined below \& \& [% BLOCK table %] \& <table> \& ... \& </table> \& [% END %] .Ve .PP If a \f(CW\*(C`BLOCK\*(C'\fR definition is not currently visible then the template name should be a file relative to one of the \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories, or an absolute or relative file name if the \f(CW\*(C`ABSOLUTE\*(C'\fR/\f(CW\*(C`RELATIVE\*(C'\fR options are appropriately enabled. The \f(CW\*(C`INCLUDE\*(C'\fR directive automatically quotes the filename specified, as per \f(CW\*(C`INSERT\*(C'\fR described above. When a variable contains the name of the template for the \f(CW\*(C`INCLUDE\*(C'\fR directive, it should be explicitly prefixed by \f(CW\*(C`$\*(C'\fR or double-quoted .PP .Vb 4 \& [% myheader = \*(Aqmy/misc/header\*(Aq %] \& [% INCLUDE myheader %] # \*(Aqmyheader\*(Aq \& [% INCLUDE $myheader %] # \*(Aqmy/misc/header\*(Aq \& [% INCLUDE "$myheader" %] # \*(Aqmy/misc/header\*(Aq .Ve .PP Any template directives embedded within the file will be processed accordingly. All variables currently defined will be visible and accessible from within the included template. .PP .Vb 4 \& [% title = \*(AqHello World\*(Aq %] \& [% INCLUDE header %] \& <body> \& ... .Ve .PP \&\fIheader\fR: .PP .Vb 2 \& <html> \& <title>[% title %]</title> .Ve .PP output: .PP .Vb 4 \& <html> \& <title>Hello World</title> \& <body> \& ... .Ve .PP Local variable definitions may be specified after the template name, temporarily masking any existing variables. Insignificant whitespace is ignored within directives so you can add variable definitions on the same line, the next line or split across several line with comments interspersed, if you prefer. .PP .Vb 1 \& [% INCLUDE table %] \& \& [% INCLUDE table title="Active Projects" %] \& \& [% INCLUDE table \& title = "Active Projects" \& bgcolor = "#80ff00" # chartreuse \& border = 2 \& %] .Ve .PP The \f(CW\*(C`INCLUDE\*(C'\fR directive localises (i.e. copies) all variables before processing the template. Any changes made within the included template will not affect variables in the including template. .PP .Vb 1 \& [% foo = 10 %] \& \& foo is originally [% foo %] \& [% INCLUDE bar %] \& foo is still [% foo %] \& \& [% BLOCK bar %] \& foo was [% foo %] \& [% foo = 20 %] \& foo is now [% foo %] \& [% END %] .Ve .PP output: .PP .Vb 4 \& foo is originally 10 \& foo was 10 \& foo is now 20 \& foo is still 10 .Ve .PP Technical Note: the localisation of the stash (that is, the process by which variables are copied before an \f(CW\*(C`INCLUDE\*(C'\fR to prevent being overwritten) is only skin deep. The top-level variable namespace (hash) is copied, but no attempt is made to perform a deep-copy of other structures (hashes, arrays, objects, etc.) Therefore, a \f(CW\*(C`foo\*(C'\fR variable referencing a hash will be copied to create a new \f(CW\*(C`foo\*(C'\fR variable but which points to the same hash array. Thus, if you update compound variables (e.g. \f(CW\*(C`foo.bar\*(C'\fR) then you will change the original copy, regardless of any stash localisation. If you're not worried about preserving variable values, or you trust the templates you're including then you might prefer to use the \f(CW\*(C`PROCESS\*(C'\fR directive which is faster by virtue of not performing any localisation. .PP You can specify dotted variables as \*(L"local\*(R" variables to an \f(CW\*(C`INCLUDE\*(C'\fR directive. However, be aware that because of the localisation issues explained above (if you skipped the previous Technical Note above then you might want to go back and read it or skip this section too), the variables might not actually be \&\*(L"local\*(R". If the first element of the variable name already references a hash array then the variable update will affect the original variable. .PP .Vb 4 \& [% foo = { \& bar = \*(AqBaz\*(Aq \& } \& %] \& \& [% INCLUDE somefile foo.bar=\*(AqBoz\*(Aq %] \& \& [% foo.bar %] # Boz .Ve .PP This behaviour can be a little unpredictable (and may well be improved upon in a future version). If you know what you're doing with it and you're sure that the variables in question are defined (nor not) as you expect them to be, then you can rely on this feature to implement some powerful \*(L"global\*(R" data sharing techniques. Otherwise, you might prefer to steer well clear and always pass simple (undotted) variables as parameters to \f(CW\*(C`INCLUDE\*(C'\fR and other similar directives. .PP If you want to process several templates in one go then you can specify each of their names (quoted or unquoted names only, no unquoted \&\f(CW$variables\fR) joined together by \f(CW\*(C`+\*(C'\fR. The \f(CW\*(C`INCLUDE\*(C'\fR directive will then process them in order. .PP .Vb 3 \& [% INCLUDE html/header + "site/$header" + site/menu \& title = "My Groovy Web Site" \& %] .Ve .PP The variable stash is localised once and then the templates specified are processed in order, all within that same variable context. This makes it slightly faster than specifying several separate \f(CW\*(C`INCLUDE\*(C'\fR directives (because you only clone the variable stash once instead of n times), but not quite as \*(L"safe\*(R" because any variable changes in the first file will be visible in the second, third and so on. This might be what you want, of course, but then again, it might not. .SS "\s-1PROCESS\s0" .IX Subsection "PROCESS" The \s-1PROCESS\s0 directive is similar to \f(CW\*(C`INCLUDE\*(C'\fR but does not perform any localisation of variables before processing the template. Any changes made to variables within the included template will be visible in the including template. .PP .Vb 1 \& [% foo = 10 %] \& \& foo is [% foo %] \& [% PROCESS bar %] \& foo is [% foo %] \& \& [% BLOCK bar %] \& [% foo = 20 %] \& changed foo to [% foo %] \& [% END %] .Ve .PP output: .PP .Vb 3 \& foo is 10 \& changed foo to 20 \& foo is 20 .Ve .PP Parameters may be specified in the \f(CW\*(C`PROCESS\*(C'\fR directive, but these too will become visible changes to current variable values. .PP .Vb 6 \& [% foo = 10 %] \& foo is [% foo %] \& [% PROCESS bar \& foo = 20 \& %] \& foo is [% foo %] \& \& [% BLOCK bar %] \& this is bar, foo is [% foo %] \& [% END %] .Ve .PP output: .PP .Vb 3 \& foo is 10 \& this is bar, foo is 20 \& foo is 20 .Ve .PP The \f(CW\*(C`PROCESS\*(C'\fR directive is slightly faster than \f(CW\*(C`INCLUDE\*(C'\fR because it avoids the need to localise (i.e. copy) the variable stash before processing the template. As with \f(CW\*(C`INSERT\*(C'\fR and \f(CW\*(C`INCLUDE\*(C'\fR, the first parameter does not need to be quoted as long as it contains only alphanumeric characters, underscores, periods or forward slashes. A \f(CW\*(C`$\*(C'\fR prefix can be used to explicitly indicate a variable which should be interpolated to provide the template name: .PP .Vb 3 \& [% myheader = \*(Aqmy/misc/header\*(Aq %] \& [% PROCESS myheader %] # \*(Aqmyheader\*(Aq \& [% PROCESS $myheader %] # \*(Aqmy/misc/header\*(Aq .Ve .PP As with \f(CW\*(C`INCLUDE\*(C'\fR, multiple templates can be specified, delimited by \&\f(CW\*(C`+\*(C'\fR, and are processed in order. .PP .Vb 1 \& [% PROCESS html/header + my/header %] .Ve .SS "\s-1WRAPPER\s0" .IX Subsection "WRAPPER" It's not unusual to find yourself adding common headers and footers to pages or sub-sections within a page. Something like this: .PP .Vb 6 \& [% INCLUDE section/header \& title = \*(AqQuantum Mechanics\*(Aq \& %] \& Quantum mechanics is a very interesting subject wish \& should prove easy for the layman to fully comprehend. \& [% INCLUDE section/footer %] \& \& [% INCLUDE section/header \& title = \*(AqDesktop Nuclear Fusion for under $50\*(Aq \& %] \& This describes a simple device which generates significant \& sustainable electrical power from common tap water by process \& of nuclear fusion. \& [% INCLUDE section/footer %] .Ve .PP The individual template components being included might look like these: .PP section/header: .PP .Vb 2 \& <p> \& <h2>[% title %]</h2> .Ve .PP section/footer: .PP .Vb 1 \& </p> .Ve .PP The \f(CW\*(C`WRAPPER\*(C'\fR directive provides a way of simplifying this a little. It encloses a block up to a matching \f(CW\*(C`END\*(C'\fR directive, which is first processed to generate some output. This is then passed to the named template file or \&\f(CW\*(C`BLOCK\*(C'\fR as the \f(CW\*(C`content\*(C'\fR variable. .PP .Vb 6 \& [% WRAPPER section \& title = \*(AqQuantum Mechanics\*(Aq \& %] \& Quantum mechanics is a very interesting subject wish \& should prove easy for the layman to fully comprehend. \& [% END %] \& \& [% WRAPPER section \& title = \*(AqDesktop Nuclear Fusion for under $50\*(Aq \& %] \& This describes a simple device which generates significant \& sustainable electrical power from common tap water by process \& of nuclear fusion. \& [% END %] .Ve .PP The single 'section' template can then be defined as: .PP .Vb 4 \& <h2>[% title %]</h2> \& <p> \& [% content %] \& </p> .Ve .PP Like other block directives, it can be used in side-effect notation: .PP .Vb 1 \& [% INSERT legalese.txt WRAPPER big_bold_table %] .Ve .PP It's also possible to specify multiple templates to a \f(CW\*(C`WRAPPER\*(C'\fR directive. The specification order indicates outermost to innermost wrapper templates. For example, given the following template block definitions: .PP .Vb 2 \& [% BLOCK bold %]<b>[% content %]</b>[% END %] \& [% BLOCK italic %]<i>[% content %]</i>[% END %] .Ve .PP the directive .PP .Vb 1 \& [% WRAPPER bold+italic %]Hello World[% END %] .Ve .PP would generate the following output: .PP .Vb 1 \& <b><i>Hello World</i></b> .Ve .SS "\s-1BLOCK\s0" .IX Subsection "BLOCK" The \f(CW\*(C`BLOCK\*(C'\fR...\f(CW\*(C`END\*(C'\fR construct can be used to define template component blocks which can be processed with the \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR and \f(CW\*(C`WRAPPER\*(C'\fR directives. .PP .Vb 6 \& [% BLOCK tabrow %] \& <tr> \& <td>[% name %]<td> \& <td>[% email %]</td> \& </tr> \& [% END %] \& \& <table> \& [% PROCESS tabrow name=\*(AqFred\*(Aq email=\*(Aqfred@nowhere.com\*(Aq %] \& [% PROCESS tabrow name=\*(AqAlan\*(Aq email=\*(Aqalan@nowhere.com\*(Aq %] \& </table> .Ve .PP A \f(CW\*(C`BLOCK\*(C'\fR definition can be used before it is defined, as long as the definition resides in the same file. The block definition itself does not generate any output. .PP .Vb 1 \& [% PROCESS tmpblk %] \& \& [% BLOCK tmpblk %] This is OK [% END %] .Ve .PP You can use an anonymous \f(CW\*(C`BLOCK\*(C'\fR to capture the output of a template fragment. .PP .Vb 8 \& [% julius = BLOCK %] \& And Caesar\*(Aqs spirit, ranging for revenge, \& With Ate by his side come hot from hell, \& Shall in these confines with a monarch\*(Aqs voice \& Cry \*(AqHavoc\*(Aq, and let slip the dogs of war; \& That this foul deed shall smell above the earth \& With carrion men, groaning for burial. \& [% END %] .Ve .PP Like a named block, it can contain any other template directives which are processed when the block is defined. The output generated by the block is then assigned to the variable \f(CW\*(C`julius\*(C'\fR. .PP Anonymous \f(CW\*(C`BLOCK\*(C'\fRs can also be used to define block macros. The enclosing block is processed each time the macro is called. .PP .Vb 3 \& [% MACRO locate BLOCK %] \& The [% animal %] sat on the [% place %]. \& [% END %] \& \& [% locate(animal=\*(Aqcat\*(Aq, place=\*(Aqmat\*(Aq) %] # The cat sat on the mat \& [% locate(animal=\*(Aqdog\*(Aq, place=\*(Aqlog\*(Aq) %] # The dog sat on the log .Ve .SH "Conditional Processing" .IX Header "Conditional Processing" .SS "\s-1IF / UNLESS / ELSIF / ELSE\s0" .IX Subsection "IF / UNLESS / ELSIF / ELSE" The \f(CW\*(C`IF\*(C'\fR and \f(CW\*(C`UNLESS\*(C'\fR directives can be used to process or ignore a block based on some run-time condition. .PP .Vb 3 \& [% IF frames %] \& [% INCLUDE frameset %] \& [% END %] \& \& [% UNLESS text_mode %] \& [% INCLUDE biglogo %] \& [% END %] .Ve .PP Multiple conditions may be joined with \f(CW\*(C`ELSIF\*(C'\fR and/or \f(CW\*(C`ELSE\*(C'\fR blocks. .PP .Vb 9 \& [% IF age < 10 %] \& Hello [% name %], does your mother know you\*(Aqre \& using her AOL account? \& [% ELSIF age < 18 %] \& Sorry, you\*(Aqre not old enough to enter \& (and too dumb to lie about your age) \& [% ELSE %] \& Welcome [% name %]. \& [% END %] .Ve .PP The following conditional and boolean operators may be used: .PP .Vb 1 \& == != < <= > >= && || ! and or not .Ve .PP Conditions may be arbitrarily complex and are evaluated with the same precedence as in Perl. Parenthesis may be used to explicitly determine evaluation order. .PP .Vb 6 \& # ridiculously contrived complex example \& [% IF (name == \*(Aqadmin\*(Aq || uid <= 0) && mode == \*(Aqdebug\*(Aq %] \& I\*(Aqm confused. \& [% ELSIF more > less %] \& That\*(Aqs more or less correct. \& [% END %] .Ve .PP The \f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`not\*(C'\fR operator are provided as aliases for \&\f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR and \f(CW\*(C`!\*(C'\fR, respectively. Unlike Perl, which treats \&\f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`not\*(C'\fR as separate, lower-precedence versions of the other operators, the Template Toolkit performs a straightforward substitution of \f(CW\*(C`and\*(C'\fR for \f(CW\*(C`&&\*(C'\fR, and so on. That means that \f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`not\*(C'\fR have the same operator precedence as \f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR and \f(CW\*(C`!\*(C'\fR. .SS "\s-1SWITCH / CASE\s0" .IX Subsection "SWITCH / CASE" The \f(CW\*(C`SWITCH\*(C'\fR / \f(CW\*(C`CASE\*(C'\fR construct can be used to perform a multi-way conditional test. The \f(CW\*(C`SWITCH\*(C'\fR directive expects an expression which is first evaluated and then compared against each \s-1CASE\s0 statement in turn. Each \f(CW\*(C`CASE\*(C'\fR directive should contain a single value or a list of values which should match. \f(CW\*(C`CASE\*(C'\fR may also be left blank or written as \&\f(CW\*(C`[% CASE DEFAULT %]\*(C'\fR to specify a default match. Only one \f(CW\*(C`CASE\*(C'\fR matches, there is no drop-through between \f(CW\*(C`CASE\*(C'\fR statements. .PP .Vb 10 \& [% SWITCH myvar %] \& [% CASE \*(Aqvalue1\*(Aq %] \& ... \& [% CASE [\*(Aqvalue2\*(Aq, \*(Aqvalue3\*(Aq] %] # multiple values \& ... \& [% CASE myhash.keys %] # ditto \& ... \& [% CASE %] # default \& ... \& [% END %] .Ve .SH "Loop Processing" .IX Header "Loop Processing" .SS "\s-1FOREACH\s0" .IX Subsection "FOREACH" The \f(CW\*(C`FOREACH\*(C'\fR directive will iterate through the items in a list, processing the enclosed block for each one. .PP .Vb 3 \& [% foo = \*(AqFoo\*(Aq \& items = [ \*(Aqone\*(Aq, \*(Aqtwo\*(Aq, \*(Aqthree\*(Aq ] \& %] \& \& Things: \& [% FOREACH thing IN [ foo \*(AqBar\*(Aq "$foo Baz" ] %] \& * [% thing %] \& [% END %] \& \& Items: \& [% FOREACH i IN items %] \& * [% i %] \& [% END %] \& \& Stuff: \& [% stuff = [ foo "$foo Bar" ] %] \& [% FOREACH s IN stuff %] \& * [% s %] \& [% END %] .Ve .PP output: .PP .Vb 4 \& Things: \& * Foo \& * Bar \& * Foo Baz \& \& Items: \& * one \& * two \& * three \& \& Stuff: \& * Foo \& * Foo Bar .Ve .PP You can use also use \f(CW\*(C`=\*(C'\fR instead of \f(CW\*(C`IN\*(C'\fR if you prefer. .PP .Vb 1 \& [% FOREACH i = items %] .Ve .PP When the \f(CW\*(C`FOREACH\*(C'\fR directive is used without specifying a target variable, any iterated values which are hash references will be automatically imported. .PP .Vb 6 \& [% userlist = [ \& { id => \*(Aqtom\*(Aq, name => \*(AqThomas\*(Aq }, \& { id => \*(Aqdick\*(Aq, name => \*(AqRichard\*(Aq }, \& { id => \*(Aqlarry\*(Aq, name => \*(AqLawrence\*(Aq }, \& ] \& %] \& \& [% FOREACH user IN userlist %] \& [% user.id %] [% user.name %] \& [% END %] .Ve .PP short form: .PP .Vb 3 \& [% FOREACH userlist %] \& [% id %] [% name %] \& [% END %] .Ve .PP Note that this particular usage creates a localised variable context to prevent the imported hash keys from overwriting any existing variables. The imported definitions and any other variables defined in such a \f(CW\*(C`FOREACH\*(C'\fR loop will be lost at the end of the loop, when the previous context and variable values are restored. .PP However, under normal operation, the loop variable remains in scope after the \f(CW\*(C`FOREACH\*(C'\fR loop has ended (caveat: overwriting any variable previously in scope). This is useful as the loop variable is secretly an iterator object (see below) and can be used to analyse the last entry processed by the loop. .PP The \f(CW\*(C`FOREACH\*(C'\fR directive can also be used to iterate through the entries in a hash array. Each entry in the hash is returned in sorted order (based on the key) as a hash array containing 'key' and 'value' items. .PP .Vb 6 \& [% users = { \& tom => \*(AqThomas\*(Aq, \& dick => \*(AqRichard\*(Aq, \& larry => \*(AqLawrence\*(Aq, \& } \& %] \& \& [% FOREACH u IN users %] \& * [% u.key %] : [% u.value %] \& [% END %] .Ve .PP Output: .PP .Vb 3 \& * dick : Richard \& * larry : Lawrence \& * tom : Thomas .Ve .PP The \f(CW\*(C`NEXT\*(C'\fR directive starts the next iteration in the \f(CW\*(C`FOREACH\*(C'\fR loop. .PP .Vb 4 \& [% FOREACH user IN userlist %] \& [% NEXT IF user.isguest %] \& Name: [% user.name %] Email: [% user.email %] \& [% END %] .Ve .PP The \f(CW\*(C`LAST\*(C'\fR directive can be used to prematurely exit the loop. \f(CW\*(C`BREAK\*(C'\fR is also provided as an alias for \f(CW\*(C`LAST\*(C'\fR. .PP .Vb 4 \& [% FOREACH match IN results.nsort(\*(Aqscore\*(Aq).reverse %] \& [% LAST IF match.score < 50 %] \& [% match.score %] : [% match.url %] \& [% END %] .Ve .PP The \f(CW\*(C`FOREACH\*(C'\fR directive is implemented using the Template::Iterator module. A reference to the iterator object for a \f(CW\*(C`FOREACH\*(C'\fR directive is implicitly available in the \f(CW\*(C`loop\*(C'\fR variable. The following methods can be called on the \f(CW\*(C`loop\*(C'\fR iterator. .PP .Vb 8 \& size() number of elements in the list \& max() index number of last element (size \- 1) \& index() index of current iteration from 0 to max() \& count() iteration counter from 1 to size() (i.e. index() + 1) \& first() true if the current iteration is the first \& last() true if the current iteration is the last \& prev() return the previous item in the list \& next() return the next item in the list .Ve .PP See Template::Iterator for further details. .PP Example: .PP .Vb 5 \& [% FOREACH item IN [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] \-%] \& [%\- "<ul>\en" IF loop.first %] \& <li>[% loop.count %]/[% loop.size %]: [% item %] \& [%\- "</ul>\en" IF loop.last %] \& [% END %] .Ve .PP Output: .PP .Vb 5 \& <ul> \& <li>1/3: foo \& <li>2/3: bar \& <li>3/3: baz \& </ul> .Ve .PP Nested loops will work as expected, with the \f(CW\*(C`loop\*(C'\fR variable correctly referencing the innermost loop and being restored to any previous value (i.e. an outer loop) at the end of the loop. .PP .Vb 3 \& [% FOREACH group IN grouplist; \& # loop => group iterator \& "Groups:\en" IF loop.first; \& \& FOREACH user IN group.userlist; \& # loop => user iterator \& "$loop.count: $user.name\en"; \& END; \& \& # loop => group iterator \& "End of Groups\en" IF loop.last; \& END \& %] .Ve .PP The \f(CW\*(C`iterator\*(C'\fR plugin can also be used to explicitly create an iterator object. This can be useful within nested loops where you need to keep a reference to the outer iterator within the inner loop. The iterator plugin effectively allows you to create an iterator by a name other than \f(CW\*(C`loop\*(C'\fR. See Template::Plugin::Iterator for further details. .PP .Vb 1 \& [% USE giter = iterator(grouplist) %] \& \& [% FOREACH group IN giter %] \& [% FOREACH user IN group.userlist %] \& user #[% loop.count %] in \& group [% giter.count %] is \& named [% user.name %] \& [% END %] \& [% END %] .Ve .SS "\s-1WHILE\s0" .IX Subsection "WHILE" The \f(CW\*(C`WHILE\*(C'\fR directive can be used to repeatedly process a template block while a conditional expression evaluates true. The expression may be arbitrarily complex as per \f(CW\*(C`IF\*(C'\fR / \f(CW\*(C`UNLESS\*(C'\fR. .PP .Vb 4 \& [% WHILE total < 100 %] \& ... \& [% total = calculate_new_total %] \& [% END %] .Ve .PP An assignment can be enclosed in parenthesis to evaluate the assigned value. .PP .Vb 3 \& [% WHILE (user = get_next_user_record) %] \& [% user.name %] \& [% END %] .Ve .PP The \f(CW\*(C`NEXT\*(C'\fR directive can be used to start the next iteration of a \&\f(CW\*(C`WHILE\*(C'\fR loop and \f(CW\*(C`BREAK\*(C'\fR can be used to exit the loop, both as per \f(CW\*(C`FOREACH\*(C'\fR. .PP The Template Toolkit uses a failsafe counter to prevent runaway \f(CW\*(C`WHILE\*(C'\fR loops which would otherwise never terminate. If the loop exceeds 1000 iterations then an \f(CW\*(C`undef\*(C'\fR exception will be thrown, reporting the error: .PP .Vb 1 \& WHILE loop terminated (> 1000 iterations) .Ve .PP The \f(CW$Template::Directive::WHILE_MAX\fR variable controls this behaviour and can be set to a higher value if necessary. .SH "Filters, Plugins, Macros and Perl" .IX Header "Filters, Plugins, Macros and Perl" .SS "\s-1FILTER\s0" .IX Subsection "FILTER" The \f(CW\*(C`FILTER\*(C'\fR directive can be used to post-process the output of a block. A number of standard filters are provided with the Template Toolkit. The \f(CW\*(C`html\*(C'\fR filter, for example, escapes the '<', '>' and '&' characters to prevent them from being interpreted as \s-1HTML\s0 tags or entity reference markers. .PP .Vb 4 \& [% FILTER html %] \& HTML text may have < and > characters embedded \& which you want converted to the correct HTML entities. \& [% END %] .Ve .PP output: .PP .Vb 2 \& HTML text may have < and > characters embedded \& which you want converted to the correct HTML entities. .Ve .PP The \f(CW\*(C`FILTER\*(C'\fR directive can also follow various other non-block directives. For example: .PP .Vb 1 \& [% INCLUDE mytext FILTER html %] .Ve .PP The \f(CW\*(C`|\*(C'\fR character can also be used as an alias for \f(CW\*(C`FILTER\*(C'\fR. .PP .Vb 1 \& [% INCLUDE mytext | html %] .Ve .PP Multiple filters can be chained together and will be called in sequence. .PP .Vb 1 \& [% INCLUDE mytext FILTER html FILTER html_para %] .Ve .PP or .PP .Vb 1 \& [% INCLUDE mytext | html | html_para %] .Ve .PP Filters come in two flavours, known as 'static' or 'dynamic'. A static filter is a simple subroutine which accepts a text string as the only argument and returns the modified text. The \f(CW\*(C`html\*(C'\fR filter is an example of a static filter, implemented as: .PP .Vb 9 \& sub html_filter { \& my $text = shift; \& for ($text) { \& s/&/&/g; \& s/</</g; \& s/>/>/g; \& } \& return $text; \& } .Ve .PP Dynamic filters can accept arguments which are specified when the filter is called from a template. The \f(CW\*(C`repeat\*(C'\fR filter is such an example, accepting a numerical argument which specifies the number of times that the input text should be repeated. .PP .Vb 1 \& [% FILTER repeat(3) %]blah [% END %] .Ve .PP output: .PP .Vb 1 \& blah blah blah .Ve .PP These are implemented as filter 'factories'. The factory subroutine is passed a reference to the current Template::Context object along with any additional arguments specified. It should then return a subroutine reference (e.g. a closure) which implements the filter. The \f(CW\*(C`repeat\*(C'\fR filter factory is implemented like this: .PP .Vb 3 \& sub repeat_filter_factory { \& my ($context, $iter) = @_; \& $iter = 1 unless defined $iter; \& \& return sub { \& my $text = shift; \& $text = \*(Aq\*(Aq unless defined $text; \& return join(\*(Aq\en\*(Aq, $text) x $iter; \& } \& } .Ve .PP The \f(CW\*(C`FILTERS\*(C'\fR option, described in Template::Manual::Config, allows custom filters to be defined when a Template object is instantiated. The \&\fBdefine_filter()\fR method allows further filters to be defined at any time. .PP When using a filter, it is possible to assign an alias to it for further use. This is most useful for dynamic filters that you want to re-use with the same configuration. .PP .Vb 3 \& [% FILTER echo = repeat(2) %] \& Is there anybody out there? \& [% END %] \& \& [% FILTER echo %] \& Mother, should I build a wall? \& [% END %] .Ve .PP Output: .PP .Vb 2 \& Is there anybody out there? \& Is there anybody out there? \& \& Mother, should I build a wall? \& Mother, should I build a wall? .Ve .PP The \f(CW\*(C`FILTER\*(C'\fR directive automatically quotes the name of the filter. As with \f(CW\*(C`INCLUDE\*(C'\fR et al, you can use a variable to provide the name of the filter, prefixed by \f(CW\*(C`$\*(C'\fR. .PP .Vb 4 \& [% myfilter = \*(Aqhtml\*(Aq %] \& [% FILTER $myfilter %] # same as [% FILTER html %] \& ... \& [% END %] .Ve .PP A template variable can also be used to define a static filter subroutine. However, the Template Toolkit will automatically call any subroutine bound to a variable and use the value returned. Thus, the above example could be implemented as: .PP .Vb 3 \& my $vars = { \& myfilter => sub { return \*(Aqhtml\*(Aq }, \& }; .Ve .PP template: .PP .Vb 3 \& [% FILTER $myfilter %] # same as [% FILTER html %] \& ... \& [% END %] .Ve .PP To define a template variable that evaluates to a subroutine reference that can be used by the \f(CW\*(C`FILTER\*(C'\fR directive, you should create a subroutine that, when called automatically by the Template Toolkit, returns another subroutine reference which can then be used to perform the filter operation. Note that only static filters can be implemented in this way. .PP .Vb 3 \& my $vars = { \& myfilter => sub { \e&my_filter_sub }, \& }; \& \& sub my_filter_sub { \& my $text = shift; \& # do something \& return $text; \& } .Ve .PP template: .PP .Vb 3 \& [% FILTER $myfilter %] \& ... \& [% END %] .Ve .PP Alternately, you can bless a subroutine reference into a class (any class will do) to fool the Template Toolkit into thinking it's an object rather than a subroutine. This will then bypass the automatic \&\*(L"call-a-subroutine-to-return-a-value\*(R" magic. .PP .Vb 3 \& my $vars = { \& myfilter => bless(\e&my_filter_sub, \*(Aqanything_you_like\*(Aq), \& }; .Ve .PP template: .PP .Vb 3 \& [% FILTER $myfilter %] \& ... \& [% END %] .Ve .PP Filters bound to template variables remain local to the variable context in which they are defined. That is, if you define a filter in a \f(CW\*(C`PERL\*(C'\fR block within a template that is loaded via \f(CW\*(C`INCLUDE\*(C'\fR, then the filter definition will only exist until the end of that template when the stash is delocalised, restoring the previous variable state. If you want to define a filter which persists for the lifetime of the processor, or define additional dynamic filter factories, then you can call the \&\fBdefine_filter()\fR method on the current Template::Context object. .PP See Template::Manual::Filters for a complete list of available filters, their descriptions and examples of use. .SS "\s-1USE\s0" .IX Subsection "USE" The \f(CW\*(C`USE\*(C'\fR directive can be used to load and initialise \*(L"plugin\*(R" extension modules. .PP .Vb 1 \& [% USE myplugin %] .Ve .PP A plugin is a regular Perl module that conforms to a particular object-oriented interface, allowing it to be loaded into and used automatically by the Template Toolkit. For details of this interface and information on writing plugins, consult Template::Plugin. .PP A number of standard plugins are included with the Template Toolkit (see below and Template::Manual::Plugins). The names of these standard plugins are case insensitive. .PP .Vb 3 \& [% USE CGI %] # => Template::Plugin::CGI \& [% USE Cgi %] # => Template::Plugin::CGI \& [% USE cgi %] # => Template::Plugin::CGI .Ve .PP You can also define further plugins using the \f(CW\*(C`PLUGINS\*(C'\fR option. .PP .Vb 6 \& my $tt = Template\->new({ \& PLUGINS => { \& foo => \*(AqMy::Plugin::Foo\*(Aq, \& bar => \*(AqMy::Plugin::Bar\*(Aq, \& }, \& }); .Ve .PP The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified. .PP .Vb 1 \& [% USE Foo %] # look for \*(AqFoo\*(Aq then \*(Aqfoo\*(Aq .Ve .PP If you define all your \f(CW\*(C`PLUGINS\*(C'\fR with lower case names then they will be located regardless of how the user specifies the name in the \f(CW\*(C`USE\*(C'\fR directive. If, on the other hand, you define your \f(CW\*(C`PLUGINS\*(C'\fR with upper or mixed case names then the name specified in the \f(CW\*(C`USE\*(C'\fR directive must match the case exactly. .PP If the plugin isn't defined in either the standard plugins (\f(CW$Template::Plugins::STD_PLUGINS\fR) or via the \f(CW\*(C`PLUGINS\*(C'\fR option, then the \f(CW\*(C`PLUGIN_BASE\*(C'\fR is searched. .PP In this case the plugin name \fIis\fR case-sensitive. It is appended to each of the \f(CW\*(C`PLUGIN_BASE\*(C'\fR module namespaces in turn (default: \&\f(CW\*(C`Template::Plugin\*(C'\fR) to construct a full module name which it attempts to locate and load. Any periods, '\f(CW\*(C`.\*(C'\fR', in the name will be converted to '\f(CW\*(C`::\*(C'\fR'. .PP .Vb 2 \& [% USE MyPlugin %] # => Template::Plugin::MyPlugin \& [% USE Foo.Bar %] # => Template::Plugin::Foo::Bar .Ve .PP The \f(CW\*(C`LOAD_PERL\*(C'\fR option (disabled by default) provides a further way by which external Perl modules may be loaded. If a regular Perl module (i.e. not a \f(CW\*(C`Template::Plugin::*\*(C'\fR or other module relative to some \&\f(CW\*(C`PLUGIN_BASE\*(C'\fR) supports an object-oriented interface and a \f(CW\*(C`new()\*(C'\fR constructor then it can be loaded and instantiated automatically. The following trivial example shows how the IO::File module might be used. .PP .Vb 1 \& [% USE file = IO.File(\*(Aq/tmp/mydata\*(Aq) %] \& \& [% WHILE (line = file.getline) %] \& <!\-\- [% line %] \-\-> \& [% END %] .Ve .PP Any additional parameters supplied in parenthesis after the plugin name will be also be passed to the \f(CW\*(C`new()\*(C'\fR constructor. A reference to the current Template::Context object is passed as the first parameter. .PP .Vb 1 \& [% USE MyPlugin(\*(Aqfoo\*(Aq, 123) %] .Ve .PP equivalent to: .PP .Vb 1 \& Template::Plugin::MyPlugin\->new($context, \*(Aqfoo\*(Aq, 123); .Ve .PP The only exception to this is when a module is loaded via the \&\f(CW\*(C`LOAD_PERL\*(C'\fR option. In this case the \f(CW$context\fR reference is \fInot\fR passed to the \f(CW\*(C`new()\*(C'\fR constructor. This is based on the assumption that the module is a regular Perl module rather than a Template Toolkit plugin so isn't expecting a context reference and wouldn't know what to do with it anyway. .PP Named parameters may also be specified. These are collated into a hash which is passed by reference as the last parameter to the constructor, as per the general code calling interface. .PP .Vb 1 \& [% USE url(\*(Aq/cgi\-bin/foo\*(Aq, mode=\*(Aqsubmit\*(Aq, debug=1) %] .Ve .PP equivalent to: .PP .Vb 5 \& Template::Plugin::URL\->new( \& $context, \& \*(Aq/cgi\-bin/foo\*(Aq \& { mode => \*(Aqsubmit\*(Aq, debug => 1 } \& ); .Ve .PP The plugin may represent any data type; a simple variable, hash, list or code reference, but in the general case it will be an object reference. Methods can be called on the object (or the relevant members of the specific data type) in the usual way: .PP .Vb 1 \& [% USE table(mydata, rows=3) %] \& \& [% FOREACH row IN table.rows %] \& <tr> \& [% FOREACH item IN row %] \& <td>[% item %]</td> \& [% END %] \& </tr> \& [% END %] .Ve .PP An alternative name may be provided for the plugin by which it can be referenced: .PP .Vb 1 \& [% USE scores = table(myscores, cols=5) %] \& \& [% FOREACH row IN scores.rows %] \& ... \& [% END %] .Ve .PP You can use this approach to create multiple plugin objects with different configurations. This example shows how the format plugin is used to create sub-routines bound to variables for formatting text as per \f(CW\*(C`printf()\*(C'\fR. .PP .Vb 4 \& [% USE bold = format(\*(Aq<b>%s</b>\*(Aq) %] \& [% USE ital = format(\*(Aq<i>%s</i>\*(Aq) %] \& [% bold(\*(AqThis is bold\*(Aq) %] \& [% ital(\*(AqThis is italic\*(Aq) %] .Ve .PP Output: .PP .Vb 2 \& <b>This is bold</b> \& <i>This is italic</i> .Ve .PP This next example shows how the \s-1URL\s0 plugin can be used to build dynamic URLs from a base part and optional query parameters. .PP .Vb 3 \& [% USE mycgi = URL(\*(Aq/cgi\-bin/foo.pl\*(Aq, debug=1) %] \& <a href="[% mycgi %]">... \& <a href="[% mycgi(mode=\*(Aqsubmit\*(Aq) %]"... .Ve .PP Output: .PP .Vb 2 \& <a href="/cgi\-bin/foo.pl?debug=1">... \& <a href="/cgi\-bin/foo.pl?mode=submit&debug=1">... .Ve .PP The \s-1CGI\s0 plugin is an example of one which delegates to another Perl module. In this case, to Lincoln Stein's \f(CW\*(C`CGI\*(C'\fR module. All of the methods provided by the \f(CW\*(C`CGI\*(C'\fR module are available via the plugin. .PP .Vb 8 \& [% USE CGI; \& CGI.start_form; \& CGI.checkbox_group( name = \*(Aqcolours\*(Aq, \& values = [ \*(Aqred\*(Aq \*(Aqgreen\*(Aq \*(Aqblue\*(Aq ] ); \& CGI.popup_menu( name = \*(Aqitems\*(Aq, \& values = [ \*(Aqfoo\*(Aq \*(Aqbar\*(Aq \*(Aqbaz\*(Aq ] ); \& CGI.end_form \& %] .Ve .PP See Template::Manual::Plugins for more information on the plugins distributed with the toolkit or available from \s-1CPAN.\s0 .SS "\s-1MACRO\s0" .IX Subsection "MACRO" The \f(CW\*(C`MACRO\*(C'\fR directive allows you to define a directive or directive block which is then evaluated each time the macro is called. .PP .Vb 1 \& [% MACRO header INCLUDE header %] .Ve .PP Calling the macro as: .PP .Vb 1 \& [% header %] .Ve .PP is then equivalent to: .PP .Vb 1 \& [% INCLUDE header %] .Ve .PP Macros can be passed named parameters when called. These values remain local to the macro. .PP .Vb 1 \& [% header(title=\*(AqHello World\*(Aq) %] .Ve .PP equivalent to: .PP .Vb 1 \& [% INCLUDE header title=\*(AqHello World\*(Aq %] .Ve .PP A \f(CW\*(C`MACRO\*(C'\fR definition may include parameter names. Values passed to the macros are then mapped to these local variables. Other named parameters may follow these. .PP .Vb 3 \& [% MACRO header(title) INCLUDE header %] \& [% header(\*(AqHello World\*(Aq) %] \& [% header(\*(AqHello World\*(Aq, bgcol=\*(Aq#123456\*(Aq) %] .Ve .PP equivalent to: .PP .Vb 2 \& [% INCLUDE header title=\*(AqHello World\*(Aq %] \& [% INCLUDE header title=\*(AqHello World\*(Aq bgcol=\*(Aq#123456\*(Aq %] .Ve .PP Here's another example, defining a macro for display numbers in comma-delimited groups of 3, using the chunk and join virtual method. .PP .Vb 2 \& [% MACRO number(n) GET n.chunk(\-3).join(\*(Aq,\*(Aq) %] \& [% number(1234567) %] # 1,234,567 .Ve .PP A \f(CW\*(C`MACRO\*(C'\fR may precede any directive and must conform to the structure of the directive. .PP .Vb 5 \& [% MACRO header IF frames %] \& [% INCLUDE frames/header %] \& [% ELSE %] \& [% INCLUDE header %] \& [% END %] \& \& [% header %] .Ve .PP A \f(CW\*(C`MACRO\*(C'\fR may also be defined as an anonymous \f(CW\*(C`BLOCK\*(C'\fR. The block will be evaluated each time the macro is called. .PP .Vb 3 \& [% MACRO header BLOCK %] \& ...content... \& [% END %] \& \& [% header %] .Ve .PP If you've got the \f(CW\*(C`EVAL_PERL\*(C'\fR option set, then you can even define a \&\f(CW\*(C`MACRO\*(C'\fR as a \f(CW\*(C`PERL\*(C'\fR block (see below): .PP .Vb 4 \& [% MACRO triple(n) PERL %] \& my $n = $stash\->get(\*(Aqn\*(Aq); \& print $n * 3; \& [% END \-%] .Ve .SS "\s-1PERL\s0" .IX Subsection "PERL" (for the advanced reader) .PP The \f(CW\*(C`PERL\*(C'\fR directive is used to mark the start of a block which contains Perl code for evaluation. The \f(CW\*(C`EVAL_PERL\*(C'\fR option must be enabled for Perl code to be evaluated or a \f(CW\*(C`perl\*(C'\fR exception will be thrown with the message '\f(CW\*(C`EVAL_PERL not set\*(C'\fR'. .PP Perl code is evaluated in the \f(CW\*(C`Template::Perl\*(C'\fR package. The \f(CW$context\fR package variable contains a reference to the current Template::Context object. This can be used to access the functionality of the Template Toolkit to process other templates, load plugins, filters, etc. See Template::Context for further details. .PP .Vb 3 \& [% PERL %] \& print $context\->include(\*(Aqmyfile\*(Aq); \& [% END %] .Ve .PP The \f(CW$stash\fR variable contains a reference to the top-level stash object which manages template variables. Through this, variable values can be retrieved and updated. See Template::Stash for further details. .PP .Vb 4 \& [% PERL %] \& $stash\->set(foo => \*(Aqbar\*(Aq); \& print "foo value: ", $stash\->get(\*(Aqfoo\*(Aq); \& [% END %] .Ve .PP Output: .PP .Vb 1 \& foo value: bar .Ve .PP Output is generated from the \f(CW\*(C`PERL\*(C'\fR block by calling \f(CW\*(C`print()\*(C'\fR. Note that the \f(CW\*(C`Template::Perl::PERLOUT\*(C'\fR handle is selected (tied to an output buffer) instead of \f(CW\*(C`STDOUT\*(C'\fR. .PP .Vb 6 \& [% PERL %] \& print "foo\en"; # OK \& print PERLOUT "bar\en"; # OK, same as above \& print Template::Perl::PERLOUT "baz\en"; # OK, same as above \& print STDOUT "qux\en"; # WRONG! \& [% END %] .Ve .PP The \f(CW\*(C`PERL\*(C'\fR block may contain other template directives. These are processed before the Perl code is evaluated. .PP .Vb 1 \& [% name = \*(AqFred Smith\*(Aq %] \& \& [% PERL %] \& print "[% name %]\en"; \& [% END %] .Ve .PP Thus, the Perl code in the above example is evaluated as: .PP .Vb 1 \& print "Fred Smith\en"; .Ve .PP Exceptions may be thrown from within \f(CW\*(C`PERL\*(C'\fR blocks using \f(CW\*(C`die()\*(C'\fR. They will be correctly caught by enclosing \f(CW\*(C`TRY\*(C'\fR blocks. .PP .Vb 7 \& [% TRY %] \& [% PERL %] \& die "nothing to live for\en"; \& [% END %] \& [% CATCH %] \& error: [% error.info %] \& [% END %] .Ve .PP output: error: nothing to live for .SS "\s-1RAWPERL\s0" .IX Subsection "RAWPERL" (for the very advanced reader) .PP The Template Toolkit parser reads a source template and generates the text of a Perl subroutine as output. It then uses \f(CW\*(C`eval()\*(C'\fR to evaluate it into a subroutine reference. This subroutine is then called to process the template, passing a reference to the current Template::Context object through which the functionality of the Template Toolkit can be accessed. The subroutine reference can be cached, allowing the template to be processed repeatedly without requiring any further parsing. .PP For example, a template such as: .PP .Vb 3 \& [% PROCESS header %] \& The [% animal %] sat on the [% location %] \& [% PROCESS footer %] .Ve .PP is converted into the following Perl subroutine definition: .PP .Vb 5 \& sub { \& my $context = shift; \& my $stash = $context\->stash; \& my $output = \*(Aq\*(Aq; \& my $error; \& \& eval { BLOCK: { \& $output .= $context\->process(\*(Aqheader\*(Aq); \& $output .= "The "; \& $output .= $stash\->get(\*(Aqanimal\*(Aq); \& $output .= " sat on the "; \& $output .= $stash\->get(\*(Aqlocation\*(Aq); \& $output .= $context\->process(\*(Aqfooter\*(Aq); \& $output .= "\en"; \& } }; \& if ($@) { \& $error = $context\->catch($@, \e$output); \& die $error unless $error\->type eq \*(Aqreturn\*(Aq; \& } \& \& return $output; \& } .Ve .PP To examine the Perl code generated, such as in the above example, set the \f(CW$Template::Parser::DEBUG\fR package variable to any true value. You can also set the \f(CW$Template::Directive::PRETTY\fR variable true to have the code formatted in a readable manner for human consumption. The source code for each generated template subroutine will be printed to \&\f(CW\*(C`STDERR\*(C'\fR on compilation (i.e. the first time a template is used). .PP .Vb 2 \& $Template::Parser::DEBUG = 1; \& $Template::Directive::PRETTY = 1; \& \& $template\->process($file, $vars) \& || die $template\->error(), "\en"; .Ve .PP The \f(CW\*(C`PERL\*(C'\fR ... \f(CW\*(C`END\*(C'\fR construct allows Perl code to be embedded into a template when the \f(CW\*(C`EVAL_PERL\*(C'\fR option is set. It is evaluated at \&\*(L"runtime\*(R" using \f(CW\*(C`eval()\*(C'\fR each time the template subroutine is called. This is inherently flexible, but not as efficient as it could be, especially in a persistent server environment where a template may be processed many times. .PP The \f(CW\*(C`RAWPERL\*(C'\fR directive allows you to write Perl code that is integrated directly into the generated Perl subroutine text. It is evaluated once at compile time and is stored in cached form as part of the compiled template subroutine. This makes \f(CW\*(C`RAWPERL\*(C'\fR blocks more efficient than \f(CW\*(C`PERL\*(C'\fR blocks. .PP The downside is that you must code much closer to the metal. For example, in a \&\f(CW\*(C`PERL\*(C'\fR block you can call \fBprint()\fR to generate some output. \f(CW\*(C`RAWPERL\*(C'\fR blocks don't afford such luxury. The code is inserted directly into the generated subroutine text and should conform to the convention of appending to the \f(CW$output\fR variable. .PP .Vb 1 \& [% PROCESS header %] \& \& [% RAWPERL %] \& $output .= "Some output\en"; \& ... \& $output .= "Some more output\en"; \& [% END %] .Ve .PP The critical section of the generated subroutine for this example would then look something like: .PP .Vb 10 \& ... \& eval { BLOCK: { \& $output .= $context\->process(\*(Aqheader\*(Aq); \& $output .= "\en"; \& $output .= "Some output\en"; \& ... \& $output .= "Some more output\en"; \& $output .= "\en"; \& } }; \& ... .Ve .PP As with \f(CW\*(C`PERL\*(C'\fR blocks, the \f(CW$context\fR and \&\f(CW$stash\fR references are pre-defined and available for use within \f(CW\*(C`RAWPERL\*(C'\fR code. .SH "Exception Handling and Flow Control" .IX Header "Exception Handling and Flow Control" .SS "\s-1TRY / THROW / CATCH / FINAL\s0" .IX Subsection "TRY / THROW / CATCH / FINAL" (more advanced material) .PP The Template Toolkit supports fully functional, nested exception handling. The \f(CW\*(C`TRY\*(C'\fR directive introduces an exception handling scope which continues until the matching \f(CW\*(C`END\*(C'\fR directive. Any errors that occur within that block will be caught and can be handled by one of the \f(CW\*(C`CATCH\*(C'\fR blocks defined. .PP .Vb 9 \& [% TRY %] \& ...blah...blah... \& [% CALL somecode %] \& ...etc... \& [% INCLUDE someblock %] \& ...and so on... \& [% CATCH %] \& An error occurred! \& [% END %] .Ve .PP Errors are raised as exceptions (objects of the Template::Exception class) which contain two fields: \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR. The exception \f(CW\*(C`type\*(C'\fR is used to indicate the kind of error that occurred. It is a simple text string which can contain letters, numbers, '\f(CW\*(C`_\*(C'\fR' or '\f(CW\*(C`.\*(C'\fR'. The \f(CW\*(C`info\*(C'\fR field contains an error message indicating what actually went wrong. Within a catch block, the exception object is aliased to the \f(CW\*(C`error\*(C'\fR variable. You can access the \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR fields directly. .PP .Vb 2 \& [% mydsn = \*(Aqdbi:MySQL:foobar\*(Aq %] \& ... \& \& [% TRY %] \& [% USE DBI(mydsn) %] \& [% CATCH %] \& ERROR! Type: [% error.type %] \& Info: [% error.info %] \& [% END %] .Ve .PP output (assuming a non-existent database called '\f(CW\*(C`foobar\*(C'\fR'): .PP .Vb 2 \& ERROR! Type: DBI \& Info: Unknown database "foobar" .Ve .PP The \f(CW\*(C`error\*(C'\fR variable can also be specified by itself and will return a string of the form "\f(CW\*(C`$type error \- $info\*(C'\fR". .PP .Vb 4 \& ... \& [% CATCH %] \& ERROR: [% error %] \& [% END %] .Ve .PP Output: .PP .Vb 1 \& ERROR: DBI error \- Unknown database "foobar" .Ve .PP Each \f(CW\*(C`CATCH\*(C'\fR block may be specified with a particular exception type denoting the kind of error that it should catch. Multiple \f(CW\*(C`CATCH\*(C'\fR blocks can be provided to handle different types of exception that may be thrown in the \f(CW\*(C`TRY\*(C'\fR block. A \f(CW\*(C`CATCH\*(C'\fR block specified without any type, as in the previous example, is a default handler which will catch any otherwise uncaught exceptions. This can also be specified as \&\f(CW\*(C`[% CATCH DEFAULT %]\*(C'\fR. .PP .Vb 11 \& [% TRY %] \& [% INCLUDE myfile %] \& [% USE DBI(mydsn) %] \& [% CALL somecode %] \& [% CATCH file %] \& File Error! [% error.info %] \& [% CATCH DBI %] \& [% INCLUDE database/error.html %] \& [% CATCH %] \& [% error %] \& [% END %] .Ve .PP Remember that you can specify multiple directives within a single tag, each delimited by '\f(CW\*(C`;\*(C'\fR'. So the above example can be written more concisely as: .PP .Vb 12 \& [% TRY; \& INCLUDE myfile; \& USE DBI(mydsn); \& CALL somecode; \& CATCH file; \& "File Error! $error.info"; \& CATCH DBI; \& INCLUDE database/error.html; \& CATCH; \& error; \& END \& %] .Ve .PP The \f(CW\*(C`DBI\*(C'\fR plugin throws exceptions of the \f(CW\*(C`DBI\*(C'\fR type (in case that wasn't already obvious). The other specific exception caught here is of the \f(CW\*(C`file\*(C'\fR type. .PP A \f(CW\*(C`file\*(C'\fR exception is automatically thrown by the Template Toolkit when it can't find a file, or fails to load, parse or process a file that has been requested by an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`INSERT\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive. If \f(CW\*(C`myfile\*(C'\fR can't be found in the example above, the \f(CW\*(C`[% INCLUDE myfile %]\*(C'\fR directive will raise a \f(CW\*(C`file\*(C'\fR exception which is then caught by the \&\f(CW\*(C`[% CATCH file %]\*(C'\fR block. The output generated would be: .PP .Vb 1 \& File Error! myfile: not found .Ve .PP Note that the \f(CW\*(C`DEFAULT\*(C'\fR option (disabled by default) allows you to specify a default file to be used any time a template file can't be found. This will prevent file exceptions from ever being raised when a non-existent file is requested (unless, of course, the \f(CW\*(C`DEFAULT\*(C'\fR file your specify doesn't exist). Errors encountered once the file has been found (i.e. read error, parse error) will be raised as file exceptions as per usual. .PP Uncaught exceptions (i.e. if the \f(CW\*(C`TRY\*(C'\fR block doesn't have a type specific or default \f(CW\*(C`CATCH\*(C'\fR handler) may be caught by enclosing \f(CW\*(C`TRY\*(C'\fR blocks which can be nested indefinitely across multiple templates. If the error isn't caught at any level then processing will stop and the Template \&\fBprocess()\fR method will return a false value to the caller. The relevant Template::Exception object can be retrieved by calling the \fBerror()\fR method. .PP .Vb 11 \& [% TRY %] \& ... \& [% TRY %] \& [% INCLUDE $user.header %] \& [% CATCH file %] \& [% INCLUDE header %] \& [% END %] \& ... \& [% CATCH DBI %] \& [% INCLUDE database/error.html %] \& [% END %] .Ve .PP In this example, the inner \f(CW\*(C`TRY\*(C'\fR block is used to ensure that the first \&\f(CW\*(C`INCLUDE\*(C'\fR directive works as expected. We're using a variable to provide the name of the template we want to include, \f(CW\*(C`user.header\*(C'\fR, and it's possible this contains the name of a non-existent template, or perhaps one containing invalid template directives. If the \f(CW\*(C`INCLUDE\*(C'\fR fails with a \f(CW\*(C`file\*(C'\fR error then we \f(CW\*(C`CATCH\*(C'\fR it in the inner block and \f(CW\*(C`INCLUDE\*(C'\fR the default \f(CW\*(C`header\*(C'\fR file instead. Any \f(CW\*(C`DBI\*(C'\fR errors that occur within the scope of the outer \f(CW\*(C`TRY\*(C'\fR block will be caught in the relevant \f(CW\*(C`CATCH\*(C'\fR block, causing the \f(CW\*(C`database/error.html\*(C'\fR template to be processed. Note that included templates inherit all currently defined template variable so these error files can quite happily access the <error> variable to retrieve information about the currently caught exception. For example, the \f(CW\*(C`database/error.html\*(C'\fR template might look like this: .PP .Vb 2 \& <h2>Database Error</h2> \& A database error has occurred: [% error.info %] .Ve .PP You can also specify a \f(CW\*(C`FINAL\*(C'\fR block. This is always processed regardless of the outcome of the \f(CW\*(C`TRY\*(C'\fR and/or \f(CW\*(C`CATCH\*(C'\fR blocks. If an exception is uncaught then the \f(CW\*(C`FINAL\*(C'\fR block is processed before jumping to the enclosing block or returning to the caller. .PP .Vb 9 \& [% TRY %] \& ... \& [% CATCH this %] \& ... \& [% CATCH that %] \& ... \& [% FINAL %] \& All done! \& [% END %] .Ve .PP The output from the \f(CW\*(C`TRY\*(C'\fR block is left intact up to the point where an exception occurs. For example, this template: .PP .Vb 7 \& [% TRY %] \& This gets printed \& [% THROW food \*(Aqcarrots\*(Aq %] \& This doesn\*(Aqt \& [% CATCH food %] \& culinary delights: [% error.info %] \& [% END %] .Ve .PP generates the following output: .PP .Vb 2 \& This gets printed \& culinary delights: carrots .Ve .PP The \f(CW\*(C`CLEAR\*(C'\fR directive can be used in a \f(CW\*(C`CATCH\*(C'\fR or \f(CW\*(C`FINAL\*(C'\fR block to clear any output created in the \f(CW\*(C`TRY\*(C'\fR block. .PP .Vb 8 \& [% TRY %] \& This gets printed \& [% THROW food \*(Aqcarrots\*(Aq %] \& This doesn\*(Aqt \& [% CATCH food %] \& [% CLEAR %] \& culinary delights: [% error.info %] \& [% END %] .Ve .PP Output: .PP .Vb 1 \& culinary delights: carrots .Ve .PP Exception types are hierarchical, with each level being separated by the familiar dot operator. A \f(CW\*(C`DBI.connect\*(C'\fR exception is a more specific kind of \f(CW\*(C`DBI\*(C'\fR error. Similarly, an \f(CW\*(C`example.error.barf\*(C'\fR is a more specific kind of \f(CW\*(C`example.error\*(C'\fR type which itself is also a \&\f(CW\*(C`example\*(C'\fR error. .PP A \f(CW\*(C`CATCH\*(C'\fR handler that specifies a general exception type (such as \f(CW\*(C`DBI\*(C'\fR or \f(CW\*(C`example.error\*(C'\fR) will also catch more specific types that have the same prefix as long as a more specific handler isn't defined. Note that the order in which \f(CW\*(C`CATCH\*(C'\fR handlers are defined is irrelevant; a more specific handler will always catch an exception in preference to a more generic or default one. .PP .Vb 10 \& [% TRY %] \& ... \& [% CATCH DBI ; \& INCLUDE database/error.html ; \& CATCH DBI.connect ; \& INCLUDE database/connect.html ; \& CATCH ; \& INCLUDE error.html ; \& END \& %] .Ve .PP In this example, a \f(CW\*(C`DBI.connect\*(C'\fR error has it's own handler, a more general \&\f(CW\*(C`DBI\*(C'\fR block is used for all other \f(CW\*(C`DBI\*(C'\fR or \f(CW\*(C`DBI.*\*(C'\fR errors and a default handler catches everything else. .PP Exceptions can be raised in a template using the \f(CW\*(C`THROW\*(C'\fR directive. The first parameter is the exception type which doesn't need to be quoted (but can be, it's the same as \f(CW\*(C`INCLUDE\*(C'\fR) followed by the relevant error message which can be any regular value such as a quoted string, variable, etc. .PP .Vb 3 \& [% THROW food "Missing ingredients: $recipe.error" %] \& [% THROW user.login \*(Aqno user id: please login\*(Aq %] \& [% THROW $myerror.type "My Error: $myerror.info" %] .Ve .PP It's also possible to specify additional positional or named parameters to the \f(CW\*(C`THROW\*(C'\fR directive if you want to pass more than just a simple message back as the error info field. .PP .Vb 1 \& [% THROW food \*(Aqeggs\*(Aq \*(Aqflour\*(Aq msg=\*(AqMissing Ingredients\*(Aq %] .Ve .PP In this case, the error \f(CW\*(C`info\*(C'\fR field will be a hash array containing the named arguments and an \f(CW\*(C`args\*(C'\fR item which contains a list of the positional arguments. .PP .Vb 5 \& type => \*(Aqfood\*(Aq, \& info => { \& msg => \*(AqMissing Ingredients\*(Aq, \& args => [\*(Aqeggs\*(Aq, \*(Aqflour\*(Aq], \& } .Ve .PP In addition to specifying individual positional arguments as \&\f(CW\*(C`[% error.info.args.n %]\*(C'\fR, the \f(CW\*(C`info\*(C'\fR hash contains keys directly pointing to the positional arguments, as a convenient shortcut. .PP .Vb 1 \& [% error.info.0 %] # same as [% error.info.args.0 %] .Ve .PP Exceptions can also be thrown from Perl code which you've bound to template variables, or defined as a plugin or other extension. To raise an exception, call \f(CW\*(C`die()\*(C'\fR passing a reference to a Template::Exception object as the argument. This will then be caught by any enclosing \f(CW\*(C`TRY\*(C'\fR blocks from where the code was called. .PP .Vb 9 \& use Template::Exception; \& ... \& my $vars = { \& foo => sub { \& # ... do something ... \& die Template::Exception\->new(\*(Aqmyerr.naughty\*(Aq, \& \*(AqBad, bad error\*(Aq); \& }, \& }; .Ve .PP Template: .PP .Vb 6 \& [% TRY %] \& [% foo %] \& [% CATCH myerr ; \& "Error: $error" ; \& END \& %] .Ve .PP Output: .PP .Vb 1 \& Error: myerr.naughty error \- Bad, bad error .Ve .PP The \f(CW\*(C`info\*(C'\fR field can also be a reference to another object or data structure, if required. .PP .Vb 4 \& die Template::Exception\->new(\*(Aqmyerror\*(Aq, { \& module => \*(Aqfoo.pl\*(Aq, \& errors => [ \*(Aqbad permissions\*(Aq, \*(Aqnaughty boy\*(Aq ], \& }); .Ve .PP Later, in a template: .PP .Vb 8 \& [% TRY %] \& ... \& [% CATCH myerror %] \& [% error.info.errors.size or \*(Aqno\*(Aq; \& error.info.errors.size == 1 ? \*(Aq error\*(Aq : \*(Aq errors\*(Aq %] \& in [% error.info.module %]: \& [% error.info.errors.join(\*(Aq, \*(Aq) %]. \& [% END %] .Ve .PP Generating the output: .PP .Vb 2 \& 2 errors in foo.pl: \& bad permissions, naughty boy. .Ve .PP You can also call \f(CW\*(C`die()\*(C'\fR with a single string, as is common in much existing Perl code. This will automatically be converted to an exception of the '\f(CW\*(C`undef\*(C'\fR' type (that's the literal string '\f(CW\*(C`undef\*(C'\fR', not the undefined value). If the string isn't terminated with a newline then Perl will append the familiar \f(CW" at $file line $line"\fR message. .PP .Vb 4 \& sub foo { \& # ... do something ... \& die "I\*(Aqm sorry, Dave, I can\*(Aqt do that\en"; \& } .Ve .PP If you're writing a plugin, or some extension code that has the current Template::Context in scope (you can safely skip this section if this means nothing to you) then you can also raise an exception by calling the context \&\fBthrow()\fR method. You can pass it an Template::Exception object reference, a pair of \f(CW\*(C`($type, $info)\*(C'\fR parameters or just an \f(CW$info\fR string to create an exception of '\f(CW\*(C`undef\*(C'\fR' type. .PP .Vb 3 \& $context\->throw($e); # exception object \& $context\->throw(\*(AqDenied\*(Aq); # \*(Aqundef\*(Aq type \& $context\->throw(\*(Aquser.passwd\*(Aq, \*(AqBad Password\*(Aq); .Ve .SS "\s-1NEXT\s0" .IX Subsection "NEXT" The \f(CW\*(C`NEXT\*(C'\fR directive can be used to start the next iteration of a \f(CW\*(C`FOREACH\*(C'\fR or \f(CW\*(C`WHILE\*(C'\fR loop. .PP .Vb 4 \& [% FOREACH user IN users %] \& [% NEXT IF user.isguest %] \& Name: [% user.name %] Email: [% user.email %] \& [% END %] .Ve .SS "\s-1LAST\s0" .IX Subsection "LAST" The \f(CW\*(C`LAST\*(C'\fR directive can be used to prematurely exit a \f(CW\*(C`FOREACH\*(C'\fR or \f(CW\*(C`WHILE\*(C'\fR loop. .PP .Vb 4 \& [% FOREACH user IN users %] \& Name: [% user.name %] Email: [% user.email %] \& [% LAST IF some.condition %] \& [% END %] .Ve .PP \&\f(CW\*(C`BREAK\*(C'\fR can also be used as an alias for \f(CW\*(C`LAST\*(C'\fR. .SS "\s-1RETURN\s0" .IX Subsection "RETURN" The \f(CW\*(C`RETURN\*(C'\fR directive can be used to stop processing the current template and return to the template from which it was called, resuming processing at the point immediately after the \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive. If there is no enclosing template then the Template \&\fBprocess()\fR method will return to the calling code with a true value. .PP .Vb 3 \& Before \& [% INCLUDE half_wit %] \& After \& \& [% BLOCK half_wit %] \& This is just half... \& [% RETURN %] \& ...a complete block \& [% END %] .Ve .PP Output: .PP .Vb 3 \& Before \& This is just half... \& After .Ve .SS "\s-1STOP\s0" .IX Subsection "STOP" The \f(CW\*(C`STOP\*(C'\fR directive can be used to indicate that the processor should stop gracefully without processing any more of the template document. This is a planned stop and the Template \fBprocess()\fR method will return a \fBtrue\fR value to the caller. This indicates that the template was processed successfully according to the directives within it. .PP .Vb 4 \& [% IF something.terrible.happened %] \& [% INCLUDE fatal/error.html %] \& [% STOP %] \& [% END %] \& \& [% TRY %] \& [% USE DBI(mydsn) %] \& ... \& [% CATCH DBI.connect %] \& <h1>Cannot connect to the database: [% error.info %]</h1> \& <p> \& We apologise for the inconvenience. \& </p> \& [% INCLUDE footer %] \& [% STOP %] \& [% END %] .Ve .SS "\s-1CLEAR\s0" .IX Subsection "CLEAR" The \f(CW\*(C`CLEAR\*(C'\fR directive can be used to clear the output buffer for the current enclosing block. It is most commonly used to clear the output generated from a \f(CW\*(C`TRY\*(C'\fR block up to the point where the error occurred. .PP .Vb 8 \& [% TRY %] \& blah blah blah # this is normally left intact \& [% THROW some \*(Aqerror\*(Aq %] # up to the point of error \& ... \& [% CATCH %] \& [% CLEAR %] # clear the TRY output \& [% error %] # print error string \& [% END %] .Ve .SH "Miscellaneous" .IX Header "Miscellaneous" .SS "\s-1META\s0" .IX Subsection "META" The \f(CW\*(C`META\*(C'\fR directive allows simple metadata items to be defined within a template. These are evaluated when the template is parsed and as such may only contain simple values (e.g. it's not possible to interpolate other variables values into \f(CW\*(C`META\*(C'\fR variables). .PP .Vb 5 \& [% META \& title = \*(AqThe Cat in the Hat\*(Aq \& author = \*(AqDr. Seuss\*(Aq \& version = 1.23 \& %] .Ve .PP The \f(CW\*(C`template\*(C'\fR variable contains a reference to the main template being processed. These metadata items may be retrieved as attributes of the template. .PP .Vb 2 \& <h1>[% template.title %]</h1> \& <h2>[% template.author %]</h2> .Ve .PP The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`modtime\*(C'\fR metadata items are automatically defined for each template to contain its name and modification time in seconds since the epoch. .PP .Vb 4 \& [% USE date %] # use Date plugin to format time \& ... \& [% template.name %] last modified \& at [% date.format(template.modtime) %] .Ve .PP The \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR options allow common headers and footers to be added to all templates. The \f(CW\*(C`template\*(C'\fR reference is correctly defined when these templates are processed, allowing headers and footers to reference metadata items from the main template. .PP .Vb 4 \& $template = Template\->new({ \& PRE_PROCESS => \*(Aqheader\*(Aq, \& POST_PROCESS => \*(Aqfooter\*(Aq, \& }); \& \& $template\->process(\*(Aqcat_in_hat\*(Aq); .Ve .PP header: .PP .Vb 5 \& <html> \& <head> \& <title>[% template.title %]</title> \& </head> \& <body> .Ve .PP cat_in_hat: .PP .Vb 6 \& [% META \& title = \*(AqThe Cat in the Hat\*(Aq \& author = \*(AqDr. Seuss\*(Aq \& version = 1.23 \& year = 2000 \& %] \& \& The cat in the hat sat on the mat. .Ve .PP footer: .PP .Vb 4 \& <hr> \& © [% template.year %] [% template.author %] \& </body> \& </html> .Ve .PP The output generated from the above example is: .PP .Vb 10 \& <html> \& <head> \& <title>The Cat in the Hat</title> \& </head> \& <body> \& The cat in the hat sat on the mat. \& <hr> \& © 2000 Dr. Seuss \& </body> \& </html> .Ve .SS "\s-1TAGS\s0" .IX Subsection "TAGS" The \f(CW\*(C`TAGS\*(C'\fR directive can be used to set the \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR values on a per-template file basis. .PP .Vb 1 \& [% TAGS <+ +> %] \& \& <+ INCLUDE header +> .Ve .PP The \s-1TAGS\s0 directive may also be used to set a named \f(CW\*(C`TAG_STYLE\*(C'\fR .PP .Vb 2 \& [% TAGS html %] \& <!\-\- INCLUDE header \-\-> .Ve .PP See the \s-1TAGS\s0 and \s-1TAG_STYLE\s0 configuration options for further details. .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" The \f(CW\*(C`DEBUG\*(C'\fR directive can be used to enable or disable directive debug messages within a template. The \f(CW\*(C`DEBUG\*(C'\fR configuration option must be set to include \f(CW\*(C`DEBUG_DIRS\*(C'\fR for the \f(CW\*(C`DEBUG\*(C'\fR directives to have any effect. If \f(CW\*(C`DEBUG_DIRS\*(C'\fR is not set then the parser will automatically ignore and remove any \f(CW\*(C`DEBUG\*(C'\fR directives. .PP The \f(CW\*(C`DEBUG\*(C'\fR directive can be used with an \f(CW\*(C`on\*(C'\fR or \f(CW\*(C`off\*(C'\fR parameter to enable or disable directive debugging messages from that point forward. When enabled, the output of each directive in the generated output will be prefixed by a comment indicate the file, line and original directive text. .PP .Vb 4 \& [% DEBUG on %] \& directive debugging is on (assuming DEBUG option is set true) \& [% DEBUG off %] \& directive debugging is off .Ve .PP The \f(CW\*(C`format\*(C'\fR parameter can be used to change the format of the debugging message. .PP .Vb 1 \& [% DEBUG format \*(Aq<!\-\- $file line $line : [% $text %] \-\->\*(Aq %] .Ve PK � �[�I��'* '* man3/Template::View.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::View 3" .TH Template::View 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::View \- customised view of a template processing context .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 7 \& # define a view \& [% VIEW view \& # some standard args \& prefix => \*(Aqmy_\*(Aq, \& suffix => \*(Aq.tt2\*(Aq, \& notfound => \*(Aqno_such_file\*(Aq \& ... \& \& # any other data \& title => \*(AqMy View title\*(Aq \& other_item => \*(AqJoe Random Data\*(Aq \& ... \& %] \& # add new data definitions, via \*(Aqmy\*(Aq self reference \& [% my.author = "$abw.name <$abw.email>" %] \& [% my.copy = "© Copyright 2000 $my.author" %] \& \& # define a local block \& [% BLOCK header %] \& This is the header block, title: [% title or my.title %] \& [% END %] \& \& [% END %] \& \& # access data items for view \& [% view.title %] \& [% view.other_item %] \& \& # access blocks directly (\*(Aqinclude_naked\*(Aq option, set by default) \& [% view.header %] \& [% view.header(title => \*(AqNew Title\*(Aq) %] \& \& # non\-local templates have prefix/suffix attached \& [% view.footer %] # => [% INCLUDE my_footer.tt2 %] \& \& # more verbose form of block access \& [% view.include( \*(Aqheader\*(Aq, title => \*(AqThe Header Title\*(Aq ) %] \& [% view.include_header( title => \*(AqThe Header Title\*(Aq ) %] \& \& # very short form of above (\*(Aqinclude_naked\*(Aq option, set by default) \& [% view.header( title => \*(AqThe Header Title\*(Aq ) %] \& \& # non\-local templates have prefix/suffix attached \& [% view.footer %] # => [% INCLUDE my_footer.tt2 %] \& \& # fallback on the \*(Aqnotfound\*(Aq template (\*(Aqmy_no_such_file.tt2\*(Aq) \& # if template not found \& [% view.include(\*(Aqmissing\*(Aq) %] \& [% view.include_missing %] \& [% view.missing %] \& \& # print() includes a template relevant to argument type \& [% view.print("some text") %] # type=TEXT, template=\*(Aqtext\*(Aq \& \& [% BLOCK my_text.tt2 %] # \*(Aqtext\*(Aq with prefix/suffix \& Text: [% item %] \& [% END %] \& \& # now print() a hash ref, mapped to \*(Aqhash\*(Aq template \& [% view.print(some_hash_ref) %] # type=HASH, template=\*(Aqhash\*(Aq \& \& [% BLOCK my_hash.tt2 %] # \*(Aqhash\*(Aq with prefix/suffix \& hash keys: [% item.keys.sort.join(\*(Aq, \*(Aq) \& [% END %] \& \& # now print() a list ref, mapped to \*(Aqlist\*(Aq template \& [% view.print(my_list_ref) %] # type=ARRAY, template=\*(Aqlist\*(Aq \& \& [% BLOCK my_list.tt2 %] # \*(Aqlist\*(Aq with prefix/suffix \& list: [% item.join(\*(Aq, \*(Aq) %] \& [% END %] \& \& # print() maps \*(AqMy::Object\*(Aq to \*(AqMy_Object\*(Aq \& [% view.print(myobj) %] \& \& [% BLOCK my_My_Object.tt2 %] \& [% item.this %], [% item.that %] \& [% END %] \& \& # update mapping table \& [% view.map.ARRAY = \*(Aqmy_list_template\*(Aq %] \& [% view.map.TEXT = \*(Aqmy_text_block\*(Aq %] \& \& \& # change prefix, suffix, item name, etc. \& [% view.prefix = \*(Aqyour_\*(Aq %] \& [% view.default = \*(Aqanyobj\*(Aq %] \& ... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1TODO\s0 .SH "METHODS" .IX Header "METHODS" .SS "new($context, \e%config)" .IX Subsection "new($context, %config)" Creates a new Template::View presenting a custom view of the specified \&\f(CW$context\fR object. .PP A reference to a hash array of configuration options may be passed as the second argument. .IP "prefix" 4 .IX Item "prefix" Prefix added to all template names. .Sp .Vb 2 \& [% USE view(prefix => \*(Aqmy_\*(Aq) %] \& [% view.view(\*(Aqfoo\*(Aq, a => 20) %] # => my_foo .Ve .IP "suffix" 4 .IX Item "suffix" Suffix added to all template names. .Sp .Vb 2 \& [% USE view(suffix => \*(Aq.tt2\*(Aq) %] \& [% view.view(\*(Aqfoo\*(Aq, a => 20) %] # => foo.tt2 .Ve .IP "map" 4 .IX Item "map" Hash array mapping reference types to template names. The \fBprint()\fR method uses this to determine which template to use to present any particular item. The \s-1TEXT, HASH\s0 and \s-1ARRAY\s0 items default to 'test', \&'hash' and 'list' appropriately. .Sp .Vb 3 \& [% USE view(map => { ARRAY => \*(Aqmy_list\*(Aq, \& HASH => \*(Aqyour_hash\*(Aq, \& My::Foo => \*(Aqmy_foo\*(Aq, } ) %] \& \& [% view.print(some_text) %] # => text \& [% view.print(a_list) %] # => my_list \& [% view.print(a_hash) %] # => your_hash \& [% view.print(a_foo) %] # => my_foo \& \& [% BLOCK text %] \& Text: [% item %] \& [% END %] \& \& [% BLOCK my_list %] \& list: [% item.join(\*(Aq, \*(Aq) %] \& [% END %] \& \& [% BLOCK your_hash %] \& hash keys: [% item.keys.sort.join(\*(Aq, \*(Aq) \& [% END %] \& \& [% BLOCK my_foo %] \& Foo: [% item.this %], [% item.that %] \& [% END %] .Ve .IP "method" 4 .IX Item "method" Name of a method which objects passed to \fBprint()\fR may provide for presenting themselves to the view. If a specific map entry can't be found for an object reference and it supports the method (default: 'present') then the method will be called, passing the view as an argument. The object can then make callbacks against the view to present itself. .Sp .Vb 1 \& package Foo; \& \& sub present { \& my ($self, $view) = @_; \& return "a regular view of a Foo\en"; \& } \& \& sub debug { \& my ($self, $view) = @_; \& return "a debug view of a Foo\en"; \& } .Ve .Sp In a template: .Sp .Vb 2 \& [% USE view %] \& [% view.print(my_foo_object) %] # a regular view of a Foo \& \& [% USE view(method => \*(Aqdebug\*(Aq) %] \& [% view.print(my_foo_object) %] # a debug view of a Foo .Ve .IP "default" 4 .IX Item "default" Default template to use if no specific map entry is found for an item. .Sp .Vb 1 \& [% USE view(default => \*(Aqmy_object\*(Aq) %] \& \& [% view.print(objref) %] # => my_object .Ve .Sp If no map entry or default is provided then the view will attempt to construct a template name from the object class, substituting any sequence of non-word characters to single underscores, e.g. .Sp .Vb 2 \& # \*(Aqfubar\*(Aq is an object of class Foo::Bar \& [% view.print(fubar) %] # => Foo_Bar .Ve .Sp Any current prefix and suffix will be added to both the default template name and any name constructed from the object class. .IP "notfound" 4 .IX Item "notfound" Fallback template to use if any other isn't found. .IP "item" 4 .IX Item "item" Name of the template variable to which the \fBprint()\fR method assigns the current item. Defaults to 'item'. .Sp .Vb 5 \& [% USE view %] \& [% BLOCK list %] \& [% item.join(\*(Aq, \*(Aq) %] \& [% END %] \& [% view.print(a_list) %] \& \& [% USE view(item => \*(Aqthing\*(Aq) %] \& [% BLOCK list %] \& [% thing.join(\*(Aq, \*(Aq) %] \& [% END %] \& [% view.print(a_list) %] .Ve .IP "view_prefix" 4 .IX Item "view_prefix" Prefix of methods which should be mapped to \fBview()\fR by \s-1AUTOLOAD.\s0 Defaults to 'view_'. .Sp .Vb 2 \& [% USE view %] \& [% view.view_header() %] # => view(\*(Aqheader\*(Aq) \& \& [% USE view(view_prefix => \*(Aqshow_me_the_\*(Aq %] \& [% view.show_me_the_header() %] # => view(\*(Aqheader\*(Aq) .Ve .IP "view_naked" 4 .IX Item "view_naked" Flag to indicate if any attempt should be made to map method names to template names where they don't match the view_prefix. Defaults to 0. .Sp .Vb 1 \& [% USE view(view_naked => 1) %] \& \& [% view.header() %] # => view(\*(Aqheader\*(Aq) .Ve .ie n .SS "print( $obj1, $obj2, ... \e%config)" .el .SS "print( \f(CW$obj1\fP, \f(CW$obj2\fP, ... \e%config)" .IX Subsection "print( $obj1, $obj2, ... %config)" \&\s-1TODO\s0 .ie n .SS "view( $template, \e%vars, \e%config );" .el .SS "view( \f(CW$template\fP, \e%vars, \e%config );" .IX Subsection "view( $template, %vars, %config );" \&\s-1TODO\s0 .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2000\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Plugin PK � �[svC�1 �1 ! man3/Template::Manual::Syntax.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Manual::Syntax 3" .TH Template::Manual::Syntax 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Manual::Syntax \- Directive syntax, structure and semantics .SH "Tag Styles" .IX Header "Tag Styles" Template directives are embedded between start and end markers tags. By default these tag markers are \f(CW\*(C`[%\*(C'\fR and \f(CW\*(C`%]\*(C'\fR. .PP .Vb 1 \& [% PROCESS header %] \& \& <h1>Hello World!</h1> \& <a href="[% page.next %]"><img src="[% icon.next %].gif"></a> \& \& [% PROCESS footer %] .Ve .PP You can change the tag characters using the \f(CW\*(C`START_TAG\*(C'\fR, \f(CW\*(C`END_TAG\*(C'\fR and \&\f(CW\*(C`TAG_STYLE\*(C'\fR configuration options. You can also use the \f(CW\*(C`TAGS\*(C'\fR directive to define a new tag style for the current template file. .PP You can also set the \f(CW\*(C`INTERPOLATE\*(C'\fR option to allow simple variable references to be embedded directly in templates, prefixed by a \f(CW\*(C`$\*(C'\fR. .PP .Vb 3 \& # INTERPOLATE = 0 \& <td>[% name %]</td> \& <td>[% email %]</td> \& \& # INTERPOLATE = 1 \& <td>$name</td> \& <td>$email</td> .Ve .PP Directives may be embedded anywhere in a line of text and can be split across several lines. Insignificant whitespace is generally ignored within the directive. .PP .Vb 4 \& [% INCLUDE header \& title = \*(AqHello World\*(Aq \& bgcol = \*(Aq#ffffff\*(Aq \& %] \& \& [%INCLUDE menu align=\*(Aqright\*(Aq%] \& \& Name: [% name %] ([%id%]) .Ve .SH "Outline Tags" .IX Header "Outline Tags" As of version 2.26, the Template Toolkit supports \*(L"outline\*(R" tags. These have a designated marker at the start of a line (\f(CW\*(C`%%\*(C'\fR by default) and continue to the end of a line. The newline character at the end of the line is discarded (aka \*(L"chomped\*(R"). .PP So rather than writing something like this: .PP .Vb 7 \& [% IF some.list.size \-%] \& <ul> \& [% FOREACH item IN some.list \-%] \& <li>[% item.html %]</li> \& [% END \-%] \& </ul> \& [% END \-%] .Ve .PP You can write it like this instead: .PP .Vb 7 \& %% IF some.list.size \& <ul> \& %% FOREACH item IN some.list \& <li>[% item.html %]</li> \& %% END \& </ul> \& %% END .Ve .PP Outline tags aren't enabled by default. There are a numbers of ways you can enable them. The first is to use the \f(CW\*(C`TAGS\*(C'\fR directive to set the tag style to \f(CW\*(C`outline\*(C'\fR in any templates where you want to use them. This will enable outline tags from that point on. .PP .Vb 2 \& [% TAGS outline \-%] \& %% INCLUDE header .Ve .PP You can set the \f(CW\*(C`TAGS\*(C'\fR back to the \f(CW\*(C`default\*(C'\fR value at some point later in the template if you want to disable them: .PP .Vb 1 \& [% TAGS default \-%] .Ve .PP You can set the \f(CW\*(C`TAG_STYLE\*(C'\fR configuration option if you want then enabled in all templates by default. You can always use the \f(CW\*(C`[% TAGS default %]\*(C'\fR directive to disable them in any templates or parts of templates if necessary. .PP .Vb 3 \& my $tt = Template\->new({ \& TAG_STYLE => \*(Aqoutline\*(Aq, \& }); .Ve .PP The \f(CW\*(C`OUTLINE_TAG\*(C'\fR option allows you to set the outline tag marker to something else if you're not a fan of percent signs. Setting this option will automatically enable outline tags. .PP .Vb 3 \& my $tt = Template\->new({ \& OUTLINE_TAG => \*(Aq>>\*(Aq, \& }); .Ve .PP You can also use the \f(CW\*(C`TAGS\*(C'\fR directive to define your own custom tags (start, end and now optionally, outline) for a template or part of a template. .PP .Vb 3 \& [% TAGS <* *> >> %] \& >> INCLUDE header # outline tag \& Hello <* name *> # inline tag .Ve .PP If you only specify a start and end tag then outline tags will be disabled. .PP .Vb 1 \& [% TAGS <* *> %] # no outline tags .Ve .SH "Comments" .IX Header "Comments" The \f(CW\*(C`#\*(C'\fR character is used to indicate comments within a directive. When placed immediately inside the opening directive tag, it causes the entire directive to be ignored. .PP .Vb 3 \& [%# this entire directive is ignored no \& matter how many lines it wraps onto \& %] .Ve .PP In any other position, it causes the remainder of the current line to be treated as a comment. .PP .Vb 4 \& [% # this is a comment \& theta = 20 # so is this \& rho = 30 # <aol>me too!</aol> \& %] .Ve .SH "Chomping Whitespace" .IX Header "Chomping Whitespace" You can add \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`+\*(C'\fR to the immediate start or end of a directive tag to control the whitespace chomping options. See the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \&\f(CW\*(C`POST_CHOMP\*(C'\fR options for further details. .PP .Vb 3 \& [% BLOCK foo \-%] # remove trailing newline \& This is block foo \& [%\- END %] # remove leading newline .Ve .SH "Implicit Directives: GET and SET" .IX Header "Implicit Directives: GET and SET" The simplest directives are \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`SET\*(C'\fR which retrieve and update variable values respectively. The \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`SET\*(C'\fR keywords are actually optional as the parser is smart enough to see them for what they really are (but note the caveat below on using side-effect notation). Thus, you'll generally see: .PP .Vb 2 \& [% SET foo = 10 %] \& [% GET foo %] .Ve .PP written as: .PP .Vb 2 \& [% foo = 10 %] \& [% foo %] .Ve .PP You can also express simple logical statements as implicit \f(CW\*(C`GET\*(C'\fR directives: .PP .Vb 1 \& [% title or template.title or \*(AqDefault Title\*(Aq %] \& \& [% mode == \*(Aqgraphics\*(Aq ? "Graphics Mode Enabled" : "Text Mode" %] .Ve .PP All other directives should start with a keyword specified in \s-1UPPER CASE\s0 (but see the \f(CW\*(C`ANYCASE\*(C'\fR option). All directives keywords are in \&\s-1UPPER CASE\s0 to make them visually distinctive and to distinguish them from variables of the same name but different case. It is perfectly valid, for example, to define a variable called \f(CW\*(C`stop\*(C'\fR which is entirely separate from the \f(CW\*(C`STOP\*(C'\fR directive. .PP .Vb 1 \& [% stop = \*(AqClackett Lane Bus Depot\*(Aq %] \& \& The bus will next stop at [% stop %] # variable \& \& [% STOP %] # directive .Ve .SH "Block Directives" .IX Header "Block Directives" Directives such as \f(CW\*(C`FOREACH\*(C'\fR, \f(CW\*(C`WHILE\*(C'\fR, \f(CW\*(C`BLOCK\*(C'\fR, \f(CW\*(C`FILTER\*(C'\fR, etc., mark the start of a block which may contain text or other directives up to the matching \&\f(CW\*(C`END\*(C'\fR directive. Blocks may be nested indefinitely. The \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR, \&\f(CW\*(C`ELSIF\*(C'\fR and \f(CW\*(C`ELSE\*(C'\fR directives also define blocks and may be grouped together in the usual manner. .PP .Vb 3 \& [% FOREACH item = [ \*(Aqfoo\*(Aq \*(Aqbar\*(Aq \*(Aqbaz\*(Aq ] %] \& * Item: [% item %] \& [% END %] \& \& [% BLOCK footer %] \& Copyright 2000 [% me %] \& [% INCLUDE company/logo %] \& [% END %] \& \& [% IF foo %] \& [% FOREACH thing = foo.things %] \& [% thing %] \& [% END %] \& [% ELSIF bar %] \& [% INCLUDE barinfo %] \& [% ELSE %] \& do nothing... \& [% END %] .Ve .PP Block directives can also be used in a convenient side-effect notation. .PP .Vb 1 \& [% INCLUDE userinfo FOREACH user = userlist %] \& \& [% INCLUDE debugtxt msg="file: $error.info" \& IF debugging %] \& \& [% "Danger Will Robinson" IF atrisk %] .Ve .PP versus: .PP .Vb 3 \& [% FOREACH user = userlist %] \& [% INCLUDE userinfo %] \& [% END %] \& \& [% IF debugging %] \& [% INCLUDE debugtxt msg="file: $error.info" %] \& [% END %] \& \& [% IF atrisk %] \& Danger Will Robinson \& [% END %] .Ve .SH "Capturing Block Output" .IX Header "Capturing Block Output" The output of a directive can be captured by simply assigning the directive to a variable. .PP .Vb 1 \& [% headtext = PROCESS header title="Hello World" %] \& \& [% people = PROCESS userinfo FOREACH user = userlist %] .Ve .PP This can be used in conjunction with the \f(CW\*(C`BLOCK\*(C'\fR directive for defining large blocks of text or other content. .PP .Vb 6 \& [% poem = BLOCK %] \& The boy stood on the burning deck, \& His fleece was white as snow. \& A rolling stone gathers no moss, \& And Keith is sure to follow. \& [% END %] .Ve .PP Note one important caveat of using this syntax in conjunction with side-effect notation. The following directive does not behave as might be expected: .PP .Vb 1 \& [% var = \*(Aqvalue\*(Aq IF some_condition %] # does not work .Ve .PP In this case, the directive is interpreted as (spacing added for clarity) .PP .Vb 3 \& [% var = IF some_condition %] \& value \& [% END %] .Ve .PP rather than .PP .Vb 3 \& [% IF some_condition %] \& [% var = \*(Aqvalue\*(Aq %] \& [% END %] .Ve .PP The variable is assigned the output of the \f(CW\*(C`IF\*(C'\fR block which returns \&\f(CW\*(Aqvalue\*(Aq\fR if true, but nothing if false. In other words, the following directive will always cause 'var' to be cleared. .PP .Vb 1 \& [% var = \*(Aqvalue\*(Aq IF 0 %] .Ve .PP To achieve the expected behaviour, the directive should be written as: .PP .Vb 1 \& [% SET var = \*(Aqvalue\*(Aq IF some_condition %] .Ve .SH "Chaining Filters" .IX Header "Chaining Filters" Multiple \f(CW\*(C`FILTER\*(C'\fR directives can be chained together in sequence. They are called in the order defined, piping the output of one into the input of the next. .PP .Vb 1 \& [% PROCESS somefile FILTER truncate(100) FILTER html %] .Ve .PP The pipe character, \f(CW\*(C`|\*(C'\fR, can also be used as an alias for \f(CW\*(C`FILTER\*(C'\fR. .PP .Vb 1 \& [% PROCESS somefile | truncate(100) | html %] .Ve .SH "Multiple Directive Blocks" .IX Header "Multiple Directive Blocks" Multiple directives can be included within a single tag when delimited by semi-colons. Note however that the \f(CW\*(C`TAGS\*(C'\fR directive must always be specified in a tag by itself. .PP .Vb 6 \& [% IF title; \& INCLUDE header; \& ELSE; \& INCLUDE other/header title="Some Other Title"; \& END \& %] .Ve .PP versus .PP .Vb 5 \& [% IF title %] \& [% INCLUDE header %] \& [% ELSE %] \& [% INCLUDE other/header title="Some Other Title" %] \& [% END %] .Ve PK � �[���i� � man3/Template::Grammar.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Template::Grammar 3" .TH Template::Grammar 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Grammar \- Parser state/rule tables for the TT grammar .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # no user serviceable parts inside .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module defines the state and rule tables that the Template::Parser module uses to parse templates. It is generated from a YACC-like grammar using the \f(CW\*(C`Parse::Yapp\*(C'\fR module. The \fIparser\fR sub-directory of the Template Toolkit source distribution contains the grammar and other files required to generate this module. .PP But you don't need to worry about any of that unless you're planning to modify the Template Toolkit language. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> .PP <http://wardley.org/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 1996\-2022 Andy Wardley. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Template::Parser PK � �[� man1/tpage.1nu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "TPAGE 1" .TH TPAGE 1 "2019-12-23" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tools::tpage \- Process templates from command line .SH "USAGE" .IX Header "USAGE" .Vb 1 \& tpage [ \-\-define var=value ] file(s) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBtpage\fR script is a simple wrapper around the Template Toolkit processor. Files specified by name on the command line are processed in turn by the template processor and the resulting output is sent to \s-1STDOUT\s0 and can be redirected accordingly. e.g. .PP .Vb 2 \& tpage myfile > myfile.out \& tpage header myfile footer > myfile.html .Ve .PP If no file names are specified on the command line then \fBtpage\fR will read \&\s-1STDIN\s0 for input. .PP The \f(CW\*(C`\-\-define\*(C'\fR option can be used to set the values of template variables. e.g. .PP .Vb 1 \& tpage \-\-define author="Andy Wardley" skeleton.pm > MyModule.pm .Ve .SS "The \fI.tpagerc\fP Configuration File" .IX Subsection "The .tpagerc Configuration File" You can use a \fI.tpagerc\fR file in your home directory. .PP The purpose of this file is to set any \fIglobal\fR configuration options that you want applied \fIevery\fR time \fItpage\fR is run. For example, you can use the \f(CW\*(C`include_path\*(C'\fR to use template files from a generic template directory. .PP Run \f(CW\*(C`tpage \-h\*(C'\fR for a summary of the options available. .PP See Template for general information about the Perl Template Toolkit and the template language and features. .SH "AUTHOR" .IX Header "AUTHOR" Andy Wardley <abw@wardley.org> .PP <http://wardley.org/> .SH "VERSION" .IX Header "VERSION" 2.68, distributed as part of the Template Toolkit version 2.19, released on 27 April 2007. .SH "COPYRIGHT" .IX Header "COPYRIGHT" .Vb 1 \& Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved. .Ve .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" ttree PK � �[Ue�B\; \; man1/ttree.1nu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "TTREE 1" .TH TTREE 1 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Tools::ttree \- Process entire directory trees of templates .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& ttree [options] [files] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fIttree\fR script is used to process entire directory trees containing template files. The resulting output from processing each file is then written to a corresponding file in a destination directory. The script compares the modification times of source and destination files (where they already exist) and processes only those files that have been modified. In other words, it is the equivalent of 'make' for the Template Toolkit. .PP It supports a number of options which can be used to configure behaviour, define locations and set Template Toolkit options. The script first reads the \fI.ttreerc\fR configuration file in the \s-1HOME\s0 directory, or an alternative file specified in the \s-1TTREERC\s0 environment variable. Then, it processes any command line arguments, including any additional configuration files specified via the \f(CW\*(C`\-f\*(C'\fR (file) option. .SS "The \fI.ttreerc\fP Configuration File" .IX Subsection "The .ttreerc Configuration File" When you run \fIttree\fR for the first time it will ask you if you want it to create a \fI.ttreerc\fR file for you. This will be created in your home directory. .PP .Vb 4 \& $ ttree \& Do you want me to create a sample \*(Aq.ttreerc\*(Aq file for you? \& (file: /home/abw/.ttreerc) [y/n]: y \& /home/abw/.ttreerc created. Please edit accordingly and re\-run ttree .Ve .PP The purpose of this file is to set any \fIglobal\fR configuration options that you want applied \fIevery\fR time \fIttree\fR is run. For example, you can use the \f(CW\*(C`ignore\*(C'\fR and \f(CW\*(C`copy\*(C'\fR / \f(CW\*(C`link\*(C'\fR options to provide regular expressions that specify which files should be ignored and which should be copied or linked rather than being processed as templates. You may also want to set flags like \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`recurse\*(C'\fR according to your preference. .PP A minimal \fI.ttreerc\fR: .PP .Vb 4 \& # ignore these files \& ignore = \eb(CVS|RCS)\eb \& ignore = ^# \& ignore = ~$ \& \& # copy these files \& copy = \e.(gif|png|jpg|pdf)$ \& \& # recurse into directories \& recurse \& \& # provide info about what\*(Aqs going on \& verbose .Ve .PP In most cases, you'll want to create a different \fIttree\fR configuration file for each project you're working on. The \f(CW\*(C`cfg\*(C'\fR option allows you to specify a directory where \fIttree\fR can find further configuration files. .PP .Vb 1 \& cfg = /home/abw/.ttree .Ve .PP The \f(CW\*(C`\-f\*(C'\fR command line option can be used to specify which configuration file should be used. You can specify a filename using an absolute or relative path: .PP .Vb 3 \& $ ttree \-f /home/abw/web/example/etc/ttree.cfg \& $ ttree \-f ./etc/ttree.cfg \& $ ttree \-f ../etc/ttree.cfg .Ve .PP If the configuration file does not begin with \f(CW\*(C`/\*(C'\fR or \f(CW\*(C`.\*(C'\fR or something that looks like a MS-DOS absolute path (e.g. \f(CW\*(C`C:\e\eetc\e\ettree.cfg\*(C'\fR) then \&\fIttree\fR will look for it in the directory specified by the \f(CW\*(C`cfg\*(C'\fR option. .PP .Vb 1 \& $ ttree \-f test1 # /home/abw/.ttree/test1 .Ve .PP The \f(CW\*(C`cfg\*(C'\fR option can only be used in the \fI.ttreerc\fR file. All the other options can be used in the \fI.ttreerc\fR or any other \fIttree\fR configuration file. They can all also be specified as command line options. .PP Remember that \fI.ttreerc\fR is always processed \fIbefore\fR any configuration file specified with the \f(CW\*(C`\-f\*(C'\fR option. Certain options like \f(CW\*(C`lib\*(C'\fR can be used any number of times and accumulate their values. .PP For example, consider the following configuration files: .PP \&\fI/home/abw/.ttreerc\fR: .PP .Vb 2 \& cfg = /home/abw/.ttree \& lib = /usr/local/tt2/templates .Ve .PP \&\fI/home/abw/.ttree/myconfig\fR: .PP .Vb 1 \& lib = /home/abw/web/example/templates/lib .Ve .PP When \fIttree\fR is invoked as follows: .PP .Vb 1 \& $ ttree \-f myconfig .Ve .PP the \f(CW\*(C`lib\*(C'\fR option will be set to the following directories: .PP .Vb 2 \& /usr/local/tt2/templates \& /home/abw/web/example/templates/lib .Ve .PP Any templates located under \fI/usr/local/tt2/templates\fR will be used in preference to those located under \&\fI/home/abw/web/example/templates/lib\fR. This may be what you want, but then again, it might not. For this reason, it is good practice to keep the \fI.ttreerc\fR as simple as possible and use different configuration files for each \fIttree\fR project. .SS "Directory Options" .IX Subsection "Directory Options" The \f(CW\*(C`src\*(C'\fR option is used to define the directory containing the source templates to be processed. It can be provided as a command line option or in a configuration file as shown here: .PP .Vb 1 \& src = /home/abw/web/example/templates/src .Ve .PP Each template in this directory typically corresponds to a single web page or other document. .PP The \f(CW\*(C`dest\*(C'\fR option is used to specify the destination directory for the generated output. .PP .Vb 1 \& dest = /home/abw/web/example/html .Ve .PP The \f(CW\*(C`lib\*(C'\fR option is used to define one or more directories containing additional library templates. These templates are not documents in their own right and typically comprise of smaller, modular components like headers, footers and menus that are incorporated into pages templates. .PP .Vb 2 \& lib = /home/abw/web/example/templates/lib \& lib = /usr/local/tt2/templates .Ve .PP The \f(CW\*(C`lib\*(C'\fR option can be used repeatedly to add further directories to the search path. .PP A list of templates can be passed to \fIttree\fR as command line arguments. .PP .Vb 1 \& $ ttree foo.html bar.html .Ve .PP It looks for these templates in the \f(CW\*(C`src\*(C'\fR directory and processes them through the Template Toolkit, using any additional template components from the \f(CW\*(C`lib\*(C'\fR directories. The generated output is then written to the corresponding file in the \f(CW\*(C`dest\*(C'\fR directory. .PP If \fIttree\fR is invoked without explicitly specifying any templates to be processed then it will process every file in the \f(CW\*(C`src\*(C'\fR directory. If the \f(CW\*(C`\-r\*(C'\fR (recurse) option is set then it will additionally iterate down through sub-directories and process and other template files it finds therein. .PP .Vb 1 \& $ ttree \-r .Ve .PP If a template has been processed previously, \fIttree\fR will compare the modification times of the source and destination files. If the source template (or one it is dependant on) has not been modified more recently than the generated output file then \fIttree\fR will not process it. The \fI\-a\fR (all) option can be used to force \fIttree\fR to process all files regardless of modification time. .PP .Vb 1 \& $ tree \-a .Ve .PP Any templates explicitly named as command line argument are always processed and the modification time checking is bypassed. .SS "File Options" .IX Subsection "File Options" The \f(CW\*(C`ignore\*(C'\fR, \f(CW\*(C`copy\*(C'\fR, \f(CW\*(C`link\*(C'\fR and \f(CW\*(C`accept\*(C'\fR options are used to specify Perl regexen to filter file names. Files that match any of the \&\f(CW\*(C`ignore\*(C'\fR options will not be processed. Remaining files that match any of the \f(CW\*(C`copy\*(C'\fR or \f(CW\*(C`link\*(C'\fR regexen will be copied or linked to the destination directory. Files that reside in any of the \f(CW\*(C`copy_dir\*(C'\fR directories are also copied. Remaining files that then match any of the \&\f(CW\*(C`accept\*(C'\fR criteria are then processed via the Template Toolkit. If no \&\f(CW\*(C`accept\*(C'\fR parameter is specified then all files will be accepted for processing if not already copied or ignored. .PP .Vb 4 \& # ignore these files \& ignore = \eb(CVS|RCS)\eb \& ignore = ^# \& ignore = ~$ \& \& # copy these files \& copy = \e.(gif|png|jpg|pdf)$ \& \& # accept only .tt2 templates \& accept = \e.tt2$ .Ve .PP The \f(CW\*(C`suffix\*(C'\fR option is used to define mappings between the file extensions for source templates and the generated output files. The following example specifies that source templates with a \f(CW\*(C`.tt2\*(C'\fR suffix should be output as \f(CW\*(C`.html\*(C'\fR files: .PP .Vb 1 \& suffix tt2=html .Ve .PP Or on the command line, .PP .Vb 1 \& \-\-suffix tt2=html .Ve .PP You can provide any number of different suffix mappings by repeating this option. .PP The \f(CW\*(C`binmode\*(C'\fR option is used to set the encoding of the output file. For example use \f(CW\*(C`\-\-binmode=:utf8\*(C'\fR to set the output format to unicode. .SS "Template Dependencies" .IX Subsection "Template Dependencies" The \f(CW\*(C`depend\*(C'\fR and \f(CW\*(C`depend_file\*(C'\fR options allow you to specify how any given template file depends on another file or group of files. The \f(CW\*(C`depend\*(C'\fR option is used to express a single dependency. .PP .Vb 1 \& $ ttree \-\-depend foo=bar,baz .Ve .PP This command line example shows the \f(CW\*(C`\-\-depend\*(C'\fR option being used to specify that the \fIfoo\fR file is dependant on the \fIbar\fR and \fIbaz\fR templates. This option can be used many time on the command line: .PP .Vb 1 \& $ ttree \-\-depend foo=bar,baz \-\-depend crash=bang,wallop .Ve .PP or in a configuration file: .PP .Vb 2 \& depend foo=bar,baz \& depend crash=bang,wallop .Ve .PP The file appearing on the left of the \f(CW\*(C`=\*(C'\fR is specified relative to the \f(CW\*(C`src\*(C'\fR or \f(CW\*(C`lib\*(C'\fR directories. The file(s) appearing on the right can be specified relative to any of these directories or as absolute file paths. .PP For example: .PP .Vb 1 \& $ ttree \-\-depend foo=bar,/tmp/baz .Ve .PP To define a dependency that applies to all files, use \f(CW\*(C`*\*(C'\fR on the left of the \f(CW\*(C`=\*(C'\fR. .PP .Vb 1 \& $ ttree \-\-depend *=header,footer .Ve .PP or in a configuration file: .PP .Vb 1 \& depend *=header,footer .Ve .PP Any templates that are defined in the \f(CW\*(C`pre_process\*(C'\fR, \f(CW\*(C`post_process\*(C'\fR, \&\f(CW\*(C`process\*(C'\fR or \f(CW\*(C`wrapper\*(C'\fR options will automatically be added to the list of global dependencies that apply to all templates. .PP The \f(CW\*(C`depend_file\*(C'\fR option can be used to specify a file that contains dependency information. .PP .Vb 1 \& $ ttree \-\-depend_file=/home/abw/web/example/etc/ttree.dep .Ve .PP Here is an example of a dependency file: .PP .Vb 1 \& # This is a comment. It is ignored. \& \& index.html: header footer menubar \& \& header: titlebar hotlinks \& \& menubar: menuitem \& \& # spanning multiple lines with the backslash \& another.html: header footer menubar \e \& sidebar searchform .Ve .PP Lines beginning with the \f(CW\*(C`#\*(C'\fR character are comments and are ignored. Blank lines are also ignored. All other lines should provide a filename followed by a colon and then a list of dependant files separated by whitespace, commas or both. Whitespace around the colon is also optional. Lines ending in the \f(CW\*(C`\e\*(C'\fR character are continued onto the following line. .PP Files that contain spaces can be quoted. That is only necessary for files after the colon (':'). The file before the colon may be quoted if it contains a colon. .PP As with the command line options, the \f(CW\*(C`*\*(C'\fR character can be used as a wildcard to specify a dependency for all templates. .PP .Vb 1 \& * : config,header .Ve .SS "Template Toolkit Options" .IX Subsection "Template Toolkit Options" \&\fIttree\fR also provides access to the usual range of Template Toolkit options. For example, the \f(CW\*(C`\-\-pre_chomp\*(C'\fR and \f(CW\*(C`\-\-post_chomp\*(C'\fR \fIttree\fR options correspond to the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR options. .PP Run \f(CW\*(C`ttree \-h\*(C'\fR for a summary of the options available. .SH "AUTHORS" .IX Header "AUTHORS" Andy Wardley <abw@andywardley.com> .PP <http://www.andywardley.com/> .PP With contributions from Dylan William Hardison (support for dependencies), Bryce Harrington (\f(CW\*(C`absolute\*(C'\fR and \f(CW\*(C`relative\*(C'\fR options), Mark Anderson (\f(CW\*(C`suffix\*(C'\fR and \f(CW\*(C`debug\*(C'\fR options), Harald Joerg and Leon Brocard who gets everywhere, it seems. .SH "VERSION" .IX Header "VERSION" 2.68, distributed as part of the Template Toolkit version 2.19, released on 27 April 2007. .SH "COPYRIGHT" .IX Header "COPYRIGHT" .Vb 1 \& Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved. .Ve .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" tpage PK � �[ arch/auto/Template/.existsnu �[��� PK � �[ # arch/auto/Template/Stash/XS/.existsnu �[��� PK � �[I� iP P ! arch/auto/Template/Stash/XS/XS.sonu ȯ�� ELF > �' @ � @ 8 @ ' & q< q< ` ` ` � � �z �� �� � � | � � � � � � � � � � $ $ S�td � � � P�td Tc Tc Tc � � Q�td R�td �z �� �� P P GNU � GNU � �@h��gϳÇH���Y , ? @ @? �c! � P m � + � � � � � � � � # � � f U � { � 9 U o � � � � � � � < s | � m � � � \ E � 4 ( L � , b A Z � F " _ � �[ s __gmon_start__ _ITM_deregisterTMCloneTable _ITM_registerTMCloneTable __cxa_finalize strcmp Perl_hv_common_key_len Perl_mg_get Perl_sv_2bool_flags Perl_sv_isobject Perl_get_sv Perl_sv_setsv_flags Perl_die_nocontext Perl_croak_nocontext Perl_sv_2pv_flags Perl_newSV_type Perl_av_extend Perl_av_store Perl_newRV_noinc Perl_sv_2mortal Perl_sv_free2 Perl_newSVsv_flags Perl_looks_like_number Perl_av_fetch Perl_mg_set Perl_sv_derived_from Perl_gv_fetchmethod_autoload Perl_av_len Perl_call_method Perl_sv_2iv_flags Perl_stack_grow Perl_markstack_grow __stack_chk_fail Perl_call_sv Perl_gv_add_by_type Perl_av_push Perl_newSViv Perl_newSVpv Perl_safesysfree Perl_safesysmalloc strlen Perl_newSVpvn Perl_sv_catsv_flags Perl_sv_catpvn_flags Perl_hv_iterinit Perl_hv_iterkeysv Perl_hv_iterval Perl_hv_iternext_flags Perl_sv_len_utf8 Perl_sv_len Perl_newRV __snprintf_chk strstr memchr Perl_av_undef Perl_croak_xs_usage Perl_push_scope Perl_savetmps Perl_pop_scope Perl_free_tmps boot_Template__Stash__XS Perl_xs_handshake Perl_newXS_deffile Perl_xs_boot_epilog libperl.so.5.32 libc.so.6 GLIBC_2.4 GLIBC_2.2.5 GLIBC_2.3.4 - ii 7 ui A ti M �� @( �� ( �� �� � �` �� P( � a � 0? � #a (� �= @� (a P� �? `� -a x� �@ �� 4a �� �: �� 8a �� �9 �� @a ȋ �: � Ea � `@ � � � 6 �� < � � � � (� 0� 8� @� H� P� X� `� h� p� x� �� �� �� �� �� �� �� �� �� Ȏ Ў ؎ � � � �� ! � " � # � $ � % � & (� ' 0� ( 8� ) @� * H� + P� , X� - `� . h� / p� 0 x� 1 �� 2 �� 3 �� 4 �� 5 �� 7 �� 8 �� 9 �� : �� ; ȏ < Џ = ؏ > � �H��H��o H��t��H��� �5�m �%�m � �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h! ������� �h" ������ �h# ������ �h$ ������ �h% ������ �h& ������ �h' ��q����� �h( ��a����� �h) ��Q����� �h* ��A����� �h+ ��1����� �h, ��!����� �h- ������� �h. ������� �h/ ����� �h0 ������ �h1 ������� �h2 ������ �h3 ������ �h4 ������ �h5 ������ �h6 ������ �h7 ��q����� �h8 ��a����� �h9 ��Q����� �h: ��A����� ��% j D � ��%j D � ��% j D � ��%j D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%�i D � ��%}i D � ��%ui D � ��%mi D � ��%ei D � ��%]i D � ��%Ui D � ��%Mi D � ��%Ei D � ��%=i D � ��%5i D � ��%-i D � ��%%i D � ��% i D � ��%i D � ��% i D � ��%i D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%�h D � ��%}h D � ��%uh D � ��%mh D � ��%eh D � ��%]h D � ��%Uh D � ��%Mh D H�=�h H��h H9�tH�6h H��t �� � � � H�=qh H�5jh H)�H��H��?H��H�H�tH�h H��t��f D � � � ��=&h u+UH�=�g H��t H�=�b �9����d�����g ]� � � � ��w��� � � �H��8 � @ AWA� AVE1�AUL�-jb ATUH��SH�� � M9�v,K� 7H��H��I��I��M�I�4$�����x"t L�sM9�w�E1�H��L��[]A\A]A^A_�f�I���ff. � �~ t 1�� � AU� E1�A� ATH��6 UH��SH��j ���ZYH��t L� A�D$ ��u1�H��[]A\A]�f D H��8 M��I)ݩ uI��Hw.1�I9������L��H�����I��Hv�A�D$ ��t� � ��t6I�$1�H��t�H�R� H��w�1�H��t�I�D$�80������l�����tI�$H�x ������Q�����u1�L��H��� �������5���I�T$� �B�!���H�H��B������ATI��UH��H��������u A�D$ ��t0� H�5�5 H���\���H�� L��H�����1�1��0���% = u"I�$H�@H�� I�t$H�=r5 1��"���L��H�� � H���+���H����f D AWAVI��AUA��ATUSH��P H��H�/H�\$���� � A� ����A�U�L��Hc�H��H�$�n���L� $� � A��E9�|WH��I��H�]�C � t�CD��L��H��D)�L��L� $Hc��t���L� $H��u��S��v{��A���SE9�}� @ I�.L��L�����L��H���w����C � t^H9\$tWH��[]A\A]A^A_� � ��t H�E H��H�D$I�.H�D$H��[]A\A]A^A_�H��L��L� $���L� $� ���L��L������ D AWI��AVAUATI��UH��SH��H��8L�$D�L$ dH�%( H�D$(H�H�D$�B �� �� �� L�mH�U H�RH�T$ � tH�\$ M��$P H��tS��tNL9�tIH�5q3 1�L��� ���H��H��t�@ �y I��$8 H��H)�H��Hw=H9�u\A�E <_t<.uOH�D$(dH+%( �� H��8L��[]A\A]A^A_� D �F ��t ���� ���~ H�H�x u��C �G H��L��������7 L�{A�G ��< �D �� �S �D$ �� H��L��E1�A� j �L$0L��L������Y^H��H��teH�(�E �� I��$8 H��H)�H��H�@ �E ��t8���: H�E H��t&H�@H�������H��tH�E�80���f D H�4$� L���/���H��L��L��j �L$0H��I��A�$ L���k���XZ�E@�� L�4$���f D L�t$ � H��L���{���I�ŋE ���� �� ���� L��H��L���N����E ����f D H��L���e������*����D$ tf�E % = � H�E H�P 1�L��L�����H��H��t6L�(A�E �� I��$8 L��H)�H��H�@ L9����� � H�4$� L������I�ŋE % = �� H�E H�P L��L��L���s���A�E@����L��L���m���L�4$�a��� @ H��0 H��L�����������H�C� L��L��H� H�0���H��������D$ ����M��tL��L����D$ I�D$xH��I�D$xI;�$� �6 H�|$H��I+T$H���I�D$ H)�H��� H�D$�|$ H�XL�p��x>1�Hc�1�L��L���0���H��H��tI�D$ L)�H���� H�I��I���9l$ }�I�D$ L)�H���� H�$I��� L��L��I�M�4$���L�������I���/���f�H�H���p���H�@H������H���Y���H�F�80���G��� � H��L�����H������H9�������f�� H��L����H���'��� � L��H�D$���H�t$�p���f � A�E ���������� I�E H�������H�@H���\���H�������I�E�80�F������ @ ��u1�L���A�������p��� @ H�F�@����H� H� �@����H��L�����Q���L��L��� L���=�I���N������� H�E H�x ��������� � H��L�����H�+H��������E �W���H��L������G�����tkI�E H�x �h������f D L��L����L�+M�������A�E �V���L��L���s��F�����u91�H��L���,�������/�����u1�L��L��� �����0���H�E�@����H� H� �@�����L��L��� L��� �I���R���L���]����H��H��� L����H�D$����I�E�@�z���H� H� �@�j����^����C�H�s�F % = ujH�H�@I��$ H�CH�pL��H�=�- 1���% = uI�H�@I��$ H�CH�p��L��I��$ � L�����H���I��$ � L�����H���ff. � �AWAVI��AUATI��USH��L�?H�t$H���C H���3�A��I�FxH��I�FxI;�� �: L��I+VH���E��x;1� Hc�1�L��L�����H��H��tI�F L)�H��~|H�I��I���D9�~�M�>H�t$� L����I��p A��H�FH�(H���� �E � I��8 H��H)�H��Hw>H9�t]H��D��L��[]A\A]A^A_���L��L��� L��� �I���i��� D �E ��t���tcH�E H��t�H�@H���� I��p H�FH�8 �� H�0L���� @ H�WxA�����H�BH�GxH;�� uML����������t^H�E H�x �C����f. � 1�L���V�H�@H�(H��� �������L��I+FH���B���H��L����������t H�E�@�>���H� H� �@�.���1�H��L�������������H�������H�E�80��������1�L����H�@���f�AVI��AUM��ATI��UH��SH��H���J dH�%( H�D$1���% = � H�H�RH�@H�$�� tH� $�C % tuH�s�F �� �� �� uRH��E1�A� L��j �L$��H��XZH��t-H�3�F � �� ��tH�V�z �� ���� I��P 1�M�e H�T$dH+%( �� H��[]A\A]A^� D H��L������t��E % = uRH�E H�P H�s1�L����H���_��� @ H�� H�����M H���� D I�u � �l���f�� H��L�����H��� L���0���t H�3�F �%����L����H�3�F ���H�3L��L������I�E � � ����l�ff. � �AWI��� AVI��AUI��ATUH��SH���<�I��M��tA�GL��L��H�����M��tL��H������D$ ��yi1�M��t A�E � u H��L��H��[]A\A]A^A_�/� � A�E�SL��L��Hc�H�����H��u�A�U���� ��A�U� @ ��L��H��1�Hc��M�� 9\$ �w���Hc�1�L��H��� ���I��H��t�H�H��t�AHc�L��H���Y�H��u�I�7H��t��V��v���V�H���T��L��H���G�����f�� �AWI��AVAUI��� ATUSH�����L��L��I�����D$ ��y(L��L���=�H��L��[H��]A\A]A^A_�� @ �PL��L��I��Hc�1��Z�� � ��9\$ |�Hc�1�L��L���'�H��H��t�H�H��t�AD��L��L��)�Hc��`�H��u�H�u H��t��V��v���V�L���Z�� � � �UH�����H��H���X�H��]H���L�ff. � �� �UH����H��H�p�'�H��]H����ff. � AWAVI��AUATUH��� S��H��XdH�%( H�D$H1����{I�ă�?� I��M����� �E L��1�<(t$���� ��<.tDH�����H���E <(u܅��� � H������ �} .u�X� � � Hc�L��L��H�����L��L��H����1�L���3�L��L��H��������\���M9�tL���/�L��L����H�T$HdH+%( uOH��X[]A\A]A^A_� D ������v���f D Hc����I��H��t I���������H�=% 1��U��P�ATI��H��1�UH��S�,�H��tOH��@ tFL����H��H�sL��j ��E1�A� H�����ZYH��tH� �@ tH�P�z t @ 1�[]A\ÐAVI��AUI��ATI��UH��H��SL���a�H��t H�@H��u3L��H�"# H���Q���E1�I��H��P M��u7H�[D��]A\A]A^�I�t$L��H���A� H�[D��]A\A]A^�f D L��L��H��1����L��H��H�����A� H�[D��]A\A]A^� D � �AWAVI��AUI��ATUSH��(H�T$dH�%( H�D$1�H��tFH��1�1�H����H��t2H�0�V �� �� � H�H�RH�T$H� L�x� D H�D$ L�=+" 1�H�5q" L����L��L��I���9��Ņ�xc1ې1�Hc�L��L����H��tDL� A�@ t I�@�x tg� L��L��L����9�tH�L$L��L��L��A� ����9�}�L��L���U�H�T$dH+%( uWH��([]A\A]A^A_�f D H�T$L��L���0���� L��L��H���=�� H�T$� L�����I��������f � � �AUI��ATUSH�� H���r�H��L��H�����If�L��L����H��H��t�@H��L����L��H��L����H��H��t�@H��L�����1�H��L���L�I��H��u�H��L���i�H��L��[H��]A\A]�4� @ � �ATI��USH�� ���H��L��H������' � L����H��H��t�@H��L���Q�H��1�L�����H��H��u�H��L�����[L��]H��A\��f�� �ATI��USH�� �H�H��L��H���j��* � H��L����H��H��t�@H��L�����1�H��L���A�H��H��u�H��L���^�[L��]H��A\�/�ff. � @ � �UH���F t"���H��H����H��]H����f D �K�H����f D AWI��AVI��AUATI��USL��H��H�t$� �g�L��H��H���I�L�L$I��M��tA�AL��H��L����I��L��L��L��L���E���H��t�U��v0���UM��tA�U��v4��A�UH��[]A\A]A^A_�f D H��L��D$� ��D$� L��L��D$����D$�ff. � AWI��AVE��AUI��ATI��UH��H��SL��H���(�H��t H�@H��u:H� L��H������H��usA��tEH��P 1�H�+H��[]A\A]A^A_�f�I�t$L��H���H�H��� []A\A]A^A_� @ H��I��L��L��[L��H��]A\A]A^A_�f���f D L��L��H��1�H�D$�{���H�t$H��H���+�H�H��� []A\A]A^A_� @ AWI��AVE��AUI��ATI��UH��H��SL��H���(�H��t H�@H��u:H�" L��H������H��usA��tEH��P 1�H�+H��[]A\A]A^A_�f�L��L��H���H�H��� []A\A]A^A_�f D H��I��L��L��[L��H��]A\A]A^A_�f���f D L��L��H��1�H�D$�{�H�t$H��H���+�H�H��� []A\A]A^A_� @ AWAVI��AUATI��UH��SD��H�� H�L$dH�%( H��$� H�H�D$�B % = �� H�L�zH�@H�D$@M��P L�l$8H��tLH�5� 1�L��� �H��H��tt�@ �� I��8 H��H)�H��HwKH9�����tMA�<_t<.uAH��$� dH+%( �� H�Ĩ L��[]A\A]A^A_�f � �F ���� �E �( M���t2A�@ uc��tA�@ � �� M9��� M���f. � H�L$A��L�D$8L��H��L��������} ���� L�D$8A�@ t�I�h�} u�H��L��L�D$����L�D$����u���1�1�H��L����L�D$H���X���L;(�k����J��� D H�T$@� L������I���t���f D ���� H�H�������H�@H�������H�����H�F�80���������H�� H��L��� ��A�����e H�E�@ �� �L �� �� H��L�����M�������H�E� L��L��H�D$8 H� H� H��H�D$(����H���� I�FxH��I�FxI;�� �} H�L$H��I+VH���I�F H)�H���h H�D$H�t$H�hL�XH���� L��L�\$�^��L�\$���D$ �� E1��! � I� I��I�A��D9L$ �� H�t$Ic�1�L��L�\$D�L$���D�L$L�\$H��I��t�I�F L)�H���L��L� L��D�L$L�D$���D�L$L�D$I��끐H�L$L�D$8L��H��L��D�L$L�D$����� ��u`L�D$8�$���f D ��u;���� 1�L���������������� L��H�D$����H�t$�c����H�H�x ���k�����L�D$D�L$���D$�� E��t!H�5 L��L�D$���L�D$���`���H�L$A��L��H��L���j������B���A�D$ �6���I�D$�x �'���� L������I�\$L�eH�l$HI���]H�H�@H�D$HI�H�PH��E1�A� L��j �L$XL�����A[I��XM��t I��B �� �BL��L���?���D$Lc|$H��L���*��I9��` L��1�H��L�����I��H��t�H�0�F � �� % = �Q���H�� L���8��H���L���H�L$L�D$8L��H��L��L�D$����t.��L�D$����H�L$L��H��L�������� @ L�l$8���f D H��L���%�����R���H�L$L�D$8L��H��L��L�D$�D$��L�D$D�L$�������H�L$L��H��L��D�L$����t���D�L$�o���A�D$ �c���I�D$�x �T���� L��D�L$���I�\$H�mD�L$I���PH�H�P 1�H��L��D�L$���D�L$H��I��t&H��B �� �BL��L��D�L$�x��D�L$A��H��L��Mc�D�L$�\��D�L$I9��� 1�L��H��L��D�L$�)��D�L$H��I��t�H�0�F �� I�4$L��D�L$���D�L$��t�I�4$�F % = �/���� L��D�L$�<��D�L$H������ � H��L��D�L$�x��D�L$�����H�E�@ ��� D H�F�@����H� H� �@��������� D M� L��� L���=��M��p I�A��I�AH�0H���� �F �7 I��8 H��H)�H��H� H9������� I��p H�A�I�H�VH�H���� �@ � H�L$(1��At-H�H�PH�AH�T�H�H��tD�R E��tH� H��tH��L�\$PH��M��� PL��L�C �@ 1��A L�\$ ���M��p Ƅ$� _AYI�PL�\$H�2H���� �F % = �� M�� L��� L��L�\$���L�\$H��L�����H��� H�E�@ �� �) �� �$���H�L$A��L�D$8L��H��L���i������P���������I��p H�FH�H���" 1�L��L����H�D$8I���@ �;���H�h�} �-������f D 1�L��L��H�L$D�D$���D�D$H�L$H�@H�0H������D��L���|��H�D$8I��H��� ���A�@ �����#����F ��t���� H�H��t�H�@H�����H��t�H�F�80�����M��p I�PH�: u"1�L��L��L�\$�m��M��p L�\$H�PH�H� H�@I�� I�@H� H���@ H�x�d���� L��L�e���L��H�����H��H���l H���@L��I��j �L$PA�$ L��L���V��ZYH��� �E@�� H��L�����I���Y���1�L�����H�@H� �@ � ���I��p H�VH�: u1�L�����H�PH�2L���i��f � 1�L��L��L�\$�^��L�\$H�@H� �@ % = �����M��p M�� I�AH�0H���5���L��1�L��L�\$L�D$� ��L�\$L�D$H�@H�0�������� H�H�x ������L���3���v���H�T$� L��H������H�D$�y���L��H�L$ D�D$H�t$���H�L$ D�D$H�t$���H�L$L�D$8L��H��L��L�D$�����.�����L�D$����H�L$A��L��H��L������������ue1�L��H�L$D�D$����H�L$���E���D�D$����1�L��L��L�\$����L�\$H�@H� ����U���� ���U��H�F�@��H� H� �@����x���PL��E1�A�$ j �L$PL��L������ZYH����������L��L���f��L��H���;��I���������H��L�������m���1�L���4��H�@H�����L��H�=� 1����L�����I�7�F �\���H��L������I�H�������H��L����������E % = u@H�E H�@I�� H�uL��H�=4 1��5��I��p H�FH�8 t'H�0L���y��H��I�� � L���"��H���1�L���c��H�@��H��L���B��I�$D�L$H���������L���#��D�L$�Z���f � AWI��H��AVI��AUI��ATUH��SD��H��(H�L$�F��H�D$M���H �����D$���L E1�� ��@ ���� A��D;d$�� 1�Ic�H��L������H��� L�(A�D$1�H��Hc�L���D$ ���H��� H� 1�@ tH�H1��y HE�L��A��L��L���-�I��H���q���H��(L��[]A\A]A^A_� � H�|$ t��tڋD$1�H��L���P�Hc��D��H���� HcT$1�H��L��L�(�&��H���� H� 1�@ tH�H1��y HE�L�D$H��(A��L��[L��]L��A\A]A^A_���H�D$�D$��������I���A�G E1��^���H�|$D��H�= �����s����H�|$�T$ H�=0 �����s����A�t$H�=w ����D��H�=0 ��� � �AWAVAUATUSH��H��8dH�%( H�D$(H�GxH�P�H�WxHcH�GH��D�bH� �H�H)�H����� �MMc�E1�Hc�N�4�J�<� L�<ȍMH�|$Hc�H��H�D$A�F � ���" A�G ��t I�W�z � H�=� 1����� % = �@ I�I�oH�@H�D$ H���O H�T$ �. H��H�T$���H���/ H�T$H��H�����H�L$L��H��I��E��H������L��H��H��� ���E � � �EH��H�����H�SL�l$J��LkL�+H�D$(dH+%( �� H��8[]A\A]A^A_� D I�vH��H�T$�'��H�T$A�Ń�����H�C��Hc�H�,�H�������E �5 H��8 H��H)�H��H�� H9�������A ����f. � H�T$ � L��H�����H��H������� � L�D$E��1�L��L��H�����H��E � ���1�H�5) H������H������ � �E ��� �����tGH�E H�������H�@H��vxA����� � H�L$E��L��H���5���H���m��� D ��u��u^1�H��H���������� @ H�E H�x ����� � H��H��������H���o���H�UD����:0DE��Y����H�E�@�Z���H� H� �@u��I����L��H��H�5% ����ff. � f�� �AWAVAUATUSH��H��8H�/dH�%( H�D$(H�GxH�P�H�WxHcH�GI��D�bH��H)�H������ Mc�A�VE1�N�<�J� � Hc�H� $L�,�A�G t I�w����A��A�E ��t I�U�z �9 H�=� 1���� % = �� I�E M�UH�@H�D$ M���� H�T$ �. L��D�D$ L�T$H�T$���D�D$ H���� H�T$H�t$H���U�D�D$ L��H��I��1�H���M���L��H��H������E � �� �EH��H���#��H�SL�4$J��LsL�3H�D$(dH+%( �� H��8[]A\A]A^A_� D H�T$ � L��H��D�D$ ���D�D$ I��M������1Ƀ�t#H�CE�NMc�J��@ tH�H1��y HE�L��L��H����H��E � �C���H��H�+�Z��H�����H�CxH��H�CxH;�� �� H��H+SH���H�C H)�H���� L�}H�C H�uH)�H���� L�nH��� H��H�3H�5� �E��A��H�A���� H�(H�P�H��t�EH�H�CXH9CPH���@����� H��� ����f D 1�L��H�����H���T��� H�� H�����H���d��� � H���������� H��H�� H���}��H����������H��H�5� �q��H�=B 1����� � �ATL�� H��1�UH� � H��H�� ���H���>��H��H�d���H�5� A�����H��H�5� H�������H��D��H��]A\��� � �H��H��� _DEBUG @ %s Template::Stash::PRIVATE Template::Stash::XS Template::Stash::LIST_OPS Template::Stash::HASH_OPS Template::Stash::SCALAR_OPS import %s is undefined root, ident, value, ... root, ident, ... undefined 3.102 v5.32.0 Stash.c Template::Stash::XS::get Template::Stash::XS::set each join keys length max reverse size values don't know how to assign to [ %s ].%s Template::Stash::XS: New() failed for convert_dotted_string don't know how to access [ %s ].%s Template::Stash::XS %cet: bad element %i Template::Stash::XS %cet: bad arg. %i Template::Stash::XS: set bad ident element at %i Template::Stash::XS: set bad ident argument at %i Template::Stash::XS: set (arg 2) must be a scalar or listref Template::Stash::XS: get (arg 2) must be a scalar or listref undefined() did not return a single value ;� ̼�� ����< ���T ��h ���� ���� l�� ���| ���� ,��0 ��� \��� L�� |��4 ���P ��� ���� L��8 ���� ���� ��� ��� ���0 ���| ��� ��� ��0 �� <���� ����, zR x � $ ����� FJ w� ?:*3$" D H���� \ ��� H p ���u B�H�E �I(�A0�D8�D@ 8D0A(B BBBC @ � ���@ R�P�H �D(�D8B@F8A0X (A ABBG ���� B�D�G ` L��K B�B�E �E(�A0�A8�KP� 8A0A(B BBBI ] 8A0A(B BBBA d � 8�� B�E�B �B(�D0�D8�Gp� 8D0A(B BBBF lxN�PxAp�xH�YxAp H � ���^ B�B�E �B(�D0�A8�DP� 8G0A(B BBBE L 8 ���� B�E�E �D(�D0�G@dHNPMHA@W 0A(A BBBF H � ���N B�J�E �E(�A0�D8�DPM 8G0A(B BBBL H � ���� F�E�B �J(�A0�A8�DPj 8D0D(B BBBI ,��$ E�W < @��% E�X L X T��p B�B�E �B(�A0�I8�F� 8A0A(B BBBF 4 � t��o B�I�D �_(I0T(A _AB \ � ���� B�E�E �D(�G0�~ (D BBBA W (D BBBG h(D BBB H @ ��� F�B�E �E(�A0�A8�D` 8A0A(B BBBG 4 � P��� F�E�A �A(�L0�(D DBB( � ���~ F�D�A �eDE ( � ��� F�D�A �hDE ���: E�] N H 8 ���� B�E�E �B(�D0�A8�GP} 8A0A(B BBBG � � 8��� B�E�E �E(�D0�G8�GP@ 8A0A(B BBBC T 8F0A(B BBBE D 8J0G(B BBBK l8F0A(B BBB� ���� B�E�E �E(�D0�G8�GP@ 8A0A(B BBBC R 8F0A(B BBBG D 8J0G(B BBBK l8F0A(B BBB� � ��� B�B�E �B(�D0�D8�J�� 8D0A(B BBBJ �N�N�D���I�p�B��L�V�A�F�N�P�A�` 8 ��� B�H�E �E(�A0�D8�G`� 8D0A(B BBBH m 8G0D(E BBBE H � �s F�B�B �B(�A0�A8�Gps 8A0A(B BBBF H � T�] F�B�B �B(�A0�A8�Gps 8A0A(B BBBF $ 4 h�s F�M�Z xGB @( ( �� �` P( a 0? #a �= (a �? -a �@ 4a �: 8a �9 @a �: Ea `@ - d\ �� �� ���o � Y � � � 8 X ���o ���o � ���o �o r ���o � 0 @ P ` p � � � � � � � � ! ! ! 0! @! P! `! p! �! �! �! �! �! �! �! �! " " " 0" @" P" `" p" �" �" �" �" �" �" �" �" # # # 0# @# P# `# p# �# �# �# �# �# �# Can't locate object method "%s" via package "%s" GCC: (GNU) 11.4.1 20231218 (Red Hat 11.4.1-3) AV:4g1231 RV:running gcc 11.4.1 20231218 BV:annobin gcc 11.4.1 20231218 GW:0x3d1056a lto SP:3 SC:-1 lto CF:8 lto FL:-2 lto GA:1 PI:2 SE:0 GA$3a1 �' �' GA$3a1 GA$3a1 d\ l\ GA$3a1 �' I( GA$3a1 c\ c\ GA$3a1 c\ c\ GA$3a1 GA$3a1 l\ q\ , P( 4 oF . P( 4 o� P( �_ � U�� T�� Q Q� `( u �o a� n� z� � `( � F� :� 1 - .� E A "� W S � y u R� � � ^� � � j� � � v� � � �� � � �� �( ! !�� � � �� � � �( o Uv �� Ӱ �( @ �� � �� � � . , � 8 6 � �� ( � a �� K E �� g a �� �) �F �� } �� � � �) � Uv T| Q0 q) � Uv T| ) � Uv Q ` R6X Y0 Ӱ � � a� E� $� ?� * � �� L� � � Y� � � f� @* 0 m g� � � T* � 6 Uv T ` Q1 g* � Y Uv Q| R2 p* � U0 2* � � Uv T| �* � � U ` �* � Uv T| Qv�R2 � �� Y� A� 0� � � �* K �� /� � � <� � I� 4 ( U� n b b� = c� � � o� � � |� � � �� � �� R � �� 3 / �* � U~ T; s� =+ =+ � � �� F D B� e+ ] �I Z� R N N� e a e� ] f� z t �+ U~ Ts + � u U~ T��Q} $ & \+ � U~ T��Q } | $ &Rs �+ � U~ �+ � U~ , � U~ T � %� �� � �� z� v� , �� �� � � �� � � �� � � �� k A �� " Ƿ _ C Է � � � � � - ! �� d X � � � � ��!� � � .� �� �, m �= Ű 4 * �� b X �� �, � � � �� � � �� � � �� �1 �1 � �� � � �� � � �1 � U| Q0 =1 � U| �� �, �, � � Ű Ű �� �, � U| T ` Q0 �� >2 � +� �� � � �� � � �� �2 �2 � �� � � �� �2 � U| Tv Q0 \2 � U| Tv �� �2 � Ib �� �� �� �2 �2 G �� $ " �� . , �2 � U| T} Q0 �2 � U| T} ;� � <� 8 6 I� E C U� � � V� U M c� ~ x n� � � o� � � 33 U| �/ � � U| T @0 � , U| T Qv $ &R0 �0 O U| T} Q3 �0 � g U| 2 � U| T~ Q~ R1 #3 � U| T~ Q~ R1 K3 U| T��Q��R1 �/ � U| Q} R1 A- � ! U| Ts �- � P U| T Q} X Y0 . � u U| T��QB 5. � � U| T Q} X$Yv e. � � Tv Q~ R2 �. � � U| Tv Q~ R2 �. � U| Tv �. � 2 U| T R0 1/ � W U| T��QB ]/ { U| T R} s/ � � U| T} �/ � � U| Ts Q %` �0 � U| Tv Q2 1 U| Tv Q2 �1 � ( U| Tv ;2 � F U| Tv �2 � d U| T} }3 ^F �3 � � U Pa Q} �3 � � U| T Q|�R2 4 � U| Q|�R2 �� �� E� Ч $� R� j� � x� � ;� Ƕ 4 ^ �\ � � � � � N : �� � � � � � � % $� q i /� � 0� � � �5 U~ �� �5 � Y �� �� � � �� 66 66 > �� �� � � C6 � U~ Tv Q0 6 � U~ Tv M4 � w U~ T| �4 � � U~ T| Qv $ &R0 �4 \ � U~ T��Q; 5 � � U�U 35 U~ T Q R1 �5 � % U~ �5 a B U~ Q0 u6 a U~ Q0 Τ Ӧ Ѻ �6 � �� � � g U �� � � � � � � ! � �@)� S O 5� n b 7 � U| X Y0 �7 � % U| Tv �7 � B U| R0 �7 � e Tv Q�@R2 8 � U| Tv Q2 8 � � U| (8 � � U| A8 � U| Q~ T8 ^F $� `8 N �s 4� � � A� � � M� Y� 1 ) f� W Q s� u m ~� � � �� � � �� 4 � �� �8 � Uv T; s� �8 �8 �� �� 1 / s� �8 �8 � �� ; 9 B� 9 D � i Z� G C N� Z V e� D f� q i �9 Uv T} �� ]9 � �� � � s� `9 `9 �� �� � � ̱ |9 � ѱ � � B� 9 9 �c Z� � � N� � � e� �9 f� � � �9 Uv �8 s � Uv T| Q �8 � � Uv T~ �8 � U�U 9 � Uv T| Qs $ &R} 39 � Uv T| Q ���# $ & R9 � L Uv T~ Qs $ &R0 w9 Uv T| Qs $ & �� C� �9 � �� S� � � `� $ m� H D z� ` Z �� | v �� � � �� � � �� O " �� � � �9 � U T; �� Q: I ï � � s� T: T: Y} �� � � Я u: � ѯ � B� y: y: Z Z� N� e� ~: f� % �: U �9 � : U T} �9 X U T~ : q U�U &: � � U T~ Q ���# $ & I: � � U T} Qs $ &R0 p: U T~ Q | s $ & ߯ �: $ �� � M E �� q m � � � �: � Z Uv T�T �: � r Uv �: U�U �� � �: % � � � � (� � � 5� � � �: � � Uv T�T �: � Uv �: U�U � ; p �� �� � � � ! � ` N $� ��~1� � � =� � � J� U� v l b� d � c� � � 0; � U~ T; �; � � U~ T �; s U~ T| �; � ( U~ T0 �; s F U~ T| < � ^ U < | U~ T| H< � � Us $ & k< � � U xa p< ^F Ш �� � �� p< o �� � � � � � � )� 6� , ( C� = ; �< � V Uv T�QQ0 �< � n U| �< � Uv Q| X Y0 � �� �< � �� � S E � � � )� � � 6� C� g Y P� � � [� � � �< _ ' U~ = � R Uv T~ Q 9` M= l Uv Q} x= � � Uv T| Q} R0 �= Uv T~ � �= � �� '� � � 4� � � A� N� < 6 [� X R h� v n u� � � �� � � �� ���� � � �= � s U~ T��Q0R0 9> � � U~ T �` Q0 G> � � U~ T} `> � � U~ T} Qs $ &R0 �> � U~ T| R2 �> � 6 U~ T| Q X2 �> T U~ T| �> t U~ Q�� ? � � U~ T| R2 ? � � U~ Q��R2 '? ^F �� ,� � �� 0? � � ! �� �� 1 + �� N J �� d ` ̮ { s خ t h ݮ � � N? � U} T; � `? � � � � k? ! U} T| s� n? n? m � �� � � �� �? $ �� � � �? ! U} Ts Q| s� �? �? n X �� � � \? ! v U} Ts �? s � U} Tv �? s � U} Tv �? ! � U} Ts Q0 �? � U} Tv �? U�U � M� ¥ �� � �? ~ ��" '� � � 4� � A� N� 4 0 [� G C g� � �! l� Z V �? � U| T; y� @ �! z� k i @ ! U| s� @ @ { " �� u s @ ! :" U| Ts /@ s X" U| Tv <@ ! {" U| Ts Q0 O@ �" U| Tv ^@ U�U �� `@ � �G$ �� � } í � � Э � � ݭ � � � � � �� � ?# �� x@ � U| T; � �@ �# � �@ ! U| Ts s� �@ �@ � �# �� �@ ! �# U| Ts �@ s �# U| Tv �@ ! $ U| Ts Q0 �@ 1$ U| Tv �@ U�U 8� �@ : ��$ H� 3 ' U� i a a� � � A �$ �$ Uv T�T A � �$ Uv A �$ U�U %A �$ �� i� �� 0A � ��& IJ � � Ѳ � � ݲ � G ? �� o g � � � � � � *� � � � � � 7� � �% <� � � YA � U| T; s� � ��% �� � � B� � �1& Z� � N� e� � f� * $ �A U| Tv B� � ��& Z� E A N� X T e� � f� m g �A U| T} gA ' �& U| Tv �A s �& U| Tv Q�� �A � U| T} Q~ R Xs �� ' � �� i� B � �|( y� � � �� � �� w c �� � � �� E 1 �� � � Ǵ � � Ҵ � � ߴ 8B _ �' U XB � �' Uv T Q U` �B �' Uv Q} �B �$ 6( U�UT�TQ�QR�RX�X' �Y �B � _( Uv T| Q} R0 �B Uv T�� |� C � ��) �� ( �� � � �� � �� l X �� � � ̳ 4! &! ٳ q! o! � �! y! � 8C _ ) U XC � G) Uv T Q o` �C g) Uv T| Q} �C �$ �) U�UT�TQ�QR�RX�X' �Y �C � �) Uv T| Q} R0 �C Uv T�� �� D � � 9 �� �! �! �� " �! �� �" �" �� �# �# �� j$ L$ ̸ % �$ ��~� & & � ��~�� @& 8& �� D � ��+ Ű ~& t& �� �& �& �� �D � T+ �� �& �& �� �& �& �� H H ?+ �� ' ' �� (' &' H � U~ Q0 5H � U~ �� �D �D � �+ Ű Ű �� �D � U~ T ` Q0 �� �E N 4, �� 2' 0' �� >' :' �� O' M' �E � , U~ Tv �E � U~ Tv Q0R0 3� v1 8� e' Y' C� �' �' N� �' �' [� �' �' h� >( <( t� W �, y� J( F( ]P U~ �� 0N b \I- �� �� g( Y( �� Q Q + ,- �� �� �( �( Q � U~ Q0 �P � U~ T��~ �� � / �� ��~ Ի �L �L 2 w�- �� �( �( � �( �( � �( �( M gF U��~T@Q1RAX � Y YM � . U~ R2 iM 9 �N a .. U~ Q0 |O a K. U~ Q0 �O a h. U~ Q0 �O � �. U~ �O a �. U~ Q0 &P a �. U~ Q0 FQ a �. U~ Q0 �R � �. U~ �R a U~ Q0 �F � 4/ U~ T��~Q R1 "G � T/ U~ T��~ uG � �/ U~ T��~Q ��~� $ &R0 �G �/ U~ R1 �I f �/ U~ Tv Q| R��~X��~ �I � 0 U~ Tv Q R��~X��~ #L 00 U~ T Q; �M |( i0 U~ Tv Q R��~X��~Ys �M � �0 U~ T} Q0 N a �0 U~ Q0 DN � �0 U~ wP �0 U~ T��~Q��~R1 �P f "1 U~ Tv Q| R��~X��~ �P ' \1 U~ Tv Q R��~X��~Ys �Q a U~ Q0 Q� � 3 V� �( �( c� ) ) p� ) ) }� 0) .) �� >) 8) �� ��~�� e) Y) �� � 2 �� �) �) �H � U~ T; s� :R � %62 �� �) �) I � _2 U~ T| X Y0 AI s }2 U~ T} VI � �2 U~ Ts oI � �2 U~ Ts Q R0 �I � �2 U~ Qv R2 !R � �2 U~ 7R � U~ �� 7R ;3 �� �) �) ι � 5 ӹ �) �) � �) �) � * * �� * * � W* E* � � �3 � �* �* �J � U~ T; s� �R � =%�3 �� �* �* �J � 4 U~ Tv R0 K s &4 U~ T} $K � D4 U~ Ts GK � m4 U~ Ts Q| R0 rK � �4 U~ �K �4 U~ Q2 �Q �4 U~ T} �Q �4 U~ �R � �4 U~ �R � U~ $� �R ,5 %� �* �* � � �6 � �* �* � + + $� �5 )� D+ 6+ 4� �5 5� x+ v+ O � U~ T< O U~ s� O 0 � �5 �� �+ �+ B� @ ;6 Z� �+ �+ N� �+ �+ e� @ f� �+ �+ SR U~ Tv JO � k6 U~ T| Q X$Yv jO �6 U~ Tv �Q � �6 U~ T| Q X$Y0 �Q � U~ Tv kE |( 7 U~ Tv Q R��~X��~Ys �E � 07 T| Q��~R2 PF � [7 U~ Tv Q %` �F � y7 U~ Tv �G f �7 U~ Tv Q| R��~X��~ �H o �7 U T �` �H ' 8 U~ Tv Q R��~Ys J � "8 U~ Tv DJ � V8 U~ Tv Q R��~X��~ nJ f �8 U~ Tv Q| R��~ �K � �8 U~ Tv �Q ^F R � �8 U �` T �R � �8 U �a Q �R � U~ Tv Q~�R2 �� �� S � ��; �� �+ �+ �� ;, ', �� �, �, �� �, �, ŵ �, �, ҵ 8- 4- ߵ S- G- � �- ~- �� �- �- � �- �- � *. . :S � �9 U~ Tv �S � : U~ Tv Q| $ &R0 �S � L: U~ Tv Q ��� $ &R0 �S �) v: U~ T Q} Xs ,T � �: U~ Tv Q ���1 $ &R0 JT � �: U~ Tv Q ��� $ &R0 �T �: U�UX�� �T � 9; U �a T �0��0)( �#sQ| �T � x; U b T �0��0)( �#sQ��� �T � �; U pb T| U � U 8b T| "� U s ��? /� \. T. <� �. |. H� T� �. �. `� �. �. m� Z/ R/ �� K � 7< ǻ z� V �? � }/ y/ �� �/ �/ �� �/ �/ �� �/ �/ �� 0 �/ �� ��ͫ <0 60 Ӱ �U k � = � V0 R0 � i0 e0 k �� z0 x0 � �0 �0 � �V t Us ګ V 7 �= ߫ �0 �0 )V V= Us Tv Q��� BV #9 �= Us T~ Q R��X} PV �? Us T s� ]V ]V �= �� �0 �0 �� �V { � z> �� �0 �0 �� �0 �0 �� �W � �_> �� �0 �0 �� �0 �0 �W � Us Tv Q0 +X � Us Tv �U � �> U �b V �? �> Uv T.Q�� lV �> Us Tv 5W � ? Us T Q��R2 `W >? Us T~ Q R0X��Y} �W � h? Us T �` Q0 �W #9 Us T~ R��X} �� � �? �� 1 �0 tX ^F �X �? U�TT �` � ө B� � �X ] ��D � 1 1 %� F1 <1 1� =� v1 p1 I� �1 �1 V� �1 �1 �� � < c@ ǻ c� � PD h� �1 �1 u� 2 2 �� 82 ,2 �� m2 c2 �� �2 �2 �� ���� �2 �2 Ӱ Y � �5A � �2 �2 � �2 �2 � �� �2 �2 � 3 3 � Y t Us �� �Y 8 �A Ƭ 13 -3 �Y �A Us T��Q��� �Y #9 �A Us T Q~ R0X��� �Y �? Us T~ s� �Y �Y �B �� B3 @3 � � �C � d3 J3 �� � NB �� �3 �3 �[ Us � +[ uB � �3 �3 s� 2[ 2[ ��B �� �3 �3 �Z �D �B Us �Z �D �B Us [ C Us T �` Q2 P[ �D C Us `[ �D 3C Us �[ \C Us TvQvR1 �[ �C Us Tv Qv R1 �[ � U (c =Y � �C U �b �Y �? �C U��T.Q�� �Y D Us Tv BZ � 0D Us T} Q��R2 u[ #9 Us T R0 Ӭ SZ ; �D ج �3 �3 �Z �) Us T Q} (� � �D )� �3 �3 �[ ^F �[ �? U�TT �` � m� I� [� �� �[ s �1F ɪ 4 4 ֪ A4 =4 � Y4 S4 � q4 o4 �� �4 �4 � �4 �4 � �` �"\ 1F �E U ��Tv Q �` R �` X �` ;\ 6F �E Uv T �` Q �X Q\ 6F F Uv T a Q U c\ ;F U�U �� y� b� =� � {� � � � !� � v � >�" � �& #� #� % #�3 #�3 #� s & #&) * ( % ?int e e" *1 #� 7 �8 � �1 � �1 � �8 \; �1 �% �8 ! �} �. �e :" �} *, �} @ � � } _ � } ^+ �} �9 �!} 8 . #� 8 � @� � O� `+ l ,, � � �8 %� � �7 � 8 � 8 j0 � � <0 � � " #�3 8 � 8 #� P 1 [ � % ? � e � � ! # ? � � O � �( " � hG #� p�' $� x�) '� � � � 8 � � , l � � 8 ? � � � *!� W � � u F , Y g" q �1 6 } F 8 � � { �6 * � ! e @� "� H F � 8 D( F { 3& � e ; � �; � %8� x4 :� �$ ;� %? � A e /" B e # C� %GM x4 I� �$ J� # K� % O� x4 Q� �$ R� 7 S e ; T� ) U� %a� c � �' d � ^� > e� � gq % Y �3 [ � � ]R T* h � %l3 �< n} �% o e %td � v � (3 w e x1 p3� � 5� � <� >2 D� ,_rt L �2 VM �. i� �< p �7 y3 e � 8 %�$ ) �) & e d ( e t * e t 0 e �/ { d W |� : (E e . �8 .W \ e p p p u A#� � % , �� �/ �} u; � � � 8 � 8 � � f- � � � � � � M/ � � � �1 �b [4 �} R- �� �1 �� � �{ g �% � l } }6 � � �: ` � q q � � � � � �& � � � ( � � �3 7 % % / � 9 9 C � M � W � a � k u b � � � � � � � � * � > � o �1 � � !� { �0 � � 0 88 � @ E9 � P @ 8 P 8 ` 8 �: �{ � � 8 Z: �\ >9 � �. $ � z ,� �8 -� � / � & 0 � t 2 e $ 4 � (� 9 � 0�0 =� 8�" ? @ J� H3, K� X" L� h�+ Y\ x " l 8 )tm 8 x e � e } e S e � e C0 e x1 e x e g( e m7 } (� � 0 50 I �5 . �7 E � e p5 � b� � d . � e E K fe � ge �( h E � �� �7 . 1: E e J, . C D �6 F . - G E �: He 8 ' 8 � *DIR 3 �1 $IV o} 8 $UV p8 $NV �^ #� #� b f t l $OP h � )op (�[ � ��/ y ��/ �ZF O ��D �& �G/ � �G/ �0 �G/ �9 �G/ �& �G/ -7 �G/ �G/ �. �G/ g1 �</ "� �</ # $COP i g 4cop X �� � ��/ y ��/ �ZF O ��D !�& �G/ !� �G/ !�0 �G/ !�9 �G/ !�& �G/ !-7 �G/ ! �G/ !�. �G/ g1 �</ "� �</ # �/ $ ��D (8 � . 0� � i/ 8 � i/ <�" ��M @�* � �M H�. � i/ P � o � `�� � ��/ y ��/ �ZF O ��D �& �G/ � �G/ �0 �G/ �9 �G/ �& �G/ -7 �G/ �G/ �. �G/ g1 �</ "� �</ #� � �/ (�. � �/ 0N& �D 8�0 i/ @P dF H4 �F Pc) �/ X s � Z P� � ��/ y ��/ �ZF O ��D !�& �G/ !� �G/ !�0 �G/ !�9 �G/ !�& �G/ !-7 �G/ ! �G/ !�. �G/ g1 �</ "� �</ #� � �/ (�. � �/ 0j � �/ 8] � �/ @� � �/ H $ ~ - :� �r# T+ #�/ -Iop $�/ ", %�/ '�/ 9 (�/ [ *ZY (� ,S/ 0r -S/ 4�9 /_Y 8� 0S/ @� 1S/ D� 3�/ H 5 4\ P0 5\ X�& 6\ `� 8i/ h� :_Y pC7 <_Y x =_Y �S A</ �c CH ��- E�/ �w! H_F ��0 KI= � LI= �B+ N�/ �g8 O�/ �77 ^G/ �� h</ ��; i</ � 1 j�/ � & v</ �7* }1/ �]8 ��/ ��! ��/ �L+ ��P � ��/ ��, �dY �}0 ��/ � D8 �8 � ��/ - ��/ 5 �I= [ �iY { �nY ( ;$ ��D 0 � �# 8 �# P � �# h '! �# � d' ��. � 3 ��. �5ISv ϩ/ � � �sY �, ��/ 5Ina �l � �� �" ��/ � � ��/ �5Irs ��/ � " ��/ � ? ��/ � ��/ � u �� � : ��/ � p8 ��/ � �4 ��/ �� �/ �m �N w �N �, �M � �/ �Z3 C2 �� �/ R4 �/ � �/ -& �/ �/ �5 . (7 l 0D) G/ 876 ?</ :� A�/ ;� B�/ <m. C�/ =�< D�/ >� H ?� K�/ @� NxY HT e�X x~ }�X �� � Y ��0 �E ��: �. �� �i/ �f4 �i/ �$ �e �; �e �E �E �$ ��/ �� ��/ ��1 ��/ �p" �. ��2 �� �� ��/ ��< ��/ � ��/ �� ��Y ��3 �� � ��/ � ��/ ��/ � ��/ � ��/ � ��/ � ��/ � ��/ � �. { ��/ } �h � �S/ (� �S/ , �S/ 05 �e 4� ��Y 8� ��/ @> ��/ H ��/ P�0 ��/ X" ��/ `m; ��/ h�4 ��/ p�) ��/ x ��/ ��9 ��/ �� ��/ �4 ��/ ��1 ��/ �� ��/ �� ��Y � ��/ �A ��/ �$8 ��/ �W ��/ �� ��/ �� ��/ �� ��/ �1 ��/ K5 ��/ � �. != !8 �/ � �/ (�% �/ 0� �/ 8M% �P @�6 e H� e LP) . P� �/ X8 �/ `�! �/ hc, e pS S/ t+< �/ x�2 �/ yx( G/ z� e || S/ � 7 #S/ �13 $�Y �[- 3�/ �T0 6�Y �� 8[ �� :!8 �� ;�D � <�D �< =�D �' E!8 �- Fe f Ii/ $! K�/ (� L�/ )d M�/ *- N�/ +�< QP ,n RP 0F SD 4x/ TD 8BIan Ui/ <}; Xi/ @�" `i/ D�! ci/ H�+ di/ Lk/ eE P� i. X� kr0 `l n;0 h� oG0 p q�Y x , sz/ �� ui/ �� �W I3 ��/ �0 �S/ N ��D ��D f* ��D ( B: ��D 0 ��D 8 g6 ��Y @ �5 �. � o �t � w �t � 5 �i/ � E2 �</ � < ��/ � �4 �</ � �+ ��/ � ;3 �. � �1 �t � F< �. � & �t � p1 ��/ � �6 ��/ � ~ �oX � +( ��/ � | �? � ] �e � �' ��/ � w& ��/ � �/ �. � �3 ��/ _ �� �2 ��/ +; ��/ 0 ��/ " ��/ �6 ��Y ( W" ��/ 0 4 �� 8 w �/ @ �1 �/ H �Y P � �D X � �D ` B1 �Y h �* �/ p �/ x + $0 � &+ �Y � A �Y � � �/ � �( �/ � f9 } � H #�W � �' $�W � �! -�W � �& 1 X � �" 4,X � � 7RX � � :�/ � �$ @�/ � � C�/ � � E�/ � �1 G�Y w< K�Y � M�X s6 PY X i: Y�Y ` � Ze h S b�W p t o�Y � i< z�D � � |l � � ��D � 6 ��Y � �) ��/ � � ��/ � �- ��/ � ��/ � ^2 ��/ � d ��/ � ��/ � V ��/ < ��/ � ��/ % ��/ � ��/ � ��/ ( �9 ��/ 0 � ��/ 8 ' ��/ @ u ��/ H �8 ��/ P "* ��/ X �9 �Z ` v: �Z � �; ��/ `n ��/ h�, ��/ p@ ��/ x4 ��/ ��1 ��/ ��( ��/ ��) ��/ ��7 ��/ �� ��/ ��6 ��/ �� �K ��2 �K ��4 �K � $SV � %# # )sv �e# �) �� �% �i/ �i/ � ��1 $AV � p# )av ��# �) ��3 �% �i/ �i/ � �H3 $HV � �# )hv ��# �) �94 �% �i/ �i/ � ��3 $CV � $ �# )cv �K$ �) �C3 �% �i/ �i/ � ��2 0 � X$ � �$ �) �6 �% i/ i/ � �4 $GP � �$ )gp P V% �7 �/ q! �D %0 !8 d$ i/ % i/ �2 �/ �/ �/ (:1 !8 0@ �/ 8u0 i/ �$ i/ u% D7 H $GV � a% )gv �% �) ��2 �% �i/ �i/ � �R2 4io �% �) �4 �% i/ i/ � >4 @ � �% h n& �' r�Q R7 h ��& = � </ � </ K0 � G/ , � S/ S/ 0' S/ �, �P = I= \ � S/ (* kP 0 �& � �& � 0 <' A& o7 � �R 4 G/ 8< 8 �! </ L \ � �/ �/ . ( $XPV � H' 4xpv ��' �+ ��/ ^$ �I7 * �l �t7 $ � �' � ( �' �+ �/ ^$ I7 * l �7 �8 7 � � �' 0 `( �+ �/ ^$ I7 * l �7 �8 7 � �6 ( R � m( %; (! �( �+ ! �/ ^$ ! I7 Y/ ! \ �8 ! \ �% ! �/ � � �( : "� ) �+ "� �/ ^$ "�I7 �) "�l � "�l 8 � ) � 0 ;{) �+ <�/ ^$ <I7 * <l <�7 �8 =7 � >�6 ( 6 � �) @< h# L* �+ #�/ ^$ #I7 * #l #GE �* #�/ �- #iE ( #�E 0V #�E 8{$ #. @� #�E H1 #!8 P�3 #i/ X�3 #8 \�2 #S/ ` � Y* � � ed+ �+ f�/ ^$ fI7 * fl f08 �8 g7 � iM2 (�< vT8 0;( x 8 8H y 8 @�' z 8 H�6 { . P}, | �/ X� } . ` 8 ~ �/ h*1 . p] � �/ x / � 8 �> � </ � �& � q+ n @ �+ � oR N8 oR � �R �4 oR �3 oR �: �R (y3 �R 0� oR 8 $ANY � �+ Cany ��, � � � ��/ '5 ��/ T ��/ � ��/ � ��/ ��/ � �. � �E R3 � S/ � i/ n � 8 ) � H 6 � } h+ � �/ � �/ f5 � �/ �0 y- � z�W �5 {p G | � j � %- �/ 0�- �% ��W � � H � � H � ��W { ��W � ��W ( � � �- 7 ( ��- �, ��/ �! �H / ��/ ��/ � ��/ L � �- � $ 9. Z $ \ A $&�D V $' i/ �- $( i/ $PAD � e# � � R. � ($+�. � $, \ � $-E � $. \ 4 $/�D � $0 i/ [ � �. N 0$L1/ �< $M. �0 $M�/ � $M%E . $Mi/ �* $Mi/ �% $Mi/ 8 $Me $�( $M</ (2 $M</ ) *I8 %�? *U8 %� *U16 %�% *I32 %�e S/ ;S/ *U32 %�1 i/ ;i/ g %� i/ � � ) (�/ � �/ # �/ �/ �/ V% e# �/ �# ~ #� (�/ �/ � �/ 8 0 8 &<0 G H &>$0 0 � &Q 60 � � '45 f '5S0 X0 (m0 e m0 � �/ & ';;0 3�* (��0 a5 (� S/ :% (� . 9% (� �/ * (� �/ �* (�~0 61 �91 D" p - 64 � �$ 0 � � � � � � � 09 ��0 91 *HE �U1 )he " �1 T1 "$ C2 � "% D7 Y ")LK *HEK ��1 )hek "-�1 + ".i/ - "/S/ 1 "5�/ �>2 M �. � �8 �H I �S � ��/ �7 ��/ 3 �>2 �H2 � �M2 C2 J1 �$ 0 ��2 M �. � �8 �H I �S � ��/ �7 ��/ 3 �>2 �H2 � �M2 ) �C3 M �. � �8 �H I �S � ��/ �7 ��/ 3 �>2 �H2 � �M2 {) ��3 M �. � �8 �H I �S � ��/ �7 ��/ 3 �>2 �H2 � �M2 `( �94 M �. � �8 �H I �S � ��/ �7 ��/ 3 �>2 �H2 � �M2 �( " �4 M . � 8 H I S � �/ �7 �/ 3 >2 H2 � M2 L* " A5 M . � 8 H I S � �/ �7 �/ 3 >2 H2 � M2 ]' �)n�6 �+ )o�/ ^$ )oI7 * )ol )o�9 �! )p!n: �7 )q �9 (�$ )r �/ 0�7 )x i/ 8�% )y i/ <� )z \ @5 ){ \ H� )| l P 5 ) s: X=. )� � `/5 )� i/ h� )� i/ l� )�x: p� )� E x) )� i/ �D )�i/ ( )�i/ $� )� . � )��/ �)' )� \ ��; )� \ �� )� \ �= )� \ � )� !8 � A5 7�' �7 � � S +0 � �/ �, � / �: � �/ 7�8 �D7 ?' � 8 J- � H �: � D7 � � �/ �1 7�< �o7 � � o7 ~" � l �& " ��7 � �l � ��6 " �7 � l � �6 " �7 � l � �6 " <8 � <l � <�6 F. A i/ (!8 �/ !8 �# 8 �- " fT8 � fl � f�6 " sx8 �$ tx8 6 u � ' i )�8 �! )</ � ) </ A- ) G/ i ) }8 @ ()( 9 � )) \ �" )* \ � )+ �/ � ), �/ � )- \ � �)/59 ^1 )0 </ x; )1 59 �8 E9 8 . )<z9 )= \ -end )> \ � )E \ . )FE9 K$ �9 )o�9 � )ol � )o�6 �! h)�i: �7 )��: )�; )�S; 4 )�l; )��; U< )��; (# )��; 0�9 )��; 8� )�< @& )�7< H~ )�l; P�4 )�Z< X�7 )��< ` �9 i: 9 z9 ]' )�A5 j )��: �/ )� E � )��: \ �* )��: �9 �: �/ �/ i/ �: S/ ; �/ �9 . . . \ �/ � i/ �: . N; �/ �9 �/ � . . u/ N; �: ; �/ l; �/ �9 X; (�; �/ �9 q; (�; �/ �9 _/ �/ �; (�; �/ �9 _/ �; # �; �; S/ �; �/ �9 �; _/ �; �/ < �/ �9 �/ �/ u/ �; �/ 7< �/ �9 �; u/ < � U< �/ �9 U< �- << �9 �< �/ �/ e �/ n: �9 �< i/ i/ �/ _< X)� D= rex )� D= �0 )�I= )��/ � )�. )' )� l �; )� l (� )� l 0sv )��/ 8k% )�o7 @pos )� \ H� )� </ P }: � r- )��< )� �= {- )� �= [ )� �= � )� 7> + )� . N= | �)��= g )� e � )� . � )� . sr0 )� �? u )w�C �= :\ x)�7> V )�zD T9 )�7> h� )�"7> p �= q+ )�[= � )� S/ )�o> w7 )� �= )� �> w7 )� �= � )� i/ ) )� i/ cp )�I> )�? w7 )� �= � )� i/ ) )� i/ cp ) I> � )? �8 @)�? w7 ) �= � ) i/ ) ) i/ cp ) I> * ) i/ � ) �/ ; )�? me )? (� ) �? 0� ) i/ 8w ) G/ < ) G/ > G/ </ @)G@ w7 ) �= � ) �= \* ) $�= � ) �9 cp ) I> ;: ) I> $� ) i/ (B )!? 0� )". 8 0)%�@ w7 )' �= 02 )( S/ [, )) S/ � )*</ )+. end ),. me )-? ( )0�@ w7 )2 �= / )3 �= � )4 �/ ; )5 . )8A val )9 e 8)>�A w7 )@ �= � )A �= me )B? B )C? cp )DI> � )E �/ $� )F e (� )I e ,� )J . 0 ()M B w7 )O �= /$ )P �= cp )QI> ;: )RI> | )S . #2 )T S/ � )U S/ $ `)X�B w7 )Z �= c1 )[ e c2 )[e cp )\I> � )] i/ ) )^ i/ �+ )_ S/ � )` S/ � )a �/ $A )b? (B )b? 0me )c? 8C6 )d�B @� )e�B N </ �B 8 h)h�C � )i i/ cp )jI> � )k i/ ) )l i/ c1 )m e c2 )me �/ )n . h )o . � )p e (min )q e ,max )qe 0A )r? 8B )r? @C6 )s�B H� )t�B V "h)�mD z+ )�<> {- )� N= 0yes )�V> � )� o> � )�> �' )? )#�? 0) ).G@ �) )6�@ m ):�@ 4$ )KA �7 )V�A )f B < )u�B | )x�= mD �D 8 \ )��= D *D8 �% $\ %$!�D � $"�D � $# �D � $$ �D E. 9. $ E R5 $ E � $%E �D �D E �. $MGE ]. $M�/ �! $M!8 #iE � #l � #�6 #�E * #�/ � #�+ #�E M #�/ n #&8 #�E �* #�/ �3 #D7 #�E � #+8 #� � ?F : ��D ,sv ��/ ,iv �8 ,uv �H ,pv �. � �\ k3 ��E �/ ZF �/ KF ?F "�F �/ �5 �D �" �/ " �F � �/ i& �D �! 0+1"G * +3 . �$ +4 . 72 +6 � f7 +7 � k +8 . +9 . 3 +: . ( O ,*dG �& ,, . �! ,- . " ,. � �2 ,/ E <2. �-H�G �' -M�G -V�G � � -[�G �+ -b�G F -i8 � -n�G 8 �G 18 8 �G 18 � 8 �G 18 � 8 H 18 �w �9 H.+�H H .- . � .. . 2 ./} � .0} � .1} � .2} (D/ .4} 0 .6} 8e; .88 @ D�/� K M /�. � /� t /�K � /�. 5 /� t � /�"G (� /�. H4 /� t P� /� K X� /�I `� /�. �� /� t �� /�!K ��0 /�e �� /�. �B /� t �'- /� ��* /�. �� /� t �G' /�&K �4+ /�e ��7 /�� ��8 /�. � /� t � /�+K 7 /��F & /�. H�5 /� t P� /�0K X| /�� `�$ /�. ��) /� t ��; /�5K �| /� H �� /�. �� /� t �� /�:K �" / l �B* / l 0�( /". h_ /# t p+ /'. x�: /( t ��( /, e � dG "G I � �F � H 1 /-�H "&nK b/ "'�/ "( t �% "E�K � "F �K �/ "G� � "H G/ �< "I G/ + "J i/ nK �/ �K �/ �/ i/ �K �' H"MpL �< "O�/ � "S�/ ": "T�/ &9 "U i/ � "V i/ m "WpL -isa "X�/ (0! "Y�/ 0� "Z!8 8 "[ i/ @ �K 3�* "g�L � "h D7 < "i �L D7 9 8"l!M q "muL � "n �/ U "o C2 x "p S/ Z& "x S/ ~' "y!M � "{i/ (J "|i/ ,� "i/ 0 �K u � �M Q9 !�M �4 "� ` # e ��9 $ �/ �� %G/ �o2 &\ � &M � )&M � � �M , l �M �M W% 0 SN � T �/ < US/ o W �D cv X !8 .* Z S/ �8 [ �/ ( b 0 `vN � a �/ < bS/ o d �D cv e !8 gv g �/ �2 h �/ ( 8 ��N � � �/ < �S/ � � �/ �% � �/ = � �/ cv � !8 (Q. ��N 0 �M " �O 0svp � �/ 0gv � �/ �4O ary � �/ ix � 8 �ZO �- � S/ ix � 8 ��O cur � 8 end � 8 ��O cur � �/ end � �/ " ��O 0ary �O T �4O �/ �ZO �4 ��O �9 0 �;P � ;P �$ ��N �) ��/ �. ��O � � �D ( � . �kP C ��/ m* � �/ "8 �P u �M �1 N � vN 2 �O �& @P [ 28 X .�Q o4 / </ 0 </ � 1 G/ � 2 S/ 4 \ �+ 5 \ s 6 . � 7 �/ R, 8 �/ ($ 9 . 0$ : . 8U ; . @� < � H� =�9 P "h o�Q � p& /8 q�P �, 8 ?R Q �/ � ?R 0 DR 3 DR � S/ � S/ $Z S/ (� S/ ,� S/ 0 �% �Q �& !�Q e oR �/ �/ o7 VR i/ �R �/ �/ o7 tR e �R �/ �/ o7 �/ � S/ �R e �R �/ o7 U< �R d+ %0 S -val 0 �0 n 0 R � 0 S/ � 0 !8 � 0�R � (0{S � 0{S � 0 �/ M" 0 . �8 0 . � 0 �/ ,S - 0 ,S <�9 �0"OW 0&OW (/ 0'�0 && 0(e � 0+e T 0-TW � 0.TW -ps 0/TW (� 00e 0� 04 S/ 4p, 05 S/ 8 06 S/ < 07 . @� 08 . H�+ 09 </ PS$ 0: </ Qa 0< </ RY) 0= �/ SD$ 0>�/ T* 0? </ Ue 0@ �/ X�. 0A �/ ` 0B �/ h� 0C G/ p�" 0D G/ rP 0E S/ t� 0F �/ x 0G S/ �� 0H S/ �� 0I H �N: 0J H ��; 0K�/ �� 0L </ � 0M G/ � % 0N S/ ��, 0O �/ ��* 0P �/ �� 0QYW �� 0R �/ �P" 0S . �8 0V . �|8 0W . � 0X . ��; 0Y . � 0Z . �o 0[ . �� 0` / �6- 0a G/ ��" 0b </ �. 0c </ � �( 0d �/ t 0e M2 �; 0f �/ E 0h ^W � 0i nW @ 5 0j </ T �" 0k </ U �, 0l </ V � 0m </ W 6 0n �P X T 0o ` _: 0p / ` s' 0q / d �2 0tH h < 0uH p � 0v8 x � 0w�/ y * 0y�/ zZ! 0{G/ �� 0|G/ �] 0}G/ ��. 0~G/ � �S S �S �0 nW 8 S/ ~W 8 �9 0�S �, �W � �W _ ��W � ��/ T9 �$�W � �$�W �W � &�W �W e �W �/ @ ' X X ( X �/ �/ � (�W 85 *9X >X �/ RX �/ �/ +_X dX (oX �/ E ! 1 y�X � � �4 6! �. �+ F! 9 H �X pad �X # �X 8 � &�X �X (�X �/ �/ :&8 � >�X �3 B_X i IMY fn J �/ ptr K � 1 L#Y �+ S/ IR �D mD ~W . �Y 8 � e 8 �Y 8 MY i/ � �Y 8 . �Y 8 - �/ ?K )0 <' � � �/ �Y 8 " 8 Z 8 �/ Z 8 61 1>�Z � � � " � � � �- ~ W( � �: � x* B4 3 0 �& - 0 �( / S' � Y9 �+ ( ;, 8 �5 61 2�\ � v5 X E �5 �4 _ � #7 �! [ � w � � g i �* � � h �* � � Q ^ �( �! !- "n #p( $� %� &�6 'O( (b ),6 * +6& ,/ -Q .�% /P 0�% 1b0 2� 3a0 4� 5 6�) 7 8�) 9! :�% ;�0 <�0 =� >� ?% @L; A� B% C\6 DA E� F G` H�/ II; JK K FV8 1 3H�\ �. � � � 3HA�\ 8 ] 8 0 &a% 3j �\ �1 3qV] �/ 3r� � 3st] t 3t�] �6 3u�] ] �/ t] �/ �/ �/ [] �/ �] �/ �/ �/ y] �/ �] �/ �/ �/ �] V] �] 8 �] &� 3v�] '� � �] �/ '�. N�] �/ '< 0 ^ �/ '' � ^ �/ 4� �/ ?^ �/ �/ S/ �' 47 �/ [^ �/ �/ * 4dS/ |^ �/ �/ d/ B; 5�t �^ � 'O �^ �/ �/ � y _/ '�- �^ �/ �/ �/ _/ �; 4��/ �^ �/ C2 �$ 4� l _ �/ �/ K6 4� l ._ �/ �/ �6 4�C2 O_ �/ �/ S/ &4 4��/ p_ �/ �/ C2 ' 4�S/ �_ �/ �/ m$ 4 �/ �_ �/ �/ \ �/ G�/ 4��_ �/ �/ \ H 4��/ �_ � 2 '�2 �` �/ �/ �/ _/ '� u #` �/ �/ u/ � 4��/ D` �/ � S/ 79 5N. `` � � � 4��/ �` �/ �/ 91 t 4^S/ �` �/ � S/ a! 4} �/ �` �/ �/ �/ \ �! 4�_Y �` �/ � 4�/ a �/ �/ � S/ q9 4� 8 &a �/ �/ _/ � 4 S/ Ba �/ �/ 8X 5� e ]a � � � 4 e ya �/ �/ �, 4< �/ �a �/ �/ � 4� e �a �/ �/ // 49 �/ �a �/ �/ � 8� 4��/ �a �/ �/ \ S/ �: 4\ b �/ �/ ' l %b � a 4k �/ Ab �/ C ' ]b �/ �/ �/ � 4s �/ ~b �/ � y $ 4n � �b t � 4^ �/ �b �/ E1 �) 4� �/ �b �/ �/ S/ 8) 4�e �b �/ �/ E 4o� #c �/ �/ � S/ l �/ u/ �: 4� �/ ?c �/ �/ 9 4� �/ `c �/ � y 'o *wc �/ �/ 8� 5[� �c p e t �4 4� . �c �/ �/ �M _/ = ��c � 2 =�5 ��c �c � $ �c 'B &d �/ _/ G 4� !8 'd �/ � �X � 4(S/ Id u/ � � 2 I� 6��d 6��/ cv 6�!8 ax 6� S/ �) 6� �/ sp 6� �/ � 6� S/ 8 6�� 9p) 6~�e 6~�/ cv 6~!8 sp 6� �/ ax 6� S/ �) 6� �/ � 6� S/ �e �% 6��/ �3 6��/ � 6��/ � 6��/ �! 3� e len 3� l str 3� . ye av 3� �/ p_ 3� - 6�C 9�8 6:�f 6:�/ cv 6:!8 sp 6< �/ ax 6< S/ �) 6< �/ � 6< S/ �f �% 6@�/ �3 6B�/ � 6D�/ �! 3� e n 3� e len 3� l str 3� . `f av 3� �/ sf � 3��/ �f sp 3� �/ �f X 3� _Y p_ 3�� p_ 3�� - 6yC �: � �/ �f 3� �/ sv 3�(�/ � 3�0�/ _ � �/ 3g 3� �/ sv 3�)�/ � 3�1�/ 2 � �/ �g 3� �/ + 3�&�/ � 3�0�/ V 3� �/ he 3� C2 �g p_ 3�� p_ 3� � ?% u �/ h 3u�/ + 3u$�/ � 3u.�/ V 3v �/ he 3w C2 h p_ 3v� p_ 3{ � �7 h �/ �h 3h�/ + 3h$�/ � 3h.�/ V 3i �/ he 3j C2 wh p_ 3i� �h p_ 3m � p_ 3n � � b �/ �h 3b�/ k) 3b$�/ � 3b.�/ C P �/ li 3P �/ k) 3P'�/ � 3P1�/ svp 3Q �/ V 3R �/ -. 3S S/ i 3SS/ Ki p_ 3R� ]i p_ 3Y� p_ 3Z� � J �/ �i 3J�/ k) 3J#�/ � 3J-�/ �- �/ 5j 3�/ k) 3$�/ � 3.�/ svp 3 �/ t3 3 �/ � 3�/ -. 3 S/ i 3S/ k 3 l M 3 . �' � e `j 3��/ �/ 3�,� �/ � e �j 3� �/ sv 3�&�/ key 3�� len 3�_/ , 3� �/ � �/ �k 3��/ sv 3�#�/ av 3�+�/ � 3�3�/ svp 3� �/ a 3� �/ i 3� S/ -. 3�S/ 5k p_ 3� � Gk p_ 3�� Yk p_ 3�� kk p_ 3�� }k p_ 3�� p_ 3� � �+ � �/ �k 3��/ key 3�%. 9; 3�0. p 3� �/ svp 3� �/ �5 �l l key 3�(. ap 3�l tmp 3�] ] C � e Al a 3� p b 3�/p � ��\ m 3� �/ sv 3�)�/ key 3�3. � 3�<�/ V 3�G�/ �! 3�Se av 3� �/ �$ 3� �/ � 3� �\ �l p_ 3�� �l p_ 3�� �l p_ 3�� p_ 3�� c w�\ �m 3w�/ sv 3w#�/ key 3w-. � 3w6�/ V 3wA�/ �! 3wMe a 3xl S 3y �/ � 3z �\ � S�\ �m 3S�/ �% 3S!�/ key 3S-. � 3S6�/ V 3SA�/ a 3Tl S 3U �/ �- 2�\ zn 32�/ �% 32!�/ key 32-. � 326�/ V 32A�/ �! 32Me a 33l S 34 �/ � 35 �\ { �/ �n 3 "�/ str 3 4� len 3 =S/ 3 �n av 3 �/ buf 3 . b 3 . �8 3 e p_ 3 � 8 o 8 ? �6 � �/ �o 3��/ �% 3� �/ �5 3�*�/ � 3�8�/ �! 3�Ce � 3� �/ key 3� �/ svp 3� �/ V 3� S/ i 3�S/ -. 3�S/ �$ � �/ Tp 3��/ � 3�#S/ sp 3��/ � 3� �/ av 3� �/ 9 3� �/ sv 3� �/ i 3� S/ 2p p_ 3�� Dp p_ 3� � p_ 3�� y � �/ �p 3��/ S 3�#�/ � 3�-�/ sp 3��/ svp 3� �/ � 3� S/ i 3� S/ X 3�_Y 9.% 3v q 3v�/ err 3v#�/ P 3z �/ � � �/ r 3��/ �% 3� �/ � 3�'�/ � 3�3�/ � 3�=�/ �! 3�He sp 3��/ svp 3� �/ � 3��/ w 3� �/ . 3� �/ T 3� l key 3� . V 3� . �+ 3�/ gv 3�/ � 3 S/ i 3 S/ X 3_Y .m 3� �/ Nt 3��/ �% 3� �/ � 3�&�/ � 3�2�/ �! 3�<e +sp 3��/ &� 3� l &t3 3� . &V 3� �/ & 3� S/ �r &\ 3��/ &w 3��/ �r +p_ 3� � +p_ 3� � p_ 3 � [s � 3 �/ �+ 3 �/ 1 3 �/ t 3 . i 3 S/ 7 3 l svp 3 �/ Ls p_ 3 $� p_ 3%� �s � 31 �/ �+ 32 �/ <- 33 �/ i 34 S/ svp 35 �/ �s p_ 31$� p_ 3=%� $t n 3IS/ i 3IS/ svp 3J�/ �+ 3K�/ gv 3L�/ t X 3S_Y � 3^Nt svp 3��/ �7 3� �/ len 3� S/ 8 ^t 8 @ .X7 3��\ �t 3� �/ �% 3�'�/ � 3�1�/ � 3�=�/ V 3�H�/ &T 3� l +key 3� . &� 3� �/ JZ 7� u 7��/ /sv 7� �/ +rc 7�i/ . 7��/ u /sv 7��/ .� 7��/ Du 7� �/ /sv 7��/ .� 7�S/ au 7��/ K 83e �u /__s 833 /__n 83t o 83� 2 L� 9� 8 9p � 9)p T; 98t +. 9Ht � 9J +__l 9 t +__u 9t &�2 9t +__p 9p &a 9e I ~ H} 1�B 4 1�B H} . 1 .1@z 1U 1R�BX!YW 1 1 1R�BUX!YW 4 1 4 1 H } 1UX YW H}� 1U 1R�BX!Y!�W! H}� 1 U H} 1R�BUX Y W .1 1 I �~ % 1R�BUX YW 1R�BUX Y W 1X Y W . ?<n !. ?<n: ; : ; 9 I8 : ;9 I8 : ;9 I8 I !I ( 4 : ;9 I : ; 9 I : ;9 I : ;9 I 4 : ;9 I : ; 9 I : ; 9 I8 : ;9 I8 : ;9 I .?: ;9 'I< I : ; 9 & I ! I/ 7 I : ;9 : ; 9 I k .:!3;9 'I 'I : ;9 I : ; 9 : ; 9 I : ;9 < ! : ;9!I k " : ;9! #$ > $ :!;9 I % : ; 9 &4 : ; 9 I '.?:!4;9 '< (' ) : ; 9! * : ; 9 I +4 : ; 9 I , : ; 9 I - : ; 9 I8 ..: ; 9 'I / : ; 9 I 0 : ;9 I 1! I/ 2 3 !: ; 9! 4 : ;9! 5 :! ; 9!I8 6>! !I: ; 9 7 !:! ;9! 8.?: ; 9 'I< 9.: ;9 ' : : ;9 ;5 I < : ; 9 =.?:!4;9!'�< >% ?$ > @ A& B : ;9 I8 C : ;9 D : ;9 E> I: ;9 F> I: ; 9 G.?: ; 9 '< H.?: ;9 'I�< I.?: ;9 ' J.: ; 9 ' K.?: ; 9 'I L.?: ; 9 'I �& K � ; M . c l } � � � 7 P( � K u-�~X�x-��x.-�f�x.-�< �x.-�t�x Z �J�x<=> t= � ��y L/xJX �=� �x�< �� l/ s�5 y�5 yt� t u � \/f �y�� uf ���yJ �f;X �� �ytXf�X �yX(��( �X J X Z =� =Y�X t � X �*""* �*rK= Z �XzfX Y! � J YJ< K ��|K ����|=Y<!��|J<!� �> Z �X .... � KJJ Y=Zf�|��X� ��O , �~��Y<. K � uZ-� X X �X �y<Z� <� s�:�|� �� �|���<t �| � � �J t & ��.<.Z<�}� X � � = � �� � � = < ' :�& �� u . � �KZ<�}� �t �=< � � � � �# �� �N�@���8 X � K � � . X � Y I � J/ .YX � t <* <j � � = 4 L Z : / X � �}8 �gt ,��|��. PT �� � `� X X �}�� s � �}< �� �� V � �}< �� T �T �� � X X z � X t X �}#� zX � u � � v W u ���3 &3==3 [, � < X = J � � � X Y . YJ � t < <[= # q= J�|�� .�\ IgJJ - wX X � �|$ � Ju�J i� � � X �|X�J f � �|t ��<��|X �# �� �P�{J�P:� t �# �L� � ��< . Z Y J�� u-K�J. cf � K � � k� < � x< )� K k�t �K@ v� ��� K �9� 9 ]X9 OX<�zYY�� X � J E . X�Ig ...- ��yY� < Y�zK�<Jf �<g -�! X ��;<Y<�zYK��Y<�zY=Y<<0�.�7�tK7�X7�Xc<XJR � I= =X. - y��= -Y! � < g.Y<�xYK�.YJ�yY=Y<<0�3��K3 =X� �4 �: K4 =X� �B ; �}�XBt�X8< � x<D �wJ 9 . M & ~ @ Q u J /!t< vJ J K4 �2 J X f&d � =< zf PX�!yt� X��X.J.fX g��?[ ��X:�X:�:*\X �g� � u < g J �/..I�.I 3I7 AX# X J X r< <urS< J...:j �e< J...6st �vf< J...4�ftK � J < X Y t � ��x e= X/ J = � Y = t Jj 0K v� < J �X....vt��=X sX �42�K4�X4KXd<Y K�<�xYK ���xYK � � �\ � I= = . -X4 �? K4t=XXc<Y ��<�xYK � � �[ � = = -X6 `@ K6t=XXc<Y ��<�xYK � � �[ � = = -X6 �@ K6 = f X < � � X�}��YXXe<�zX�X�z<YX���z<Y=Y<<YKY<J�X ....�zt�X��J �T��zTz<KTzPX# X J^ ^J4 u-=X ..J m<� =nJX .... zXzJ�z l ..zJy� �X� = tJ X ....T+XzTz<KTzPX# X J^ ^J4 u-=X ..J m<� =nJX .... ztzJ�z l ..zJy� �X� = tJ X ....C�zX�Y�< � � t Y �X �y<Z� �� s��y��) �}�� ���~ �< X t<& /rfu�� � � X t J, i � , Z � � � . �~ X X < X �> L � J J=�$���� < �O��k7 YX�J� � J � Y W � 0 � � s K f7 � t <& J � � �<7 . J � . X X �� tX X� h�� ��� ��!��# X <�X�* �' X�$ �Y% J$uX<% 1! /+ # �+ .# < %YC�K%=9 z�' X* X' � �( .!Yf�% � t� � . .� �7 �~3 ��t JX!.X .* �' X$��$ YYN$zX<, 2 t= , �= ;%0��J%� ��%� X9 zX' J* ' f* �' X(� �( X(� <!/%�!�%$X,� f &= �9 �=� � (�=�r;=J�~�� ��� vtJ>t � �J � tJ � � �}J X - �' / p �' t �'� t � � � ������L% f � X% k <�J �J �~f �� �~t �� � \ @� � �~�;' � " � ��~ �K �X<`�!_JKB ��� . � � t�* �' < ' X �'� � - �~� � � X � X�~+� � f X �~�< Xf' � #�~=�<<X b#B ��� �� �~X �L �% � � $! �~% � � � < � ��X � � u � J @. �� . �� �% � � J � .! � �J�.J \J8t \XZ �=; K � f < p� J � � � >X < � ? + f M � > �� f.l� � [ f � � > X � ? + f M �\Fj @ @J.*\XX lJ ���� U � �vJ � � < �vJ< � Jtu�: �|<�<:L�L8\<JZ�~ �}��? � J X J � � � t �* �' f �� = �e =X ��wK� �LVLt֬<J�J�X<�~? � �w� �� �#<� t �� �< �w� �(J � �w�� Xs � ��� �wf�� XR<tX �X � K �v< � � < �vJ< � JJu�> �}J�<L�:LL�~ �~�X<� J X J � � � � �* �' � �!� = �e =X ��wK� �LHLt֬<.J �~f � � �"s�+ f" K ��< �;=Y�� � � J � K I J � K J � > t X = = �t�xYK �=� � � �^�< � � � � � X X�XD<t �X�X �[ �N 2�* $p @� N X m< Y`Hh ,X f ^ �� ~ ; J � K M :� � � � � � [ ] � � � � � & i u � < � � � � � � � � � E � � � � � � � � 4 � 3 E w � # � � : c , � � } � l GNU GIMPLE 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -mtune=generic -march=x86-64-v2 -g -O2 -fno-openmp -fno-openacc -fcf-protection=full -fPIC -fstack-protector-strong -fltrans -fplugin=annobin __builtin___snprintf_chk __stack_chk_fail Ilaststatval long long int Perl_av_push old_parser subtr_ass_amg blku_oldsaveix Iorigargc Iorigargv Perl_sv_catpvn_flags si_errno keeper __pad0 tbl_arena_next _spent_size Iin_utf8_CTYPE_locale hostent ls_prev close_paren list_dot_max lex_stuff xpvgv Istatcache Icompiling Idbargs new_perl Perl_newSVsv_flags blku_oldsp sub_error_count xpvhv PERL_CONTEXT _asctime_buffer Inumeric_standard prevcomppad Ie_script Perl_newSV_type xhvnameu_name sv_u Ipreambleav IDBcontrol xpvio key_args xpviv tbl_max Perl_sv_isobject si_tid Imy_cxt_size blku_old_tmpsfloor Imain_root Perl_SvREFCNT_inc xcv_outside blku_type _PerlIO __locales he_valu __comparison Iutf8_totitle _spent_struct more named_buff want_vtbl_hintselem h_length op_first Idoswitches _netent_size thrhook_proc_t next_branch Perl_POPMARK block_eval s_port __in6_u in_port_t gp_refcnt prev_mark last_sv Idef_layerlist errsv result saw_infix_sigil Irestartjmpenv save_lastloc Iwarn_locale _spent_buffer Icolors mg_obj je_old_delaymagic fallback_amg multi_end PerlIO_list_s PerlIO_list_t COPHH scream_pos xpvmg Iargvgv despatch_signals_proc_t rshift_ass_amg xio_flags Isharehook tm_mday old_regmatch_state xcv_xsub nextword Iminus_E Icheckav pad_1 pad_2 Imarkstack Idump_re_max_len tm_zone __base Istatusvalue IDBsingle utf8_substr __u6_addr8 min_offset prealloc pmop st_atim sival_int Ilast_in_gv rootav Ireg_curpm share_proc_t joint Ihash_rand_bits_enabled pw_gecos hash_f convert_dotted_string _call_addr long double op_private lex_formbrack SVt_LAST sbu_dstr Irunops Ipsig_pend _ctime_buffer Icomppad_name Imarkstack_max sbu_iters internal Ireentrant_retint saved_curcop cmp_arg max_amg_code strcmp __blkcnt_t PTR_TBL_t Perl_call_method sig_seen xhv_max _protoent_size bsearch hent_hek xhv_aux_flags _grent_ptr _getlogin_buffer xivu_eval_seen __locale_data pos_flags Istack_base exec Imax_intro_pending poscache op_pmstashstartu to_gv_amg group sbu_strend smart_amg re_scream_pos_data_s cop_stashoff s_addr st_size sge_amg TT_RET_CODEREF Iperldb lastparen si_addr_lsb Iinplace __locale_t _pkey Perl_pop_scope tm_min mk_mortal_av IDBline want_vtbl_nkeys sin_amg Isv_arenaroot jump gp_egv newval padname states xio_bottom_gv jlen tt_ops roothv Iphase yylen list_f subbeg cos_amg throw_str _asctime_size Iblockhooks end_shift Perl_get_sv sbu_oldsaveix _pwent_ptr Iosname n_addrtype lex_casemods lex_brackstack numbered_buff_STORE Iefloatsize leave_op PADLIST Ipeepp PADNAME scalar_op mro_which Iregex_pad retop pkg_gen xcv_padlist_u minmod sp_pwdp Iutf8_foldclosures Ilocale_utf8ness Isv_yes parenfloor branchlike JMPENV Imain_start qr_anoncv Istashpad _arch my_perl Ienvgv Iperlio Ipadname_const Perl_xs_boot_epilog key2 __wchb pow_ass_amg mult_ass_amg Iregmatch_state prev_rex Iisarev Iutf8locale tm_mon key_sv op_opt c2_utf8 sa_family_t sockaddr_inarp subcoffset svu_fp yy_stack_frame Idebstash topword destroy_gen Perl_safesysfree want_vtbl_ovrld reg_substr_datum si_stack xpadl_max Inomemok dotop __uint8_t tm_hour TT_RET firstpos want_vtbl_debugvar Imbrlen_ps Idiehook prev_recurse_locinput any_ptr Sighandler1_t CLONE_PARAMS Icompcv padnl concat_ass_amg lex_repl timespec PerlInterpreter xpadnl_max_named Perl_hv_common_key_len newhash ILatin1 Isighandler1p st_nlink Iminus_F re_eval_str Iscopestack_ix sp_max Iscopestack_max iter_amg Iminus_a any_pvp Iminus_c want_vtbl_arylen_p Iminus_l Iminus_n Perl_die_nocontext Iminus_p Iargvout_stack Iinitav Perl_newSVpvn Perl_newXS_deffile Perl_SvREFCNT_dec sin6_family tm_yday newsv tbl_items Perl_ophook_t cache_mask firstchars xpvlenu_rx Imaxsysfd xs_args Ilocalizing Isighandler3p lex_shared retval servent _crypt_struct_buffer rxfree ncmp_amg pw_name sp_lstchg curly _getlogin_size nomethod_amg add_amg Iunicode __fmt blku_sub qr_package neg_amg Perl_mg_set Irestartop ICCC_non0_non230 autobox_list_op gofs __mask_was_saved PERL_PHASE_CONSTRUCT Ilastgotoprobe cop_line Isecondgv atroot __locale_struct Isavebegin want_vtbl_vec initialized XPVAV to_av_amg STRLEN exitlistentry abs_amg op_ppaddr xpadnl_alloc Icheckav_save Idebug_pad __jmp_buf_tag concat_amg lex_flags Iendav blku_oldscopesp Iutf8_idcont Icomppad_name_fill my_op IHasMultiCharFold __mbstate_t tmpXSoff XPVCV Perl_savetmps xhv_last_rand mark_stack_entry regnode xhv_name_u Iperl_destruct_level si_cxix mg_virtual padnamelist interpreter PMOP Istashpadix Perl_xs_handshake st_uid longfold sp_min xcv_xsubany PADOFFSET sbxor_amg snprintf sbu_rflags xpv_cur xpadn_flags Istderrgv xio_page_len xhv_eiter perl_memory_debug_header xhv_riter Iin_clean_all si_type mark_name memchr Istashpadmax old_regmatch_slab __ino_t reg_substr_data lex_super_state _grent_struct assign xcv_root_u curlym setting Icustom_op_descs si_prev XPVGV _addr_bnd sp_namp lex_starts Isavestack Sighandler3_t si_code Imodcount prev_curlyx Isortstash Istdingv svt_local sp_warn Perl_SvTRUE Icustom_ops sbor_ass_amg CHECKPOINT XPVHV any_av _grent_buffer sne_amg last_uni XPVIO sp_expire XPVIV __uint16_t minlenret Iofsgv Idelaymagic_gid xcv_gv_u Iunderlying_numeric_obj Icollxfrm_mult Perl_gv_add_by_type tbl_arena_end Isavestack_ix want_vtbl_defelem TT_RET_OK sockaddr_x25 SVt_PVAV sin6_flowinfo xmg_magic svu_gp any_dptr intuit Ibody_roots si_sigval hek_len Icollation_ix list_dot_reverse tokenbuf op_nextop line_t mgvtbl Iutf8_xidcont si_cxstack yyerrstatus Siginfo_t _hostent_ptr sbu_rx xcv_padlist resolve svt_get _Bool svu_iv XPVMG sbu_rxtainted seq_amg div_ass_amg op_moresib xpv_len_u Ipatchlevel Perl_call_sv _pwent_struct nextval svu_pv any_gv not_amg Ihash_rand_bits sbu_orig _servent_struct __gid_t Iparser xpadlarr_dbg stack_max1 runops_proc_t any_hv __compar Ipadlist_generation destroy SVt_PVFM xpadnl_max Idefoutgv _lower Istatusvalue_posix _pwent_buffer Iutf8_tosimplefold __ctype_tolower siginfo_t Perl_newSViv any_iv Ichopset Irpeepp oldcomppad sbu_rxres SVt_PVGV Iincgv si_markoff xpadnl_fill want_vtbl_arylen tv_nsec nexttype sig_slurpy want_vtbl_backref Icurpm_under SVt_PVHV lshift_ass_amg Sighandler_t svu_hash ISCX_invlist svu_nv sband_amg si_cxsubix lex_inpat last_lop tm_sec sockaddr_ax25 ptr_tbl_arena SVt_PVIO SVt_PVIV filtered Ilastfd want_vtbl_collxfrm Ieval_start ls_linestr PADNAMELIST SVt_PVCV PERL_PHASE_START xcv_hscxt any_u32 Perl_croak_nocontext _ctime_size repeat_ass_amg op_pmreplrootu scalar_dot_defined Isavestack_max item_len xhv_rand Ilocalpatches Isv_root SVt_PVLV p5rx op_next Perl_looks_like_number __saved_mask svu_rv copline sockaddr_eon any_op Icurstack SVt_PVMG Ipadix_floor Perl_push_scope si_status xpadl_arr h_addrtype end_loop _strerror_size Idelaymagic_euid bufend Perl_newSVpv lex_inwhat any_pv atan2_amg xnv_nv boot_Template__Stash__XS sin_zero Iopfreehook ssize _protoent_ptr Iunitcheckav svu_uv PerlIOl sgt_amg to_hv_amg Isetlocale_bufsize xpvhv_aux protoent mg_len Imemory_debug_header slt_amg SVt_IV Itop_env want_vtbl_sigelem __blksize_t list_dot_size short unsigned int _spent_ptr Perl_av_fetch bool__amg Itmps_stack yy_lexshared offs any_sv want_vtbl_substr Isv_undef Ipsig_name LEXSHARED clone_params perl_drand48_t Igensym Iregmatch_slab op_redoop rsfp call_coderef _hostent_struct start_tmp xio_fmt_name svt_len cop_hints h_name Ierrors xpvlenu_len h_aliases _hostent_size op_pmreplstart hent_refcount saved_copy lex_sub_inwhat any_uv Itmps_floor Istrxfrm_is_behaved __wch xpadl_id dec_amg int_amg Perl_av_undef Ibasetime Iop_mask Isighandlerp unreferenced Isignalhook xpadnl_refcnt loceol IUpperLatin1 mro_linear_current xio_ofp __value _hostent_buffer cop_seq multi_start op_pmreplroot SVt_NV IDBtrace maxlen pre_prefix op_targ Ibeginav je_ret resume_state Isv_consts pw_dir lex_casestack op_lastop Isub_generation blku_eval float want_vtbl_isaelem __count unsigned char si_cxmax multi_open _kill st_rdev LOOP ILB_invlist SVt_PV want_vtbl_dbline REENTR Imess_sv Iglobalstash Imin_intro_pending expect oldloc Icollxfrm_base want_vtbl_envelem copy_amg Iutf8_perl_idcont cx_blk a_av Istatname RETVAL Perl_gv_fetchmethod_autoload modulo_amg xnv_u __uid_t sin6_scope_id blku_gimme XSUBADDR_t st_ctim recheck_utf8_validity Iutf8_tofold xcv_root ISB_invlist block_format in_addr_t op_sibparent old_namesv log_amg xpadn_type_u IAssigned_invlist peep_t xhv_backreferences Iinternal_random_state Perl_sv_free2 Isv_no minlen __off_t perl_phase Iin_clean_objs Isv_zero super PERL_PHASE_INIT PERL_PHASE_DESTRUCT in_pod Perl_stack_grow gp_io Imultideref_pc Iors_sv string_amg xpadn_protocv Ievalseq Iunlockhook regexp_engine mg_flags subtr_amg Icurstash gr_passwd Perl_markstack_grow _gmtime_struct gr_gid want_vtbl_checkcall si_overrun __clock_t SVt_NULL ls_bufptr Ibeginav_save __uint32_t Iorigfilename xmg_hash_index last_lop_op cop_warnings Icop_seqmax op_pmtargetgv form_lex_state Istatgv Idestroyhook st_blocks max_offset GNU C17 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -march=x86-64-v2 -mtune=generic -g -g -O2 -flto -ffat-lto-objects -fexceptions -fstack-protector-strong -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection=full -fwrapv -fno-strict-aliasing -fPIC -fplugin=annobin sbu_m sbu_s Perl_safesysmalloc save_curlyx Icomppad sub_no_recover lex_dojoin xmg_u gp_cvgen Perl_av_store xcv_file SVt_PVNV itervar_u gp_flags xiou_dirp _servent_buffer paren_names Perl_sv_len Iregistered_mros si_uid avref pw_passwd fold_results Iin_some_fold sqrt_amg lex_allbrackets die_object opval hash_dot_keys Icurcopdb block_sub throw_fmt pos_magic gp_file_hek sv_refcnt sockaddr_in6 __nlink_t tbl_ary mro_alg sband_ass_amg xav_alloc si_fd nparens xpadn_refcnt scmp_amg Ieval_root old_eval_root named_buff_iter st_gid Idowarn yychar Ifirstgv rshift_amg mg_moremagic op_pmoffset xhv_name_count op_pmstashoff Inumeric_underlying_is_standard PERL_SI MGVTBL op_static MAGIC Itmps_max want_vtbl_pack sockaddr_ipx Ithreadhook blku_givwhen gr_name op_type Iutf8_perl_idstart Perl_hv_iterinit sublen blku_oldmarksp xivu_iv _netent_ptr want_vtbl_regexp Ipadname_undef preambling xhv_mro_meta Inumeric_underlying _upper cx_u output looks_private IDBcv trie Ilockhook __ctype_toupper Perl_newRV _xnvu xio_lines_left compflags sockaddr_iso want_vtbl_utf8 Iin_load_module xio_page sigjmp_buf pow_amg want_vtbl_hints tm_isdst div_amg Ilaststype __ctype_b h_addr_list Iutf8_charname_continue in_my_stash want_vtbl_regdata xpadn_len _strerror_buffer add_ass_amg dummy Iunitcheckav_save si_stime lastcloseparen short int ifmatch Perl_mg_get Idumpindent Ioldname preambled op_code_list XS_Template__Stash__XS_set xhv_keys itersave sbxor_ass_amg IAboveLatin1 Iutf8_mark _servent_size si_signo IDBgv Perl_sv_2bool_flags __names sv_any blk_u xcv_start accepted gvval IWB_invlist olddepth Iutf8cache _localtime_struct _bounds prev_eval Ipadix defsv_save want_vtbl_lvref _netent_buffer xcv_stash YYSTYPE _xhvnameu xcv_gv cop_hints_hash Icustom_op_names lex_sub_repl sle_amg xpadn_high re_scream_pos_data hek_hash _ttyname_buffer Iknown_layers _netent_errno Itainting Icurcop Istack_sp __ssize_t any_bool regmatch_info_aux PERL_PHASE_END Icollation_standard __glibc_reserved find_perl_op want_vtbl_taint lex_defer xmg_stash k_av Iorigalen sbu_maxiters sockaddr Idebug refcounted_he Icurpad __time_t st_mtim want_vtbl_uvar s_proto sbu_targ logical Iforkprocess lex_brackets xio_top_gv Iutf8_tolower Perl_newRV_noinc blku_oldcop Icurstackinfo Istart_env lex_fakeeof lex_sub_op stashes Istashcache xnv_lines mult_amg want_vtbl_packelem p_aliases _netent_struct in_my r_av next_off xivu_uv sin_port Imodglobal sockaddr_at regmatch_info_aux_eval xcv_start_u list_dot_join Perl_sv_catsv_flags want_vtbl_env basesp Igeneration IGCB_invlist Istrtab xpadl_outid hash_op xpadn_low block_givwhen regexp_paren_pair __size crypt_data pprivate cv_flags_t cur_top_env xpadn_typestash Iin_utf8_COLLATE_locale state_u TT_RET_UNDEF PERL_PHASE_RUN _sigfault op_spare lex_op st_ino cop_features __pid_t parsed_sub op_last Perl_free_tmps proto_perl want_vtbl_regdatum xio_type yylval Perl_sv_derived_from sp_inact sockaddr_dl xav_fill hent_val Iorigenviron Idelaymagic_egid gp_av ftest_amg scream_olds mg_ptr maxpos sa_family ptr_tbl Inumeric_name lazyiv get_debug_flag _sifields Perl_av_extend want_vtbl_pos SVt_REGEXP Ipsig_ptr gp_cv xgv_stash netent tv_sec tm_year blku_u16 Iprofiledata sbor_amg __sigset_t gp_line Imainstack Icurpm op_pmflags st_blksize xpadn_ourstash ptr_tbl_ent _hostent_errno op_slabbed scompl_amg Isubline Iargvoutgv Iwatchaddr r_hv Idefgv hek_key PerlExitListEntry xio_bottom_name gp_form Ireentrant_buffer hent_next check_ix op_flags Iunsafe tm_wday Ihintgv sockaddr_in __jmp_buf IDBsignal Iutf8_charname_begin xs_arg Ilanginfo_bufsize blku_format __dirstream sin_addr IXpv Iregex_padav hash_dot_values blku_loop cache_offset wanted pw_uid _timer Istrxfrm_NUL_replacement IInMultiCharFold je_old_stack_hwm sig_elems __idx gr_mem Ixsubfilename gp_hv Ipad_reset_pending dfoutgv Perl_sv_setsv_flags _sigchld xcv_depth Itaint_warn Imbrtowc_ps pw_shell si_next want_vtbl_nonelem _syscall Iexitlist Ilanginfo_buf Isubname any_i32 Ihv_fetch_ent_mh UNOP_AUX_item svt_dup xcv_flags Inumeric_radix_sv globhook_t xcv_outside_seq ident Isplitstr xcv_hek svt_free sockaddr_ns long long unsigned int si_addr Ibody_arenas checkstr _grent_size Perl_hv_iterval SVt_INVLIST want_vtbl_mglob Isortcop sin_family Isignals sbu_type si_pid mg_private dupe je_buf lazysv Iwcrtomb_ps Itoptarget Istrxfrm_max_cp Ierrgv Perl_sv_2pv_flags inc_amg svt_clear PERL_PHASE_CHECK nexttoke Itmps_ix Isig_pending substrs any_svp intflags destroyable_proc_t Ifdpid xpadlarr_alloc ival any_dxptr n_net to_sv_amg Perl_croak_xs_usage op_pmtargetoff ident_av Icollation_name Iefloatbuf to_cv_amg magic_vtable_max _pwent_size oldval find_xs_op any_long xiou_any ITR_SPECIAL_HANDLING_UTF8 lshift_amg Iexit_flags c1_utf8 Perl_sv_len_utf8 repeat_amg Icurlocales Iglobhook sin6_port xio_top_name do_getset IPrivate_Use scalar_f modulo_ass_amg Iptr_table Icolorset Perl_hv_iternext_flags __jmpbuf Ifilemode __dev_t Iexitlistlen sockaddr_un numer_amg op_folded Idelaymagic Imarkstack_ptr block tt_fetch_item pw_gid tm_gmtoff prev_yes_state s_name _protoent_struct op_comp gp_sv svu_array hash_dot_each whilem IInBitmap mother_re __val n_aliases _sigsys extflags xio_fmt_gv xpadn_gen __key cop_file Icurstname cx_subst __u6_addr16 Isv_count svt_set tt_ret Idefstash Itainted Ibodytarget oldoldbufptr xav_max xiv_u b_len _protoent_buffer st_mode savearray _xivu __compar_fn_t Iutf8_xidstart re_eval_start XS_Template__Stash__XS_get perl_debug_pad Istack_max cache_gen svtype strstr st_dev __u6_addr32 je_prev want_vtbl_sv Iclocktick Perl_sv_2iv_flags __syscall_slong_t IXPosix_ptrs IDBsub spwd Iutf8_idstart je_mustcatch numbered_buff_LENGTH yy_parser block_loop op_savefree Iscopestack Iformtarget pad_offset mro_nextmethod s_aliases lastcp Iconstpadix multi_close stat herelines Imy_cxt_list IPosix_ptrs xivu_namehek _ttyname_size sin6_addr scalar_dot_length Iwatchok Perl_av_len p_proto Perl_sv_2mortal want_vtbl_isa svt_copy xnv_bm_tail sival_ptr mark_loc si_utime xpvav Isrand_called perl_var strlen regexp_amg __nmemb __mode_t sp_flag Ireplgv sa_data Ibreakable_sub_gen rsfp_filters Iin_eval suboffset __sigval_t _servent_ptr lex_re_reparsing Iutf8_toupper Perl_hv_iterkeysv linestart sig_optelems xhvnameu_names old_cxsubix Icv_has_eval mg_type xpvcv Isetlocale_buf numbered_buff_FETCH Irandom_state Iscopestack_name si_band xpadn_pv Icomppad_name_floor kflags Idelaymagic_uid Iwarnhook _xmgu _sigpoll mro_linear_all xio_dirpu Iin_utf8_turkic_locale cur_text blku_oldpm Imain_cv /home/.cpan/build/Template-Toolkit-3.102-0/xs <artificial> /usr/include/bits /usr/lib64/perl5/CORE Stash.xs stdlib-bsearch.h inline.h stdio2.h Stash.c <built-in> struct_stat.h intrpvar.h mg_vtable.h av.h __locale_t.h iperlsys.h string.h handy.h sockaddr.h grp.h struct___jmp_buf_tag.h dirent.h __sigval_t.h util.h overload.h pwd.h /usr/lib/gcc/x86_64-redhat-linux/11/include crypt.h gv.h netdb.h types.h mg.h perlio.h /usr/include struct_timespec.h time_t.h regexp.h cv.h cop.h hv.h stdint-uintn.h pad.h parser.h /usr/include/netinet __sigset_t.h reentr.h proto.h perly.h socket.h sv.h /usr/include/sys __mbstate_t.h siginfo_t.h stdlib.h /usr/include/bits/types stddef.h struct_tm.h perl.h setjmp.h shadow.h in.h �4 1U1uVu~�U�~�V l �~� � l9�~�9� l � �~� � � l�� ~��� 10�1l^~�^ 19�1l_~�_ GiS~�S Qi\~�\ ZiP~�P QZ\ QZ�� ��U��V���U���V ��P ���� � ��\��\��\ ��V��V��V ��\ ��V ��U��V ��T��\ ��P ��U��^�� �� P ���U��^ ��T��]���T���T��] ��V��V��vx���V��u ��V ��S������P��S������P ��P���� ��S��_������S��_��_ ��S��S ��1���\��|���\��\ ��P���� ��S ��S��S ��^��^ ��Q��s��Q ��U�� \� � �U�� � \� � U� �\ ��T�� S� � �T�� � S� � �T�� � S� ��T���S���T���S���T���S���T���S���T���S���T���S ��Q�� V� � �Q�� � V� � �Q�� �V���Q���V���Q���V���Q���V���Q���V���Q���V���Q���V ��R�� _� � �R�� � _� � �R�� � R� � _� ��R���_���R���_���R���_���R���_���R���_���R���_���R���_ ��X�� ��� � X� ��� ��Y�� ��� � �Y�� � ��� � Y� ������Y��������Y��������Y��������Y����� ��P��u �� ��� � ��� � u � �����^��~���^��~���^��| ������^������^������������ � � P� � S� � P� � S��P��S��S��S��S��P��S��P��S��S � � P� � V� � P� �]��]��V � � _��_��_��_��_��_ � �_��_��_��_��_��_��_ �� ]� � ]� � P� � ]��]��]��]��]��]��] �� ]� � ]��]��]��] �� \� � \��\��\��\ ��P��P���� ��\� � \��\��\��\ ��T ��\ ��V ��\ ��V ��\ ��] ��\ ��] ��\ ��s ��P ������P�������� ��0���V��V ��P��P ��U��^��U���U���^��U��^��U�� ^ ��T������T������T�� �� ��Q��\���Q���\���Q���Q��\���Q���\�� �Q� ��_�����_��~ ��_��P��_��~ ��_ ��P��S��S ��P��P��\��T��\�� ����\�� ���� \ ��0���V��V��0� ��P��P��P��P��u� ��q� ��^��^��^��^�� ^ �� ^ � � U� � \� � |�}�� � �U�� � \� � U� � \� � �U� � � T� � S� � �T�� � S� � �T�� � S� � �T�� � S� � �T� � � Q� � V� � �Q�� � V� � Q� � V � � R� � ^� � �R�� � ^ � � X� � ]� � �X�� � ]� � X� � ] � � Q� � Q � � 0�� � S� � 0�� � S� � 0�� � S � � U� �!V�!�!U�!�!�U��!�"V � � T� � _� �!�T��!�!_�!�"�T� � � Q� �!^�!�!�Q��!�"^ � � R� �!]�!�!�R��!�"] �!�!_�"�"P�"�"_ � � P� �!\�!�!T�!�"\ � � 0�� �!S�!�!S�!�!0��!�!s��!�!s��!�"S�"�"s��"�"S � � P�!�!P�!�"�� � � P� �!\�!�!T�!�"\ � � _ �!�!] �!�!]�"�"] �!�!V�"�"V �!�!Q�!�!}�!�!q��"�"Q �"�"R �"�"R �"�"T �"�"T �"�"V �"�"Q�"�"t�"�"q��"�"Q �"�#U�#�#_�#�#U�#�#�U��#�$_ �"�"T�"�#]�#�#�T��#�$] �"�#Q�#�$�Q� �#�#V�#�$P�$�$V �#�#P�#�#^�#�$^ �#�#P�#�#���#�#P�#�$�� �#�#0��#�$S �#�#P�#�#^�#�$^ �$�$R �$�$R �$�$T �$�$T �$�$_ �$�$Q�$�$t�$�$q��$�$Q �$�$U�$�$V�$�$U�$�$�U� �$�$T�$�$�T� �$�$Q�$�$�Q� �%�%U�%�%V�%�%U�%�%�U� �%�%T�%�%�T� �%�%Q�%�%�Q� �%�%U�%�'^�'�'�U��'�(^ �%�%T�%�&V�&�&v��&�&V�'�'V�'�(V �%�%Q�%�%S�&�&S�&�&s��&�&S�&�&s��&�&S�'�'S�'�(S �%�%P�%�'\�'�'\�'�'P�'�(\ �%�%��~��%�%]�%�'_�'�'_�'�(P�(�(_ �%�%��~��%�%]�%�&_�&�&R�&�&r��&�&R�'�'_�'�'R�(�(P�(�(_ �%�&0��&�&Q�'�'0��'�'Q�'�(0� �%�%P�%�'\�'�'\�'�'P�'�(\ �(�(U�(�)V�)�)�U� �(�(T�(�)\�)�)�T� �(�(Q�(�(T�(�)�Q� �(�(P�(�)S �(�(P �)�)U�)�)V�)�) �X P ��)�*V�*�*�U��*�*V�*�*�U� �)�)T�)�)\�)�)�T��)�*\�*�*�T��*�*\�*�*�T� �)�)Q�)�)^�)�)�Q��)�*^�*�*�Q� �)�)R�)�)]�)�)�R��)�*]�*�*�R��*�*]�*�*�R� �)�)X�)�)S�)�)�X��)�*S�*�*�X��*�*S�*�*�X� �)�)P �)�)P�)�)^�*�*^ �*�+U�+�-^�-�-�U��-�-^ �*�+T�+�-]�-�-�T��-�-] �*�+Q�+�+P�+�-�� �+�+P�,�,P�-�-P �,�,X�-�-X�-�-P �+�+P�+�-\�-�-\�-�-\ �+�+P�+�-V�-�-V�-�-V �+�+0��+�,S�-�-S �+�+ S` ��+�-_�-�-_�-�-_ �-�-U�-�/]�/�/U�/�/�U� �-�-T�-�.S�.�/�T� �-�-Q�-�/�Q� �.�.P�.�/V �.�.P�.�.\�.�.P�.�/\ �.�.P�.�/V �.�.P �.�.P �.�.P �.�.P �/�/U�/�0\�0�0U�0�0�U� �/�/T�/�0S�0�0�T� �/�/Q�/�0�Q� �/�/P�/�0V �/�/P�/�/P �/�/P�/�0V �/�/P �/�/P �0�0U�0�1\�1�1U�1�1�U� �0�0T�0�1S�1�1�T� �0�0Q�0�1�Q� �0�0P�0�1V �0�0P�0�1P �0�0P�0�1V �0�0P �0�0P �1�1U�1�1V�1�1U�1�1�U��1�1U�1�1V �1�1T�1�1�T��1�1T�1�1�T� �1�1Q�1�1�Q��1�1Q�1�1�Q� �1�2U�2�2\�2�3�U��3�3\ �1�2T�2�2���2�3�T��3�3���3�3�T� �1�2Q�2�2^�2�3�Q��3�3^ �1�2R�2�3_�3�3�R��3�3_ �1�2X�2�2S�2�3�X��3�3S �2�2P�2�2V�3�3V �2�2P�2�2]�3�3] �2�2P�3�3P�3�3�� �1�3�' � �2�2Y �2�2V�3�3V �2�2\�3�3\ �2�2Q�2�2v�3�3Q �2�2]�3�3] �2�2\�3�3\ �2�2Q�2�2}�3�3Q �3�3U�3�4V�4�4v�}��4�4 �X P ��4�4V�4�4�U��4�4V�4�4U�4�4�U��4�5V�5�5�U� �3�3T�3�4\�4�4�T��4�4\�4�4�T��4�4\�4�4T�4�4�T��4�5\�5�5�T� �3�3Q�3�4_�4�4�Q��4�4_�4�4�Q��4�4_�4�4Q�4�4�Q��4�5_�5�5�Q� �3�3R�3�4]�4�4�R��4�4]�4�4�R��4�4]�4�4R�4�4�R��4�5]�5�5�R� �3�3X�3�4S�4�4�X��4�4S�4�4�X��4�4S�4�4X�4�4�X��4�5S�5�5�X� �3�3Y�3�4^�4�4�Y��4�4^�4�4�Y��4�5^�5�5�Y� �3�3P �4�4P�4�4P�4�5P�5�5�� �5�5U�5�6V�6�6v�}��6�6 �X P ��6�6V�6�6�U��6�6V�6�6U�6�6�U��6�7V�7�7�U� �5�5T�5�6\�6�6�T��6�6\�6�6�T��6�6\�6�6T�6�6�T��6�7\�7�7�T� �5�5Q�5�6_�6�6�Q��6�6_�6�6�Q��6�6_�6�6Q�6�6�Q��6�7_�7�7�Q� �5�5R�5�6]�6�6�R��6�6]�6�6�R��6�6]�6�6R�6�6�R��6�7]�7�7�R� �5�5X�5�6S�6�6�X��6�6S�6�6�X��6�6S�6�6X�6�6�X��6�7S�7�7�X� �5�5Y�5�6^�6�6�Y��6�6^�6�6�Y��6�7^�7�7�Y� �5�5P �6�6P�6�6P�6�7P�7�7�� �7�8U�8�9^�9�9�U��9�;^�;�;U�;�U^ �7�8T�8�8V�8�9�T��9�9V�9�9�T��9�:V�:�;�T��;�;T�;�AV�A�B�T��B�DV�D�F�T��F�KV�K�K�T��K�MV�M�N�T��N�RV�R�R�T��R�RV�R�S�T��S�SV�S�T�T��T�UV�U�U�T� �7�8Q�8�8\�8�9�Q��9�;\�;�;Q�;�A\�A�B�Q��B�D\�D�F�Q��F�M\�M�N�Q��N�R\�R�R�Q��R�R\�R�S�Q��S�S\�S�T�Q��T�U\�U�U�Q� �7�8R�8�8��~�8�9�R��9�9��~�9�9�R��9�:��~�:�;�R��;�;R�;�D��~�D�F�R��F�R��~�R�S�R��S�S��~�S�S�R��S�U��~�U�U�R� �7�8X�8�8S�8�9�X��9�9S�9�9�X��9�AS�A�B�X��B�DS�D�F�X��F�RS�R�S�X��S�SS�S�S�X��S�US�U�U�X� �7�7P�7�8u �8�8��~�9�9��~�9�:��~�;�;u �;�=��~�=�=[�=�=��~�=�=[�=�={��=�>[�>�>��~�>�?��~�?�@��~�C�C��~�F�G��~�G�GR�H�Hrx��H�HP�H�H~ �K�KR�K�K��~�N�N~ �P�P��~�T�T��~�T�T��~ �8�8_�9�;_�;�A_�B�R_�S�S_�S�U_ �<�<p ���<�<y ���F�Fy ���F�G ��~��� �8�8_�9�9_�;�;_�?�@_�G�G_ �8�8^�9�9^�;�;^�?�@^�G�G^ �8�8P�?�?P�?�?��~ �8�8^�9�9^�;�;^�?�@^�G�G^ �?�?T �?�?^ �:�;P �:�:T�:�;V �:�:p� �=�=P�=�>��~�G�GP�G�GX�K�KX�K�K��~ �=�=0��=�>Y�>�>Y�>�>��~ �>�>P�>�>X�>�>��~ �<�<P�<�>��~�B�C��~�G�M��~�N�R��~�R�R��~�S�S��~�T�T��~�T�U��~ �<�<P �<�=P�P�PP �G�H^�K�K^�L�L^�O�P^�P�P^�Q�Q^�R�R^ �Q�QU�Q�Q^ �I�I � � �I�I@� �I�I��~��I�I[�I�I��~ �A�AP�A�B]�S�S] �A�BS�S�SS �A�B\�S�S\ �A�AQ �A�A0��A�B��~�S�S��~ �A�A_�A�AP�A�A_�B�BP�B�B_�S�S_ �A�AP�A�B]�S�S] �A�AQ�S�SQ �A�AQ�S�SQ �D�DP�D�F]�U�U] �D�FS�U�US �D�FV�U�UV �D�D0��E�EY�E�E��~�E�EQ�E�F\ �D�E\�E�EP�E�E\�F�FP�F�F\�U�UP�U�U\�U�UP�U�U\ �D�DP�D�F]�U�U] �E�EQ�U�UQ �E�EQ�U�UQ �M�MP�M�NV�R�RV�R�R0��S�TV �M�N\�R�R\�R�R\�S�S\�S�T\ �M�MP�M�NV�R�RV�R�RP�R�RV�S�SV�S�TV �M�MP �M�MP�R�RP �R�RV�S�TV �R�R^�S�T^ �R�RQ�R�Rv�R�Rq��S�TQ �U�UU�U�W^�W�W�U��W�X^�X�XU�X�X�U��X�Y^ �U�UT�U�V_�V�VP�V�W_�W�WP�W�W_�W�WP�W�X_�X�XT�X�Y_ �U�UQ�U�WV�W�W�Q��W�XV�X�X�Q��X�YV �U�UR�U�V]�V�X���X�X]�X�Y�� �U�UX�U�US�U�V�X��V�WS�W�XS�X�XY�X�YS �W�WR�X�XR �V�V]�V�W]�W�W]�W�X]�X�XQ�X�Y] �V�VP�V�VP�W�WP�W�XP�X�XP�X�YP�Y�YP�Y�YP �V�VP�X�X���X�XP�X�X�� �V�V0��V�W\�W�W\�X�X0��X�Y\ �U�UP�U�Vp��V�X���X�XP�X�Y�� �Y�ZU�Z�\S�\�\�U��\�`S �Y�ZT�Z�\�T��\�\T�\�`�T��`�`T�`�`U�`�`�T� �Y�YQ�Y�\\�\�`\ �Y�Zq $ &3$p "��Z�Z| $ &3$p "��Z�Z| $ &3$s"��\�\| $ &3$s"��`�`| $ &3$p "� �Z�ZQ�\�\Q�\�\���`�`Q �Z�\^�\�`^ �Z�[_�\�^_�^�`_ �Z�ZP�Z�\���\�\P�\�`�� �[�[P�[�\V�\�\P�^�^P�^�^V �Z�Z]�\�\P�\�]]�^�^]�_�_]�_�`] �[�[V�]�]P�]�^V �Z�Z^�\�\^ �Z�ZS�\�\S �Z�` ` � �Z�`6� �[�[P�[�\_ �\�\V �]�]V�^�^V�_�`V �]�]S�^�^S�_�`S �_�_V �_�_S �\�\1��`�`1� �`�aU�a�cS�c�c�U��c�gS �`�aT�a�g�T��g�gT�g�gU�g�g�T� �`�aQ�a�c\�c�g\ �a�aq $ &3$p "��a�a| $ &3$p "��g�g| $ &3$p "� �a�bV�c�dV�f�fV�g�gV �a�c_�c�g_�g�g_ �a�c]�c�g]�g�g] �b�cP�c�cV�c�cP�d�dP�d�dV�e�fV �a�aX�a�bX�c�cX�c�d���f�fX �e�eP�e�eX�f�fX�g�gX �b�bZ�b�c���c�dP �a�a_ �a�aU�a�aS �a�g ` ��g�g ` � �a�g6��g�g6� �b�bP�b�c^ �c�cV �d�eV�e�eT�e�et��e�eT�e�eu �e�eP�e�eQ�f�fQ�f�fT�f�fv��f�fV�g�gP�g�gs �d�eP�f�fP �e�fV �e�eV �d�dR �c�c1��f�g1� �g�gU�g�gT�g�hV�h�hU�h�h�U� �g�gT�g�h�T� �g�gP�g�h\�h�hT �g�gp $ &3$v"8 � �g�gv �g�gv p $ &3$ v #8� &8i�� ADQZ �������� �������� ���� ������ �� � � ������ ��� � ������ � � �������� � � ���������� ������ ������ ���� �������� ���������� � � � � � � �!�!�"�" �"�"�"�"�"�#�#�# �%�%�%�%�%�% �-�-�-�-�-�-�.�. �/�/�/�/�/�/ �0�0�0�0�0�0 �1�2�2�2 �2�2�2�2 �2�2�3�3 �2�2�3�3 �2�2�3�3 �2�2�3�3 �8�8�9�9�;�;�?�@�G�G �8�8�9�9�;�;�?�@�G�G �<�>�B�C�G�K�K�K�K�L�L�M�N�R�R�R�S�S�T�T�T�U �<�=�P�P �G�H�K�K�K�K�L�L�O�P�P�P�Q�Q�R�R �H�J�L�M�N�O�Q�R�T�T�T�U �@�B�S�S �@�A�A�A �A�A�S�S �D�F�R�S�U�U �D�D�D�D�D�D �E�E�E�E�U�U �M�N�R�R�R�R�S�S�S�T �M�M�M�M �M�M�M�M�M�M �M�M�M�M�R�R �R�R�S�T �Y�Y�Y�Y �Z�\�\�\�\�\�\�` �Z�Z�Z�Z�\�\ �]�]�]�]�^�^�_�_�_�` �]�]�]�]�_�_ �\�\�\�\ �`�`�`�` �a�c�c�c�c�c�c�f�g�g �a�a�a�a �d�f�f�f�g�g �d�e�f�f �c�c�c�c � � � r � 8 � �# �' d\ ` Tc Pd �� �� �� � � � 1� 8� ! " # � �' �' ! ( 7 1� C �� j @( v �� � � P( � `( u � � � �( @ � * � � �* K � , � 4 ^ �6 � `8 N �9 � 0 �: $ = �: % K ; p a p< o n �< � v �= � � 0? � � �? ~ � `@ � � �@ : � 0A � � B � � C � � D � � � 1 S � U s % �X ] � @ �l � sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF sF � N sF _ d\ e �� r � { Tc � 8� � � � � � � � 1 A �[ s Z v � � � � � � � - A X k ~ � � � � � � � � " 7 J V g { � � � � � � � � $ / ? L ] k { � � � � � � " crtstuff.c deregister_tm_clones __do_global_dtors_aux completed.0 __do_global_dtors_aux_fini_array_entry frame_dummy __frame_dummy_init_array_entry scalar_dot_defined find_xs_op xs_args get_debug_flag.part.0.isra.0 die_object fold_results assign call_coderef tt_fetch_item mk_mortal_av list_dot_reverse list_dot_max list_dot_size convert_dotted_string find_perl_op list_op list_dot_join hash_dot_each hash_dot_keys hash_dot_values scalar_dot_length autobox_list_op.constprop.0 hash_op scalar_op dotop throw_fmt do_getset XS_Template__Stash__XS_set XS_Template__Stash__XS_get __FRAME_END__ Stash.c.6545d45e _fini __dso_handle _DYNAMIC __GNU_EH_FRAME_HDR __TMC_END__ _GLOBAL_OFFSET_TABLE_ _init Perl_sv_2iv_flags Perl_sv_2bool_flags __snprintf_chk@GLIBC_2.3.4 Perl_looks_like_number Perl_hv_iterkeysv Perl_newRV_noinc Perl_stack_grow boot_Template__Stash__XS _ITM_deregisterTMCloneTable Perl_sv_catpvn_flags Perl_call_method Perl_sv_derived_from Perl_av_len Perl_pop_scope Perl_die_nocontext strlen@GLIBC_2.2.5 __stack_chk_fail@GLIBC_2.4 Perl_av_store Perl_sv_2pv_flags Perl_xs_boot_epilog Perl_hv_iternext_flags Perl_safesysmalloc memchr@GLIBC_2.2.5 strcmp@GLIBC_2.2.5 Perl_sv_isobject __gmon_start__ Perl_croak_xs_usage Perl_savetmps Perl_sv_len Perl_av_push Perl_newSVpv Perl_gv_fetchmethod_autoload Perl_get_sv Perl_croak_nocontext Perl_newXS_deffile Perl_mg_set Perl_hv_iterinit Perl_sv_setsv_flags Perl_sv_2mortal Perl_mg_get Perl_safesysfree Perl_sv_catsv_flags Perl_av_undef Perl_xs_handshake Perl_av_fetch Perl_free_tmps Perl_markstack_grow Perl_hv_common_key_len Perl_newRV Perl_newSV_type Perl_call_sv Perl_sv_len_utf8 Perl_sv_free2 Perl_push_scope _ITM_registerTMCloneTable Perl_newSViv Perl_hv_iterval Perl_gv_add_by_type Perl_newSVsv_flags Perl_newSVpvn __cxa_finalize@GLIBC_2.2.5 strstr@GLIBC_2.2.5 Perl_av_extend .symtab .strtab .shstrtab .note.gnu.property .note.gnu.build-id .gnu.hash .dynsym .dynstr .gnu.version .gnu.version_r .rela.dyn .rela.plt .init .plt.sec .text .fini .rodata .eh_frame_hdr .eh_frame .init_array .fini_array .data.rel.ro .dynamic .got .data .bss .comment .annobin.notes .gnu.build.attributes .debug_aranges .debug_info .debug_abbrev .debug_line .debug_str .debug_line_str .debug_loclists .debug_rnglists � � . � � $ A ���o � � $ K S Y [ ���o r r � h ���o � � @ w 8 8 X � B � � � � � � � �# �# � � �' �' �4 � d\ d\ � 2 ` ` S � Tc Tc � � Pd Pd \ � �� �z � �� �z � �� �z @ � � | � � � �} � � � 1 � 1� 1� 0 1� . 0 _� � 8� � 2 � 0 A <� �� M �> G [ E 9( g 0 Lm *= r 0 v� � � ?� �4 � �� � � % � � $ � � PK � �[̇�<�0 �0 script/ttreenu ȯ�� #!/usr/bin/perl -w #======================================================================== # # ttree # # DESCRIPTION # Script for processing all directory trees containing templates. # Template files are processed and the output directed to the # relvant file in an output tree. The timestamps of the source and # destination files can then be examined for future invocations # to process only those files that have changed. In other words, # it's a lot like 'make' for templates. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2013 Andy Wardley. All Rights Reserved. # Copyright (C) 1998-2003 Canon Research Centre Europe Ltd. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== use strict; use Template::App::ttree; my $ttree = Template::App::ttree->new; $ttree->offer_create_a_sample_config_file(); $ttree->run(); exit(0); __END__ #------------------------------------------------------------------------ # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. #------------------------------------------------------------------------ =head1 NAME Template::Tools::ttree - Process entire directory trees of templates =head1 SYNOPSIS ttree [options] [files] =head1 DESCRIPTION The F<ttree> script is used to process entire directory trees containing template files. The resulting output from processing each file is then written to a corresponding file in a destination directory. The script compares the modification times of source and destination files (where they already exist) and processes only those files that have been modified. In other words, it is the equivalent of 'make' for the Template Toolkit. It supports a number of options which can be used to configure behaviour, define locations and set Template Toolkit options. The script first reads the F<.ttreerc> configuration file in the HOME directory, or an alternative file specified in the TTREERC environment variable. Then, it processes any command line arguments, including any additional configuration files specified via the C<-f> (file) option. =head2 The F<.ttreerc> Configuration File When you run F<ttree> for the first time it will ask you if you want it to create a F<.ttreerc> file for you. This will be created in your home directory. $ ttree Do you want me to create a sample '.ttreerc' file for you? (file: /home/abw/.ttreerc) [y/n]: y /home/abw/.ttreerc created. Please edit accordingly and re-run ttree The purpose of this file is to set any I<global> configuration options that you want applied I<every> time F<ttree> is run. For example, you can use the C<ignore> and C<copy> / C<link> options to provide regular expressions that specify which files should be ignored and which should be copied or linked rather than being processed as templates. You may also want to set flags like C<verbose> and C<recurse> according to your preference. A minimal F<.ttreerc>: # ignore these files ignore = \b(CVS|RCS)\b ignore = ^# ignore = ~$ # copy these files copy = \.(gif|png|jpg|pdf)$ # recurse into directories recurse # provide info about what's going on verbose In most cases, you'll want to create a different F<ttree> configuration file for each project you're working on. The C<cfg> option allows you to specify a directory where F<ttree> can find further configuration files. cfg = /home/abw/.ttree The C<-f> command line option can be used to specify which configuration file should be used. You can specify a filename using an absolute or relative path: $ ttree -f /home/abw/web/example/etc/ttree.cfg $ ttree -f ./etc/ttree.cfg $ ttree -f ../etc/ttree.cfg If the configuration file does not begin with C</> or C<.> or something that looks like a MS-DOS absolute path (e.g. C<C:\\etc\\ttree.cfg>) then F<ttree> will look for it in the directory specified by the C<cfg> option. $ ttree -f test1 # /home/abw/.ttree/test1 The C<cfg> option can only be used in the F<.ttreerc> file. All the other options can be used in the F<.ttreerc> or any other F<ttree> configuration file. They can all also be specified as command line options. Remember that F<.ttreerc> is always processed I<before> any configuration file specified with the C<-f> option. Certain options like C<lib> can be used any number of times and accumulate their values. For example, consider the following configuration files: F</home/abw/.ttreerc>: cfg = /home/abw/.ttree lib = /usr/local/tt2/templates F</home/abw/.ttree/myconfig>: lib = /home/abw/web/example/templates/lib When F<ttree> is invoked as follows: $ ttree -f myconfig the C<lib> option will be set to the following directories: /usr/local/tt2/templates /home/abw/web/example/templates/lib Any templates located under F</usr/local/tt2/templates> will be used in preference to those located under F</home/abw/web/example/templates/lib>. This may be what you want, but then again, it might not. For this reason, it is good practice to keep the F<.ttreerc> as simple as possible and use different configuration files for each F<ttree> project. =head2 Directory Options The C<src> option is used to define the directory containing the source templates to be processed. It can be provided as a command line option or in a configuration file as shown here: src = /home/abw/web/example/templates/src Each template in this directory typically corresponds to a single web page or other document. The C<dest> option is used to specify the destination directory for the generated output. dest = /home/abw/web/example/html The C<lib> option is used to define one or more directories containing additional library templates. These templates are not documents in their own right and typically comprise of smaller, modular components like headers, footers and menus that are incorporated into pages templates. lib = /home/abw/web/example/templates/lib lib = /usr/local/tt2/templates The C<lib> option can be used repeatedly to add further directories to the search path. A list of templates can be passed to F<ttree> as command line arguments. $ ttree foo.html bar.html It looks for these templates in the C<src> directory and processes them through the Template Toolkit, using any additional template components from the C<lib> directories. The generated output is then written to the corresponding file in the C<dest> directory. If F<ttree> is invoked without explicitly specifying any templates to be processed then it will process every file in the C<src> directory. If the C<-r> (recurse) option is set then it will additionally iterate down through sub-directories and process and other template files it finds therein. $ ttree -r If a template has been processed previously, F<ttree> will compare the modification times of the source and destination files. If the source template (or one it is dependant on) has not been modified more recently than the generated output file then F<ttree> will not process it. The F<-a> (all) option can be used to force F<ttree> to process all files regardless of modification time. $ tree -a Any templates explicitly named as command line argument are always processed and the modification time checking is bypassed. =head2 File Options The C<ignore>, C<copy>, C<link> and C<accept> options are used to specify Perl regexen to filter file names. Files that match any of the C<ignore> options will not be processed. Remaining files that match any of the C<copy> or C<link> regexen will be copied or linked to the destination directory. Files that reside in any of the C<copy_dir> directories are also copied. Remaining files that then match any of the C<accept> criteria are then processed via the Template Toolkit. If no C<accept> parameter is specified then all files will be accepted for processing if not already copied or ignored. # ignore these files ignore = \b(CVS|RCS)\b ignore = ^# ignore = ~$ # copy these files copy = \.(gif|png|jpg|pdf)$ # accept only .tt2 templates accept = \.tt2$ The C<suffix> option is used to define mappings between the file extensions for source templates and the generated output files. The following example specifies that source templates with a C<.tt2> suffix should be output as C<.html> files: suffix tt2=html Or on the command line, --suffix tt2=html You can provide any number of different suffix mappings by repeating this option. The C<binmode> option is used to set the encoding of the output file. For example use C<--binmode=:utf8> to set the output format to unicode. =head2 Template Dependencies The C<depend> and C<depend_file> options allow you to specify how any given template file depends on another file or group of files. The C<depend> option is used to express a single dependency. $ ttree --depend foo=bar,baz This command line example shows the C<--depend> option being used to specify that the F<foo> file is dependant on the F<bar> and F<baz> templates. This option can be used many time on the command line: $ ttree --depend foo=bar,baz --depend crash=bang,wallop or in a configuration file: depend foo=bar,baz depend crash=bang,wallop The file appearing on the left of the C<=> is specified relative to the C<src> or C<lib> directories. The file(s) appearing on the right can be specified relative to any of these directories or as absolute file paths. For example: $ ttree --depend foo=bar,/tmp/baz To define a dependency that applies to all files, use C<*> on the left of the C<=>. $ ttree --depend *=header,footer or in a configuration file: depend *=header,footer Any templates that are defined in the C<pre_process>, C<post_process>, C<process> or C<wrapper> options will automatically be added to the list of global dependencies that apply to all templates. The C<depend_file> option can be used to specify a file that contains dependency information. $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep Here is an example of a dependency file: # This is a comment. It is ignored. index.html: header footer menubar header: titlebar hotlinks menubar: menuitem # spanning multiple lines with the backslash another.html: header footer menubar \ sidebar searchform Lines beginning with the C<#> character are comments and are ignored. Blank lines are also ignored. All other lines should provide a filename followed by a colon and then a list of dependant files separated by whitespace, commas or both. Whitespace around the colon is also optional. Lines ending in the C<\> character are continued onto the following line. Files that contain spaces can be quoted. That is only necessary for files after the colon (':'). The file before the colon may be quoted if it contains a colon. As with the command line options, the C<*> character can be used as a wildcard to specify a dependency for all templates. * : config,header =head2 Template Toolkit Options F<ttree> also provides access to the usual range of Template Toolkit options. For example, the C<--pre_chomp> and C<--post_chomp> F<ttree> options correspond to the C<PRE_CHOMP> and C<POST_CHOMP> options. Run C<ttree -h> for a summary of the options available. =head1 AUTHORS Andy Wardley E<lt>abw@andywardley.comE<gt> L<http://www.andywardley.com/|http://www.andywardley.com/> With contributions from Dylan William Hardison (support for dependencies), Bryce Harrington (C<absolute> and C<relative> options), Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon Brocard who gets everywhere, it seems. =head1 VERSION 2.68, distributed as part of the Template Toolkit version 2.19, released on 27 April 2007. =head1 COPYRIGHT Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<tpage|Template::Tools::tpage> =cut PK � �[��l# l# script/tpagenu ȯ�� #!/usr/bin/perl -w #======================================================================== # # tpage # # DESCRIPTION # Script for processing and rendering a template document using the # Perl Template Toolkit. # # AUTHOR # Andy Wardley <abw@kfs.org> # # COPYRIGHT # Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved. # Copyright (C) 1998-2000 Canon Research Centre Europe Ltd. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #------------------------------------------------------------------------ # # $Id$ # #======================================================================== use strict; use Template; use Template::Directive; use AppConfig; my $NAME = "tpage"; my $VERSION = 2.70; my $HOME = $ENV{ HOME } || ''; my $RCFILE = $ENV{"\U${NAME}rc"} || "$HOME/.${NAME}rc"; my $TTMODULE = 'Template'; # read .tpagerc file and any command line arguments my $config = read_config($RCFILE); # unshift any perl5lib directories onto front of INC unshift(@INC, @{ $config->perl5lib }); # get all template_directive_* options from the config my %ttdirectiveopts = $config->varlist('^template_directive_', 1); # get all template_* (except template_directive_*) options from the config and fold keys to UPPER CASE my %ttopts = $config->varlist('^template_(?!directive_)', 1); my $ttmodule = delete($ttopts{ module }); my $ttenvvars = delete($ttopts{ envvars }); my $ucttopts = { map { my $v = $ttopts{ $_ }; defined $v ? (uc $_, $v) : () } keys %ttopts, }; # load custom template module if ($ttmodule) { my $ttpkg = $ttmodule; $ttpkg =~ s[::][/]g; $ttpkg .= '.pm'; require $ttpkg; } else { $ttmodule = $TTMODULE; } # load custom Template::Directive configuration map { my $v = $ttdirectiveopts{ $_ }; if( defined $v ) { ${ $Template::Directive::{ uc $_ } } = $ttdirectiveopts{ $_ } } } keys %ttdirectiveopts; # add current directory to INCLUDE_PATH unshift(@{ $ucttopts->{ INCLUDE_PATH } }, '.'); # read from STDIN if no files specified push(@ARGV, '-') unless @ARGV; my $template = $ttmodule->new($ucttopts) || die $ttmodule->error(); my %ttvars = (); if ($ttenvvars) { $ttvars{'env'} = \%ENV; } # process each input file foreach my $file (@ARGV) { $file = \*STDIN if $file eq '-'; $template->process($file,\%ttvars) || die $template->error(); } sub read_config { my $file = shift; my $config = AppConfig->new( { ERROR => sub { die(@_, "\ntry `$NAME --help'\n") } }, 'help|h' => { ACTION => \&help }, 'template_absolute|absolute' => { DEFAULT => 1 }, 'template_relative|relative' => { DEFAULT => 1 }, 'template_module|module=s', 'template_anycase|anycase', 'template_eval_perl|eval_perl', 'template_load_perl|load_perl', 'template_interpolate|interpolate', 'template_pre_chomp|pre_chomp|prechomp', 'template_post_chomp|post_chomp|postchomp', 'template_trim|trim', 'template_variables|variables|define=s%', 'template_include_path|include_path|include|I=s@', 'template_pre_process|pre_process|preprocess=s@', 'template_post_process|post_process|postprocess=s@', 'template_process|process=s', 'template_wrapper|wrapper=s', 'template_recursion|recursion', 'template_expose_blocks|expose_blocks', 'template_default|default=s', 'template_error|error=s', 'template_debug|debug=s', 'template_start_tag|start_tag|starttag=s', 'template_end_tag|end_tag|endtag=s', 'template_tag_style|tag_style|tagstyle=s', 'template_compile_ext|compile_ext=s', 'template_compile_dir|compile_dir=s', 'template_plugin_base|plugin_base|pluginbase=s@', 'perl5lib|perllib=s@', 'template_envvars|envvars', 'template_directive_debug', 'template_directive_pretty', 'template_directive_while_max|while_max=i' ); # add the 'file' option now that we have a $config object that we # can reference in a closure $config->define( 'file|f=s@' => { EXPAND => AppConfig::EXPAND_ALL, ACTION => sub { my ($state, $item, $file) = @_; $file = $state->cfg . "/$file" unless $file =~ /^[\.\/]|(?:\w:)/; $config->file($file) } } ); # process main config file, then command line args $config->file($file) if -f $file; $config->args(); return $config; } sub help { print<<END_OF_HELP; $NAME $VERSION (Template Toolkit version $Template::VERSION) usage: $NAME [options] [files] Options: --define var=value Define template variable --interpolate Interpolate '\$var' references in text --anycase Accept directive keywords in any case. --pre_chomp Chomp leading whitespace --post_chomp Chomp trailing whitespace --trim Trim blank lines around template blocks --eval_perl Evaluate [% PERL %] ... [% END %] code blocks --load_perl Load regular Perl modules via USE directive --absolute Allow ABSOLUTE directories (enabled by default) --relative Allow RELATIVE directories (enabled by default) --include_path=DIR Add directory to INCLUDE_PATH --pre_process=TEMPLATE Process TEMPLATE before each main template --post_process=TEMPLATE Process TEMPLATE after each main template --process=TEMPLATE Process TEMPLATE instead of main template --wrapper=TEMPLATE Process TEMPLATE wrapper around main template --default=TEMPLATE Use TEMPLATE as default --error=TEMPLATE Use TEMPLATE to handle errors --debug=STRING Set TT DEBUG option to STRING --start_tag=STRING STRING defines start of directive tag --end_tag=STRING STRING defined end of directive tag --tag_style=STYLE Use pre-defined tag STYLE --plugin_base=PACKAGE Base PACKAGE for plugins --compile_ext=STRING File extension for compiled template files --compile_dir=DIR Directory for compiled template files --perl5lib=DIR Specify additional Perl library directories --template_module=MODULE Specify alternate Template module --while_max=INTEGER Change '\$Template::Directive::WHILE_MAX' default --envvars Set the 'env' variable to the environment (%ENV) See 'perldoc tpage' for further information. END_OF_HELP exit(0); } __END__ #------------------------------------------------------------------------ # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. #------------------------------------------------------------------------ =head1 NAME Template::Tools::tpage - Process templates from command line =head1 USAGE tpage [ --define var=value ] file(s) =head1 DESCRIPTION The B<tpage> script is a simple wrapper around the Template Toolkit processor. Files specified by name on the command line are processed in turn by the template processor and the resulting output is sent to STDOUT and can be redirected accordingly. e.g. tpage myfile > myfile.out tpage header myfile footer > myfile.html If no file names are specified on the command line then B<tpage> will read STDIN for input. The C<--define> option can be used to set the values of template variables. e.g. tpage --define author="Andy Wardley" skeleton.pm > MyModule.pm =head2 The F<.tpagerc> Configuration File You can use a F<.tpagerc> file in your home directory. The purpose of this file is to set any I<global> configuration options that you want applied I<every> time F<tpage> is run. For example, you can use the C<include_path> to use template files from a generic template directory. Run C<tpage -h> for a summary of the options available. See L<Template> for general information about the Perl Template Toolkit and the template language and features. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/|http://wardley.org/> =head1 VERSION 2.68, distributed as part of the Template Toolkit version 2.19, released on 27 April 2007. =head1 COPYRIGHT Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<ttree|Template::Tools::ttree> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[� ��ie ie lib/Template.pmnu ��6�$ #============================================================= -*-perl-*- # # Template # # DESCRIPTION # Module implementing a simple, user-oriented front-end to the Template # Toolkit. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== package Template; use strict; use warnings; use 5.006; use base 'Template::Base'; use Template::Config; use Template::Constants; use Template::Provider; use Template::Service; use File::Basename; use File::Path; use Scalar::Util qw(blessed); our $VERSION = '3.102'; our $ERROR = ''; our $DEBUG = 0; our $BINMODE = 0 unless defined $BINMODE; our $AUTOLOAD; # preload all modules if we're running under mod_perl Template::Config->preload() if $ENV{ MOD_PERL }; #------------------------------------------------------------------------ # process($input, \%replace, $output) # # Main entry point for the Template Toolkit. The Template module # delegates most of the processing effort to the underlying SERVICE # object, an instance of the Template::Service class. #------------------------------------------------------------------------ sub process { my ($self, $template, $vars, $outstream, @opts) = @_; my ($output, $error); my $options = (@opts == 1) && ref($opts[0]) eq 'HASH' ? shift(@opts) : { @opts }; $options->{ binmode } = $BINMODE unless defined $options->{ binmode }; # we're using this for testing in t/output.t and t/filter.t so # don't remove it if you don't want tests to fail... $self->DEBUG("set binmode\n") if $DEBUG && $options->{ binmode }; $output = $self->{ SERVICE }->process($template, $vars); if (defined $output) { $outstream ||= $self->{ OUTPUT }; unless (ref $outstream) { my $outpath = $self->{ OUTPUT_PATH }; $outstream = "$outpath/$outstream" if $outpath; } # send processed template to output stream, checking for error return ($self->error($error)) if ($error = &_output($outstream, \$output, $options)); return 1; } else { return $self->error($self->{ SERVICE }->error); } } #------------------------------------------------------------------------ # service() # # Returns a reference to the internal SERVICE object which handles # all requests for this Template object #------------------------------------------------------------------------ sub service { my $self = shift; return $self->{ SERVICE }; } #------------------------------------------------------------------------ # context() # # Returns a reference to the CONTEXT object within the SERVICE # object. #------------------------------------------------------------------------ sub context { my $self = shift; return $self->{ SERVICE }->{ CONTEXT }; } sub template { shift->context->template(@_); } #======================================================================== # -- PRIVATE METHODS -- #======================================================================== #------------------------------------------------------------------------ # _init(\%config) #------------------------------------------------------------------------ sub _init { my ($self, $config) = @_; # convert any textual DEBUG args to numerical form my $debug = $config->{ DEBUG }; $config->{ DEBUG } = Template::Constants::debug_flags($self, $debug) || return if defined $debug && $debug !~ /^\d+$/; # prepare a namespace handler for any CONSTANTS definition if (my $constants = $config->{ CONSTANTS }) { my $ns = $config->{ NAMESPACE } ||= { }; my $cns = $config->{ CONSTANTS_NAMESPACE } || 'constants'; $constants = Template::Config->constants($constants) || return $self->error(Template::Config->error); $ns->{ $cns } = $constants; } $self->{ SERVICE } = $config->{ SERVICE } || Template::Config->service($config) || return $self->error(Template::Config->error); $self->{ OUTPUT } = $config->{ OUTPUT } || \*STDOUT; $self->{ OUTPUT_PATH } = $config->{ OUTPUT_PATH }; return $self; } #------------------------------------------------------------------------ # _output($where, $text) #------------------------------------------------------------------------ sub _output { my ($where, $textref, $options) = @_; my $reftype; my $error = 0; # call a CODE reference if (($reftype = ref($where)) eq 'CODE') { &$where($$textref); } # print to a glob (such as \*STDOUT) elsif ($reftype eq 'GLOB') { print $where $$textref; } # append output to a SCALAR ref elsif ($reftype eq 'SCALAR') { $$where .= $$textref; } # push onto ARRAY ref elsif ($reftype eq 'ARRAY') { push @$where, $$textref; } # call the print() method on an object that implements the method # (e.g. IO::Handle, Apache::Request, etc) elsif (blessed($where) && $where->can('print')) { $where->print($$textref); } # a simple string is taken as a filename elsif (! $reftype) { local *FP; # make destination directory if it doesn't exist my $dir = dirname($where); eval { mkpath($dir) unless -d $dir; }; if ($@) { # strip file name and line number from error raised by die() ($error = $@) =~ s/ at \S+ line \d+\n?$//; } elsif (open(FP, '>', $where)) { # binmode option can be 1 or a specific layer, e.g. :utf8 my $bm = $options->{ binmode }; if (not(defined $bm)) { $bm = $BINMODE; } if ($bm && $bm eq 1) { binmode FP; } elsif ($bm){ binmode FP, $bm; } print FP $$textref; close FP; } else { $error = "$where: $!"; } } # give up, we've done our best else { $error = "output_handler() cannot determine target type ($where)\n"; } return $error; } 1; __END__ =head1 NAME Template - Front-end module to the Template Toolkit =head1 SYNOPSIS use Template; # some useful options (see below for full list) my $config = { INCLUDE_PATH => '/search/path', # or list ref INTERPOLATE => 1, # expand "$var" in plain text POST_CHOMP => 1, # cleanup whitespace PRE_PROCESS => 'header', # prefix each template EVAL_PERL => 1, # evaluate Perl code blocks }; # create Template object my $template = Template->new($config); # define template variables for replacement my $vars = { var1 => $value, var2 => \%hash, var3 => \@list, var4 => \&code, var5 => $object, }; # specify input filename, or file handle, text reference, etc. my $input = 'myfile.html'; # process input template, substituting variables $template->process($input, $vars) || die $template->error(); =head1 DESCRIPTION This documentation describes the Template module which is the direct Perl interface into the Template Toolkit. It covers the use of the module and gives a brief summary of configuration options and template directives. Please see L<Template::Manual> for the complete reference manual which goes into much greater depth about the features and use of the Template Toolkit. The L<Template::Tutorial> is also available as an introductory guide to using the Template Toolkit. =head1 METHODS =head2 new(\%config) The C<new()> constructor method (implemented by the L<Template::Base|Template::Base#new()> base class) instantiates a new C<Template> object. A reference to a hash array of configuration items may be passed as a parameter. my $tt = Template->new({ INCLUDE_PATH => '/usr/local/templates', EVAL_PERL => 1, }) || die $Template::ERROR, "\n"; A reference to a new C<Template> object is returned, or undef on error. In the latter case, the error message can be retrieved by calling L<error()> as a class method or by examining the C<$Template::ERROR> package variable directly. my $tt = Template->new(\%config) || die Template->error(), "\n"; my $tt = Template->new(\%config) || die $Template::ERROR, "\n"; For convenience, configuration items may also be specified as a list of items instead of a hash array reference. These are automatically folded into a hash array by the constructor. my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1) || die $Template::ERROR, "\n"; =head2 process($template, \%vars, $output, %options) The C<process()> method is called to process a template. The first parameter indicates the input template as one of: =over 4 =item * a filename relative to C<INCLUDE_PATH>, if defined =item * a reference to a text string containing the template text =item * a file handle reference (e.g. C<IO::Handle> or sub-class) or C<GLOB> (e.g. C<\*STDIN>), from which the template can be read. =back A reference to a hash array may be passed as the second parameter, containing definitions of template variables. # filename $tt->process('welcome.tt2') || die $tt->error(), "\n"; # text reference $text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]"; $tt->process(\$text) || die $tt->error(), "\n"; # file handle (GLOB) $tt->process(\*DATA) || die $tt->error(), "\n"; __END__ [% INCLUDE header %] This is a template defined in the __END__ section which is accessible via the DATA "file handle". [% INCLUDE footer %] By default, the processed template output is printed to C<STDOUT>. The C<process()> method then returns C<1> to indicate success. A third parameter may be passed to the C<process()> method to specify a different output location. This value may be one of: =over 4 =item * a plain string indicating a filename which will be opened (relative to C<OUTPUT_PATH>, if defined) and the output written to =item * a file GLOB opened ready for output =item * a reference to a scalar (e.g. a text string) to which output/error is appended =item * a reference to a subroutine which is called, passing the output as a parameter =item * any object reference which implements a C<print()> method (e.g. C<IO::Handle>, C<Apache::Request>, etc.) which will be called, passing the generated output as a parameter. =back Examples: # output filename $tt->process('welcome.tt2', $vars, 'welcome.html') || die $tt->error(), "\n"; # reference to output subroutine sub myout { my $output = shift; ... } $tt->process('welcome.tt2', $vars, \&myout) || die $tt->error(), "\n"; # reference to output text string my $output = ''; $tt->process('welcome.tt2', $vars, \$output) || die $tt->error(), "\n"; print "output: $output\n"; In an Apache/mod_perl handler: sub handler { my $req = shift; # ...your code here... # direct output to Apache::Request via $req->print($output) $tt->process($file, $vars, $req) || do { $req->log_reason($tt->error()); return SERVER_ERROR; }; return OK; } After the optional third output argument can come an optional reference to a hash or a list of C<(name, value)> pairs providing further options for the output. The only option currently supported is C<binmode> which, when set to any true value will ensure that files created (but not any existing file handles passed) will be set to binary mode. # either: hash reference of options $tt->process($infile, $vars, $outfile, { binmode => 1 }) || die $tt->error(), "\n"; # or: list of name, value pairs $tt->process($infile, $vars, $outfile, binmode => 1) || die $tt->error(), "\n"; Alternately, the C<binmode> argument can specify a particular IO layer such as C<:utf8>. $tt->process($infile, $vars, $outfile, binmode => ':utf8') || die $tt->error(), "\n"; The C<OUTPUT> configuration item can be used to specify a default output location other than C<\*STDOUT>. The C<OUTPUT_PATH> specifies a directory which should be prefixed to all output locations specified as filenames. my $tt = Template->new({ OUTPUT => sub { ... }, # default OUTPUT_PATH => '/tmp', ... }) || die Template->error(), "\n"; # use default OUTPUT (sub is called) $tt->process('welcome.tt2', $vars) || die $tt->error(), "\n"; # write file to '/tmp/welcome.html' $tt->process('welcome.tt2', $vars, 'welcome.html') || die $tt->error(), "\n"; The C<process()> method returns C<1> on success or C<undef> on error. The error message generated in the latter case can be retrieved by calling the L<error()> method. See also L<CONFIGURATION SUMMARY> which describes how error handling may be further customised. =head2 error() When called as a class method, it returns the value of the C<$ERROR> package variable. Thus, the following are equivalent. my $tt = Template->new() || die Template->error(), "\n"; my $tt = Template->new() || die $Template::ERROR, "\n"; When called as an object method, it returns the value of the internal C<_ERROR> variable, as set by an error condition in a previous call to process(). $tt->process('welcome.tt2') || die $tt->error(), "\n"; Errors are represented in the Template Toolkit by objects of the L<Template::Exception> class. If the L<process()> method returns a false value then the C<error()> method can be called to return an object of this class. The L<type()|Template::Exception#type()> and L<info()|Template::Exception#info()> methods can called on the object to retrieve the error type and information string, respectively. The L<as_string()|Template::Exception#as_string()> method can be called to return a string of the form C<$type - $info>. This method is also overloaded onto the stringification operator allowing the object reference itself to be printed to return the formatted error string. $tt->process('somefile') || do { my $error = $tt->error(); print "error type: ", $error->type(), "\n"; print "error info: ", $error->info(), "\n"; print $error, "\n"; }; =head2 service() The C<Template> module delegates most of the effort of processing templates to an underlying L<Template::Service> object. This method returns a reference to that object. =head2 context() The L<Template::Service> module uses a core L<Template::Context> object for runtime processing of templates. This method returns a reference to that object and is equivalent to C<< $template-E<gt>service-E<gt>context() >>. =head2 template($name) This method is a simple wrapper around the L<Template::Context> method of the same name. It returns a compiled template for the source provided as an argument. =head1 CONFIGURATION SUMMARY The following list gives a short summary of each Template Toolkit configuration option. See L<Template::Manual::Config> for full details. =head2 Template Style and Parsing Options =head3 ENCODING Specifies the character encoding. =head3 START_TAG, END_TAG Define tokens that indicate start and end of directives (default: 'C<[%>' and 'C<%]>'). =head3 TAG_STYLE Set C<START_TAG> and C<END_TAG> according to a pre-defined style (default: 'C<template>', as above). =head3 PRE_CHOMP, POST_CHOMP Removes whitespace before/after directives (default: 0/0). =head3 TRIM Remove leading and trailing whitespace from template output (default: 0). =head3 INTERPOLATE Interpolate variables embedded like C<$this> or C<${this}> (default: 0). =head3 ANYCASE Allow directive keywords in lower case (default: 0 - UPPER only). =head2 Template Files and Blocks =head3 INCLUDE_PATH One or more directories to search for templates. =head3 DELIMITER Delimiter for separating paths in C<INCLUDE_PATH> (default: 'C<:>'). =head3 ABSOLUTE Allow absolute file names, e.g. C</foo/bar.html> (default: 0). =head3 RELATIVE Allow relative filenames, e.g. C<../foo/bar.html> (default: 0). =head3 DEFAULT Default template to use when another not found. =head3 BLOCKS Hash array pre-defining template blocks. =head3 AUTO_RESET Enabled by default causing C<BLOCK> definitions to be reset each time a template is processed. Disable to allow C<BLOCK> definitions to persist. =head3 RECURSION Flag to permit recursion into templates (default: 0). =head2 Template Variables =head3 VARIABLES Hash array of variables and values to pre-define in the stash. =head2 Runtime Processing Options =head3 EVAL_PERL Flag to indicate if C<PERL>/C<RAWPERL> blocks should be processed (default: 0). =head3 PRE_PROCESS, POST_PROCESS Name of template(s) to process before/after main template. =head3 PROCESS Name of template(s) to process instead of main template. =head3 ERROR Name of error template or reference to hash array mapping error types to templates. =head3 OUTPUT Default output location or handler. =head3 OUTPUT_PATH Directory into which output files can be written. =head3 DEBUG Enable debugging messages. =head2 Caching and Compiling Options =head3 CACHE_SIZE Maximum number of compiled templates to cache in memory (default: undef - cache all) =head3 COMPILE_EXT Filename extension for compiled template files (default: undef - don't compile). =head3 COMPILE_DIR Root of directory in which compiled template files should be written (default: undef - don't compile). =head2 Plugins and Filters =head3 PLUGINS Reference to a hash array mapping plugin names to Perl packages. =head3 PLUGIN_BASE One or more base classes under which plugins may be found. =head3 LOAD_PERL Flag to indicate regular Perl modules should be loaded if a named plugin can't be found (default: 0). =head3 FILTERS Hash array mapping filter names to filter subroutines or factories. =head2 Customisation and Extension =head3 LOAD_TEMPLATES List of template providers. =head3 LOAD_PLUGINS List of plugin providers. =head3 LOAD_FILTERS List of filter providers. =head3 TOLERANT Set providers to tolerate errors as declinations (default: 0). =head3 SERVICE Reference to a custom service object (default: L<Template::Service>). =head3 CONTEXT Reference to a custom context object (default: L<Template::Context>). =head3 STASH Reference to a custom stash object (default: L<Template::Stash>). =head3 PARSER Reference to a custom parser object (default: L<Template::Parser>). =head3 GRAMMAR Reference to a custom grammar object (default: L<Template::Grammar>). =head1 DIRECTIVE SUMMARY The following list gives a short summary of each Template Toolkit directive. See L<Template::Manual::Directives> for full details. =head2 GET Evaluate and print a variable or value. [% GET variable %] # 'GET' keyword is optional [% variable %] [% hash.key %] [% list.n %] [% code(args) %] [% obj.meth(args) %] [% "value: $var" %] =head2 CALL As per L<GET> but without printing result (e.g. call code) [% CALL variable %] =head2 SET Assign a values to variables. [% SET variable = value %] # 'SET' also optional [% variable = other_variable variable = 'literal text @ $100' variable = "interpolated text: $var" list = [ val, val, val, val, ... ] list = [ val..val ] hash = { var => val, var => val, ... } %] =head2 DEFAULT Like L<SET>, but variables are only set if currently unset (i.e. have no true value). [% DEFAULT variable = value %] =head2 INSERT Insert a file without any processing performed on the contents. [% INSERT legalese.txt %] =head2 PROCESS Process another template file or block and insert the generated output. Any template L<BLOCK>s or variables defined or updated in the C<PROCESS>ed template will thereafter be defined in the calling template. [% PROCESS template %] [% PROCESS template var = val, ... %] =head2 INCLUDE Similar to C<PROCESS>, but using a local copy of the current variables. Any template C<BLOCK>s or variables defined in the C<INCLUDE>d template remain local to it. [% INCLUDE template %] [% INCLUDE template var = val, ... %] =head2 WRAPPER The content between the C<WRAPPER> and corresponding C<END> directives is first evaluated, with the output generated being stored in the C<content> variable. The named template is then process as per C<INCLUDE>. [% WRAPPER layout %] Some template markup [% blah %]... [% END %] A simple F<layout> template might look something like this: Your header here... [% content %] Your footer here... =head2 BLOCK Define a named template block for L<INCLUDE>, L<PROCESS> and L<WRAPPER> to use. [% BLOCK hello %] Hello World [% END %] [% INCLUDE hello %] =head2 FOREACH Repeat the enclosed C<FOREACH> ... C<END> block for each value in the list. [% FOREACH variable IN [ val, val, val ] %] # either [% FOREACH variable IN list %] # or The variable is set to [% variable %] [% END %] =head2 WHILE The block enclosed between C<WHILE> and C<END> block is processed while the specified condition is true. [% WHILE condition %] content [% END %] =head2 IF / UNLESS / ELSIF / ELSE The enclosed block is processed if the condition is true / false. [% IF condition %] content [% ELSIF condition %] content [% ELSE %] content [% END %] [% UNLESS condition %] content [% # ELSIF/ELSE as per IF, above %] content [% END %] =head2 SWITCH / CASE Multi-way switch/case statement. [% SWITCH variable %] [% CASE val1 %] content [% CASE [ val2, val3 ] %] content [% CASE %] # or [% CASE DEFAULT %] content [% END %] =head2 MACRO Define a named macro. [% MACRO name <directive> %] [% MACRO name(arg1, arg2) <directive> %] ... [% name %] [% name(val1, val2) %] =head2 FILTER Process enclosed C<FILTER> ... C<END> block then pipe through a filter. [% FILTER name %] # either [% FILTER name( params ) %] # or [% FILTER alias = name( params ) %] # or content [% END %] =head2 USE Load a plugin module (see C<Template::<Manual::Plugins>), or any regular Perl module when the C<LOAD_PERL> option is set. [% USE name %] # either [% USE name( params ) %] # or [% USE var = name( params ) %] # or ... [% name.method %] [% var.method %] =head2 PERL / RAWPERL Evaluate enclosed blocks as Perl code (requires the C<EVAL_PERL> option to be set). [% PERL %] # perl code goes here $stash->set('foo', 10); print "set 'foo' to ", $stash->get('foo'), "\n"; print $context->include('footer', { var => $val }); [% END %] [% RAWPERL %] # raw perl code goes here, no magic but fast. $output .= 'some output'; [% END %] =head2 TRY / THROW / CATCH / FINAL Exception handling. [% TRY %] content [% THROW type info %] [% CATCH type %] catch content [% error.type %] [% error.info %] [% CATCH %] # or [% CATCH DEFAULT %] content [% FINAL %] this block is always processed [% END %] =head2 NEXT Jump straight to the next item in a C<FOREACH> or C<WHILE> loop. [% NEXT %] =head2 LAST Break out of C<FOREACH> or C<WHILE> loop. [% LAST %] =head2 RETURN Stop processing current template and return to including templates. [% RETURN %] =head2 STOP Stop processing all templates and return to caller. [% STOP %] =head2 TAGS Define new tag style or characters (default: C<[%> C<%]>). [% TAGS html %] [% TAGS <!-- --> %] =head2 COMMENTS Ignored and deleted. [% # this is a comment to the end of line foo = 'bar' %] [%# placing the '#' immediately inside the directive tag comments out the entire directive %] =head1 SOURCE CODE REPOSITORY The source code for the Template Toolkit is held in a public git repository on Github: L<https://github.com/abw/Template2> =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 VERSION Template Toolkit version 3.100, released on July 13 2020. =head1 SUPPORT The Template Toolkit mailing list provides a forum for discussing issues relating to the use and abuse of the Template Toolkit. There are a number of knowledgeable and helpful individuals who frequent the list (including the author) who can often offer help or suggestions. Please respect their time and patience by checking the documentation and/or mailing list archives before asking questions that may already have been answered. To subscribe to the mailing list, send an email to: template-toolkit+subscribe@groups.io You can also use the web interface: https://groups.io/g/template-toolkit For information about commercial support and consultancy for the Template Toolkit, please contact the author. =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�zSiN N lib/Template/Manual/Credits.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Credits # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =encoding utf8 =head1 NAME Template::Manual::Credits - Author and contributor credits =head1 HISTORY The Template Toolkit began its life as the C<Text::MetaText> module, originally released to CPAN around 1996. This itself was the public manifestation of an earlier template processing system I developed while working at Peritas (now Knowledge Pool - http://www.knowledgepool.com/) C<Text::MetaText> was the prototype - the one we always planned to throw away. It did the job well, showing us what worked and what didn't, what was good and what was bad, and gave us some ideas about what could be done better, given the chance to start again from scratch. Some time late in 1998 I threw away the prototype and started work on the Template Toolkit. By then I was working at Canon Research Centre Europe Ltd. (CRE), involved in a general research programme related to web publishing and dynamic content generation. The first alpha release was in June 1999, followed by numerous more alpha and beta releases culminating in 1.00 being released on 2nd December 1999. A month or so later, work had begun on version 2.00. The plan was to get the template language relatively stable in version 1.00 and not worry too much about performance or other internal matters. Then, version 2.00 would follow to improve performance, clean up the architecture and fix anything that, with the benefit of hindsight, we thought could be improved. As it happens, me starting work on version 2.00 coincided with Doug Steinwand sending me his parser variant which compiled templates to Perl code, giving a major performance boost. As well as the speedups, there are a whole host of significant new features in version 2.00, and a greatly improved internal architecture. Apart from a few minor "fixups" the template directives and language have remained the same as in version 1.00 Version 2.00 was available in beta release form in July 2000, just in time for the 4th Perl Conference where version 1.00 was awarded "Best New Perl Module". After another extended beta release period, version 2.00 was released on 1st December 2000. Version 3 has been in development ever since. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2020 Andy Wardley. All Rights Reserved. The Template Toolkit is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 CONTRIBUTORS Many people have contributed ideas, inspiration, fixes and features to the Template Toolkit. Their efforts continue to be very much appreciated. Please let me know if you think anyone is missing from this list. If you submit a patch/pull request then please make sure you add your own name to this list and include it in the changes. Adam Kennedy, ahollandECS, Alexey A. Kiritchun, Amiri Barksdale, Andreas Koenig, Andy Wardley, Autrijus Tang, Axel Gerstmair, Barrie Slaymaker, Ben Tilly, Breno G. de Oliveira, Briac PilprE<eacute>, Brian Fraser, Brian Wightman, Bryce Harrington, Chris Dean, Chris Winters, Christian, chromatic, Colin Johnson, Colin Keith, Craig Barratt, Darren Chamberlain, Dave Cash, Dave Cross, Dave Hodgkinson, Dave Howorth, Dave Jacoby, David Steinbrunner, Denis F. Latypoff, Dennis Clark, Doug, Drew Taylor, Dylan, E. Choroba, eadjei, Eric Cholet, Francois Desarmenien, François Andriot, fREW Schmidt, gordon-fish, Guido Flohr, Hans von Lengerke, Harald Joerg, Horst Dumcke, Ivan Krylov, Ivan Kurmanov, Jacques Germishuys, Jason Lewis, Jay Hannah, Jens Rehsack, Jess Robinson, Jim Vaughan, John Lightsey, John Napiorkowski, Jon Jensen, Jonas Liljegren, Jonathon Padfield, José Joaquín Atria, Jose Luis Martinez, Josh Rosenbaum, Kenny Gatdula, Kent Fredric, Kevin M. Goess, Koenig, Leon Brocard, Leslie Michael Orchard, Lubomir, Lyle Brooks, Marc Remy, Mark Fowler, Martin, Matthew Somerville, Michael Fowler, Michael Stevens, Mike Schilli, Mikhail Klyuchnikov from Positive Technologies, nataraj, Neil Bowers, Nick Hibma, Nicolas R, Nik Clayton, Norbert Buchmüller, Paul Orrock, Paul Seamons, Paul Sharpe, Perrin Harkins, Philippe Bruhat (BooK), Piers Cawley, Portman, Rafael Kitover, Randal L. Schwartz, Ricardo Signes, Richard Tietjen, Robin Berjon, Rod Taylor, Schaffner, sdeseille, Sean McAfee, Sean Zellmer, Simon, Simon Dawson, Simon Matthews, Simon Napiorkowski, Slaven Rezic, Smylers, Stas Bekman, Stathy G. Touloumis, stefano-b, Steinwand, Steve Peters, Swen, Thierry-Michel Barral, Thuemmler, Timmy Chan, Todd Rinaldo, Tom Delmas, Tony Bowden, Tosh Cooey, Ville SkyttE<auml>, Vivek Khera, Wilcox, William Hardison, Yanick Champoux, Yuri Pimenov. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[� �ܑ% �% lib/Template/Manual/Intro.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Intro # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Intro - Introduction to the Template Toolkit =head1 Introduction The Template Toolkit is a collection of Perl modules which implement a fast, flexible, powerful and extensible template processing system. It is most often used for generating dynamic web content, although it can be used equally well for processing any kind of text documents. At the simplest level it provides an easy way to process template files, filling in embedded variable references with their equivalent values. Here's an example of a template. Dear [% name %], It has come to our attention that your account is in arrears to the sum of [% debt %]. Please settle your account before [% deadline %] or we will be forced to revoke your Licence to Thrill. The Management. By default, template directives are embedded within the character sequences C<[%> ... C<%]> but you can change these and various other options to configure how the Template Toolkit looks, feels and works. You can set the C<INTERPOLATE> option, for example, if you prefer to embed your variables in Perl style: Dear $name, It has come to our attention that your account is in arrears to the sum of $debt. ...etc... =head1 The Template Perl Module The L<Template> Perl module is the front end to the Template Toolkit for Perl programmers, providing access to the full range of functionality through a single module with a simple interface. It loads the other modules as required and instantiates a default set of objects to handle subsequent template processing requests. Configuration parameters may be passed to the L<Template> constructor method, L<new()|Template#new()>, which are then used to configure the generate object. use Template; my $tt = Template->new({ INCLUDE_PATH => '/usr/local/templates', INTERPOLATE => 1, }) || die "$Template::ERROR\n"; The L<Template> object implements a L<process()|Template#process()> method for processing template files or text. The name of the input template (or various other sources) is passed as the first argument, followed by a reference to a hash array of variable definitions for substitution in the template. my $vars = { name => 'Count Edward van Halen', debt => '3 riffs and a solo', deadline => 'the next chorus', }; $tt->process('letters/overdrawn', $vars) || die $tt->error(), "\n"; The L<process()|Template#process()> method returns a true value (C<1>) on success and prints the template output to C<STDOUT>, by default. On error, the L<process()|Template#process()> method returns a false value (C<undef>). The L<error()|Template#error()> method can then be called to retrieve details of the error. =head1 Component Based Content Construction A number of special directives are provided, such as C<INSERT>, C<INCLUDE> and C<PROCESS>, which allow content to be built up from smaller template components. This permits a modular approach to building a web site or other content repository, promoting reusability, cross-site consistency, ease of construction and subsequent maintenance. Common elements such as headers, footers, menu bars, tables, and so on, can be created as separate template files which can then be processed into other documents as required. All defined variables are inherited by these templates along with any additional "local" values specified. [% PROCESS header title = "The Cat Sat on the Mat" %] [% PROCESS menu %] The location of the missing feline has now been established. Thank you for your assistance. [% INSERT legal/disclaimer %] [% PROCESS footer %] You can also define a template as a BLOCK within the same file and PROCESS it just like any other template file. This can be invaluable for building up repetitive elements such as tables, menus, etc. [% BLOCK tabrow %] <tr><td>[% name %]</td><td>[% email %]</td></tr> [% END %] <table> [% PROCESS tabrow name="tom" email="tom@here.org" %] [% PROCESS tabrow name="dick" email="disk@there.org" %] [% PROCESS tabrow name="larry" email="larry@where.org" %] </table> =head1 Data and Code Binding One of the key features that sets the Template Toolkit apart from other template processors is the ability to bind template variables to any kind of Perl data: scalars, lists, hash arrays, sub-routines and objects. my $vars = { root => 'http://here.com/there', menu => [ 'modules', 'authors', 'scripts' ], client => { name => 'Doctor Joseph von Satriani', id => 'JVSAT', }, checkout => sub { my $total = shift; ...; return $something }, shopcart => My::Cool::Shopping::Cart->new(), }; The Template Toolkit will automatically Do The Right Thing to access the data in an appropriate manner to return some value which can then be output. The dot operator 'C<.>' is used to access into lists and hashes or to call object methods. The C<FOREACH> directive is provided for iterating through lists, and various logical tests are available using directives such as C<IF>, C<UNLESS>, C<ELSIF>, C<ELSE>, C<SWITCH>, C<CASE>, etc. [% FOREACH section = menu %] <a href="[% root %]/[% section %]/index.html">[% section %]</a> [% END %] <b>Client</b>: [% client.name %] (id: [% client.id %]) [% IF shopcart.nitems %] Your shopping cart contains the following items: <ul> [% FOREACH item = shopcart.contents %] <li>[% item.name %] : [% item.qty %] @ [% item.price %] [% END %] </ul> [% checkout(shopcart.total) %] [% ELSE %] No items currently in shopping cart. [% END %] =head1 Advanced Features: Filters, Macros, Exceptions, Plugins The Template Toolkit also provides a number of additional directives for advanced processing and programmatical functionality. It supports output filters (FILTER), allows custom macros to be defined (MACRO), has a fully-featured exception handling system (TRY, THROW, CATCH, FINAL) and supports a plugin architecture (USE) which allows special plugin modules and even regular Perl modules to be loaded and used with the minimum of fuss. The Template Toolkit is "just" a template processor but you can trivially extend it to incorporate the functionality of any Perl module you can get your hands on. Thus, it is also a scalable and extensible template framework, ideally suited for managing the presentation layer for application servers, content management systems and other web applications. =head1 Separating Presentation and Application Logic Rather than embedding Perl code or some other scripting language directly into template documents, it encourages you to keep functional components (i.e. Perl code) separate from presentation components (e.g. HTML templates). The template variables provide the interface between the two layers, allowing data to be generated in code and then passed to a template component for displaying (pipeline model) or for sub-routine or object references to be bound to variables which can then be called from the template as and when required (callback model). The directives that the Template Toolkit provide implement their own mini programming language, but they're not really designed for serious, general purpose programming. Perl is a far more appropriate language for that. If you embed application logic (e.g. Perl or other scripting language fragments) in HTML templates then you risk losing the clear separation of concerns between functionality and presentation. It becomes harder to maintain the two elements in isolation and more difficult, if not impossible, to reuse code or presentation elements by themselves. It is far better to write your application code in separate Perl modules, libraries or scripts and then use templates to control how the resulting data is presented as output. Thus you should think of the Template Toolkit language as a set of layout directives for displaying data, not calculating it. Having said that, the Template Toolkit doesn't force you into one approach or the other. It attempts to be pragmatic rather than dogmatic in allowing you to do whatever best gets the job done. Thus, if you enable the EVAL_PERL option then you can happily embed real Perl code in your templates within PERL ... END directives. =head1 Performance The Template Toolkit uses a fast YACC-like parser which compiles templates into Perl code for maximum runtime efficiency. It also has an advanced caching mechanism which manages in-memory and on-disk (i.e. persistent) versions of compiled templates. The modules that comprise the toolkit are highly configurable and the architecture around which they're built is designed to be extensible. The Template Toolkit provides a powerful framework around which content creation and delivery systems can be built while also providing a simple interface through the Template front-end module for general use. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��2�\G \G ! lib/Template/Manual/Internals.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Internals # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Internals - Template Toolkit internals =head1 Introduction This section of the documentation is aimed at developers wishing to know more about how the Template Toolkit works on the inside in order to extend or adapt it to their own needs. If that doesn't sound like you then you probably don't need to read this. There is no test afterwards. =head1 Outside Looking In The L<Template> module is simply a front end module which creates and uses a L<Template::Service> and pipes the output wherever you want it to go (C<STDOUT> by default, or maybe a file, scalar, etc). The C<Apache::Template> module (available separately from CPAN) is another front end. That creates a C<Template::Service::Apache> object, calls on it as required and sends the output back to the relevant C<Apache::Request> object. These front-end modules are really only there to handle any specifics of the environment in which they're being used. The C<Apache::Template> front end, for example, handles C<Apache::Request> specifics and configuration via the F<httpd.conf>. The regular L<Template> front-end deals with C<STDOUT>, variable refs, etc. Otherwise it is L<Template::Service> (or subclass) which does all the work. The L<Template::Service> module provides a high-quality template delivery service, with bells, whistles, signed up service level agreement and a 30-day no quibble money back guarantee. "Have a good time, all the time", that's our motto. Within the lower levels of the Template Toolkit, there are lots of messy details that we generally don't want to have to worry about most of the time. Things like templates not being found, or failing to parse correctly, uncaught exceptions being thrown, missing plugin modules or dependencies, and so on. L<Template::Service> hides that all away and makes everything look simple to the outsider. It provides extra features, like C<PRE_PROCESS>, C<PROCESS> and C<POST_PROCESS>, and also provides the error recovery mechanism via C<ERROR>. You ask it to process a template and it takes care of everything for you. The C<Template::Service::Apache> module goes a little bit further, adding some extra headers to the L<Apache::Request>, setting a few extra template variables, and so on. For the most part, the job of a service is really just one of scheduling and dispatching. It receives a request in the form of a call to its L<process()|Template::Service#process()> method and schedules the named template specified as an argument, and possibly several other templates (C<PRE_PROCESS>, etc) to be processed in order. It doesn't actually process the templates itself, but instead makes a L<process()|Template::Context#process()> call against a L<Template::Context> object. L<Template::Context> is the runtime engine for the Template Toolkit - the module that hangs everything together in the lower levels of the Template Toolkit and that one that does most of the real work, albeit by crafty delegation to various other friendly helper modules. Given a template name (or perhaps a reference to a scalar or file handle) the context process() method must load and compile, or fetch a cached copy of a previously compiled template, corresponding to that name. It does this by calling on a list of one or more L<Template::Provider> objects (the C<LOAD_TEMPLATES> posse) who themselves might get involved with a L<Template::Parser> to help turn source templates into executable Perl code (but more on that later). Thankfully, all of this complexity is hidden away behind a simple L<template()|Template::Context#template()> method. You call it passing a template name as an argument, and it returns a compiled template in the form of a L<Template::Document> object, or otherwise raises an exception. A L<Template::Document> is a thin object wrapper around a compiled template subroutine. The object implements a L<process()|Template::Document#process()> method which performs a little bit of housekeeping and then calls the template subroutine. The object also defines template metadata (defined in C<[% META ... %]> directives) and has a L<block()|Template::Document#block()> method which returns a hash of any additional C<[% BLOCK xxxx %]> definitions found in the template source. So the context fetches a compiled document via its own L<template()|Template::Context#template()> method and then gets ready to process it. It first updates the stash (the place where template variables get defined - more on that shortly) to set any template variable definitions specified as the second argument by reference to hash array. Then, it calls the document L<process()|Template::Document#process()> method, passing a reference to itself, the context object, as an argument. In doing this, it provides itself as an object against which template code can make callbacks to access runtime resources and Template Toolkit functionality. What we're trying to say here is this: not only does the L<Template::Context> object receive calls from the I<outside>, i.e. those originating in user code calling the process() method on a Template object, but it also receives calls from the I<inside>, i.e. those originating in template directives of the form C<[% PROCESS template %]>. Before we move on to that, here's a simple structure diagram showing the outer layers of the Template Toolkit heading inwards, with pseudo code annotations showing a typical invocation sequence. ,--------. | Caller | use Template; `--------' my $tt = Template->new( ... ); | $tt->process($template, \%vars); | Outside - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - T T | package Template; Inside V +----------+ sub process($template, \%vars) { | Template | $out = $self->SERVICE->process($template, $vars); +----------+ print $out or send it to $self->OUTPUT; | } | | package Template::Service; | | sub process($template, \%vars) { | try { +----------+ foreach $p in @self->PRE_PROCESS | Service | $self->CONTEXT->process($p, $vars); +----------+ | $self->CONTEXT->process($template, $vars); | | foreach $p @self->POST_PROCESS | $self->CONTEXT->process($p, $vars); | } | catch { | $self->CONTEXT->process($self->ERROR); | } | } | V package Template::Context; +----------+ | Context | sub process($template, \%vars) { +----------+ # fetch compiled template | $template = $self->template($template) | # update stash | $self->STASH->update($vars); | # process template | $template->process($self) | } V +----------+ package Template::Document; | Document | +----------+ sub process($context) { $output = &{ $self->BLOCK }($context); } =head1 Inside Looking Out To understand more about what's going on in these lower levels, we need to look at what a compiled template looks like. In fact, a compiled template is just a regular Perl sub-routine. Here's a very simple one. sub my_compiled_template { return "This is a compiled template.\n"; } You're unlikely to see a compiled template this simple unless you wrote it yourself but it is entirely valid. All a template subroutine is obliged to do is return some output (which may be an empty of course). If it can't for some reason, then it should raise an error via C<die()>. sub my_todo_template { die "This template not yet implemented\n"; } If it wants to get fancy, it can raise an error as a L<Template::Exception> object. An exception object is really just a convenient wrapper for the 'C<type>' and 'C<info>' fields. sub my_solilique_template { die (Template::Exception->new('yorrick', 'Fellow of infinite jest')); } Templates generally need to do a lot more than just generate static output or raise errors. They may want to inspect variable values, process another template, load a plugin, run a filter, and so on. Whenever a template subroutine is called, it gets passed a reference to a L<Template::Context> object. It is through this context object that template code can access the features of the Template Toolkit. We described earlier how the L<Template::Service> object calls on L<Template::Context> to handle a L<process()|Template::Context#process()> request from the I<outside>. We can make a similar request on a context to process a template, but from within the code of another template. This is a call from the I<inside>. sub my_process_template { my $context = shift; my $output = $context->process('header', { title => 'Hello World' }) . "\nsome content\n" . $context->process('footer'); } This is then roughly equivalent to a source template something like this: [% PROCESS header title = 'Hello World' %] some content [% PROCESS footer %] Template variables are stored in, and managed by a L<Template::Stash> object. This is a blessed hash array in which template variables are defined. The object wrapper provides L<get()|Template::Stash#get()> and L<set()|Template::Stash#set()> method which implement all the I<magical.variable.features> of the Template Toolkit. Each context object has its own stash, a reference to which can be returned by the appropriately named L<stash()|Template::Context#stash()> method. So to print the value of some template variable, or for example, to represent the following source template: <title>[% title %]</title> we might have a subroutine definition something like this: sub { my $context = shift; my $stash = $context->stash(); return '<title>' . $stash->get('title') . '</title>'; } The stash L<get()|Template::Stash#get()> method hides the details of the underlying variable types, automatically calling code references, checking return values, and performing other such tricks. If 'C<title>' happens to be bound to a subroutine then we can specify additional parameters as a list reference passed as the second argument to get(). [% title('The Cat Sat on the Mat') %] This translates to the stash call: $stash->get([ 'title', ['The Cat Sat on the Mat'] ]); Dotted compound variables can be requested by passing a single list reference to the C<get()> method in place of the variable name. Each pair of elements in the list should correspond to the variable name and reference to a list of arguments for each dot-delimited element of the variable. [% foo(1, 2).bar(3, 4).baz(5) %] is thus equivalent to $stash->get([ foo => [1,2], bar => [3,4], baz => [5] ]); If there aren't any arguments for an element, you can specify an empty, zero or null argument list. [% foo.bar %] $stash->get([ 'foo', 0, 'bar', 0 ]); The L<set()|Template::Stash#set()> method works in a similar way. It takes a variable name and a variable value which should be assigned to it. [% x = 10 %] $stash->set('x', 10); [% x.y = 10 %] $stash->set([ 'x', 0, 'y', 0 ], 10); So the stash gives us access to template variables and the context provides the higher level functionality. Alongside the L<process()|Template::Context#process()> method lies the L<include()|Template::Context#include()> method. Just as with the C<PROCESS> / C<INCLUDE> directives, the key difference is in variable localisation. Before processing a template, the C<process()> method simply updates the stash to set any new variable definitions, overwriting any existing values. In contrast, the C<include()> method creates a copy of the existing stash, in a process known as I<cloning> the stash, and then uses that as a temporary variable store. Any previously existing variables are still defined, but any changes made to variables, including setting the new variable values passed aas arguments will affect only the local copy of the stash (although note that it's only a shallow copy, so it's not foolproof). When the template has been processed, the C<include()> method restores the previous variable state by I<decloning> the stash. The context also provides an L<insert()|Template::Context#insert()> method to implement the C<INSERT> directive, but no C<wrapper()> method. This functionality can be implemented by rewriting the Perl code and calling C<include()>. [% WRAPPER foo -%] blah blah [% x %] [%- END %] $context->include('foo', { content => 'blah blah ' . $stash->get('x'), }); Other than the template processing methods C<process()>, C<include()> and C<insert()>, the context defines methods for fetching plugin objects, L<plugin()|Template::Context#plugin()>, and filters, L<filter()|Template::Context#filter()>. # TT USE directive [% USE foo = Bar(10) %] # equivalent Perl $stash->set('foo', $context->plugin('Bar', [10])); # TT FILTER block [% FILTER bar(20) %] blah blah blah [% END %] # equivalent Perl my $filter = $context->filter('bar', [20]); &$filter('blah blah blah'); Pretty much everything else you might want to do in a template can be done in Perl code. Things like C<IF>, C<UNLESS>, C<FOREACH> and so on all have direct counterparts in Perl. # TT IF directive [% IF msg %] Message: [% msg %] [% END %]; # equivalent Perl if ($stash->get('msg')) { $output .= 'Message: '; $output .= $stash->get('msg'); } The best way to get a better understanding of what's going on underneath the hood is to set the C<$Template::Parser::DEBUG> flag to a true value and start processing templates. This will cause the parser to print the generated Perl code for each template it compiles to C<STDERR>. You'll probably also want to set the C<$Template::Directive::PRETTY> option to have the Perl pretty-printed for human consumption. use Template; use Template::Parser; use Template::Directive; $Template::Parser::DEBUG = 1; $Template::Directive::PRETTY = 1; my $template = Template->new(); $template->process(\*DATA, { cat => 'dog', mat => 'log' }); __DATA__ The [% cat %] sat on the [% mat %] The output sent to C<STDOUT> remains as you would expect: The dog sat on the log The output sent to C<STDERR> would look something like this: compiled main template document block: sub { my $context = shift || die "template sub called without context\n"; my $stash = $context->stash; my $output = ''; my $error; eval { BLOCK: { $output .= "The "; $output .= $stash->get('cat'); $output .= " sat on the "; $output .= $stash->get('mat'); $output .= "\n"; } }; if ($@) { $error = $context->catch($@, \$output); die $error unless $error->type eq 'return'; } return $output; } =head1 Hacking on the Template Toolkit Please feel free to hack on the Template Toolkit. If you find a bug that needs fixing, if you have an idea for something that's missing, or you feel inclined to tackle something on the TODO list, then by all means go ahead and do it! If you're contemplating something non-trivial then you'll probably want to bring it up on the mailing list first to get an idea about the current state of play, find out if anyone's already working on it, and so on. The source code repository for the Template Toolkit is hosted at Github. https://github.com/abw/Template2 Clone the repository, make your changes, commit them, then send a pull request. Once you've made your changes, please remember to update the test suite by adding extra tests to one of the existing test scripts in the C<t> sub-directory, or by adding a new test script of your own. And of course, run C<make test> to ensure that all the tests pass with your new code. Don't forget that any files you do add will need to be added to the MANIFEST. Running C<make manifest> will do this for you, but you need to make sure you haven't got any other temporary files lying around that might also get added to it. Documentation is often something that gets overlooked but it's just as important as the code. If you're adding a new module, a plugin module, for example, then it's OK to include the POD documentation in with the module, but I<please> write it all in one piece at the end of the file, I<after> the code (just look at any other C<Template::*> module for an example). It's a religious issue, I know, but I have a strong distaste for POD documentation interspersed throughout the code. In my not-so-humble opinion, it makes both the code and the documentation harder to read (same kinda problem as embedding Perl in HTML). Then add a line to the Changes file giving a very brief description of what you've done. There's no need to go into detail here (save that for the commit message, comments in code or docuemtation where appropriate). Please also make sure you add your name to the lib/Template/Manual/Credits.pod file (if it isn't already there). Then commit your changes and send a pull request. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[���U# U# lib/Template/Manual/Plugins.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Plugins # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Plugins - Standard plugins =head1 TEMPLATE TOOLKIT PLUGINS The following plugin modules are distributed with the Template Toolkit. Some of the plugins interface to external modules (detailed below) which should be downloaded from any CPAN site and installed before using the plugin. =head2 Assert New in 2.20! The L<Assert|Template::Plugin::Assert> plugin adds an C<assert> virtual method that you can use to catch undefined values. For example, consider this dotop: [% user.name %] If C<user.name> is an undefined value then TT will silently ignore the fact and print nothing. If you C<USE> the C<assert> plugin then you can add the C<assert> vmethod between the C<user> and C<name> elements, like so: [% user.assert.name %] Now, if C<user.name> is an undefined value, an exception will be thrown: assert error - undefined value for name =head2 CGI The L<CGI|Template::Plugin::CGI> plugin is a wrapper around Lincoln Stein's CGI.pm module. The plugin is distributed with the Template Toolkit (see L<Template::Plugin::CGI>) and the L<CGI> module itself is distributed with recent versions Perl, or is available from CPAN. [% USE CGI %] [% CGI.param('param_name') %] [% CGI.start_form %] [% CGI.popup_menu( Name => 'color', Values => [ 'Green', 'Brown' ] ) %] [% CGI.end_form %] =head2 Datafile Provides an interface to data stored in a plain text file in a simple delimited format. The first line in the file specifies field names which should be delimiter by any non-word character sequence. Subsequent lines define data using the same delimiter as in the first line. Blank lines and comments (lines starting '#') are ignored. See L<Template::Plugin::Datafile> for further details. /tmp/mydata: # define names for each field id : email : name : tel # here's the data fred : fred@here.com : Fred Smith : 555-1234 bill : bill@here.com : Bill White : 555-5678 example: [% USE userlist = datafile('/tmp/mydata') %] [% FOREACH user = userlist %] [% user.name %] ([% user.id %]) [% END %] =head2 Date The L<Date|Template::Plugin::Date> plugin provides an easy way to generate formatted time and date strings by delegating to the L<POSIX> C<strftime()> routine. See L<Template::Plugin::Date> and L<POSIX> for further details. [% USE date %] [% date.format %] # current time/date File last modified: [% date.format(template.modtime) %] =head2 Directory The L<Directory|Template::Plugin::Directory> plugin provides a simple interface to a directory and the files within it. See L<Template::Plugin::Directory> for further details. [% USE dir = Directory('/tmp') %] [% FOREACH file = dir.files %] # all the plain files in the directory [% END %] [% FOREACH file = dir.dirs %] # all the sub-directories [% END %] =head2 DBI The C<DBI> plugin is no longer distributed as part of the Template Toolkit (as of version 2.15). It is now available as a separate L<Template::DBI> distribution from CPAN. =head2 Dumper The L<Dumper|Template::Plugin::Dumper> plugin provides an interface to the Data::Dumper module. See L<Template::Plugin::Dumper> and L<Data::Dumper> for further details. [% USE dumper(indent=0, pad="<br>") %] [% dumper.dump(myvar, yourvar) %] =head2 File The L<File|Template::Plugin::File> plugin provides a general abstraction for files and can be used to fetch information about specific files within a filesystem. See L<Template::Plugin::File> for further details. [% USE File('/tmp/foo.html') %] [% File.name %] # foo.html [% File.dir %] # /tmp [% File.mtime %] # modification time =head2 Filter This module implements a base class plugin which can be subclassed to easily create your own modules that define and install new filters. package MyOrg::Template::Plugin::MyFilter; use Template::Plugin::Filter; use base qw( Template::Plugin::Filter ); sub filter { my ($self, $text) = @_; # ...mungify $text... return $text; } Example of use: # now load it... [% USE MyFilter %] # ...and use the returned object as a filter [% FILTER $MyFilter %] ... [% END %] See L<Template::Plugin::Filter> for further details. =head2 Format The L<Format|Template::Plugin::Format> plugin provides a simple way to format text according to a C<printf()>-like format. See L<Template::Plugin::Format> for further details. [% USE bold = format('<b>%s</b>') %] [% bold('Hello') %] =head2 GD The C<GD> plugins are no longer part of the core Template Toolkit distribution. They are now available from CPAN in a separate L<Template::GD> distribution. =head2 HTML The L<HTML|Template::Plugin::HTML> plugin is very basic, implementing a few useful methods for generating HTML. It is likely to be extended in the future or integrated with a larger project to generate HTML elements in a generic way. [% USE HTML %] [% HTML.escape("if (a < b && c > d) ..." %] [% HTML.attributes(border => 1, cellpadding => 2) %] [% HTML.element(table => { border => 1, cellpadding => 2 }) %] See L<Template::Plugin::HTML> for further details. =head2 Iterator The L<Iterator|Template::Plugin::Iterator> plugin provides a way to create a L<Template::Iterator> object to iterate over a data set. An iterator is created automatically by the C<FOREACH> directive and is aliased to the C<loop> variable. This plugin allows an iterator to be explicitly created with a given name, or the default plugin name, C<iterator>. See L<Template::Plugin::Iterator> for further details. [% USE iterator(list, args) %] [% FOREACH item = iterator %] [% '<ul>' IF iterator.first %] <li>[% item %] [% '</ul>' IF iterator.last %] [% END %] =head2 Pod This plugin provides an interface to the L<Pod::POM|Pod::POM> module which parses POD documents into an internal object model which can then be traversed and presented through the Template Toolkit. [% USE Pod(podfile) %] [% FOREACH head1 = Pod.head1; FOREACH head2 = head1/head2; ... END; END %] =head2 Scalar The Template Toolkit calls user-defined subroutines and object methods using Perl's array context by default. # TT2 calls object methods in array context by default [% object.method %] This plugin module provides a way for you to call subroutines and methods in scalar context. [% USE scalar %] # force it to use scalar context [% object.scalar.method %] # also works with subroutine references [% scalar.my_sub_ref %] =head2 String The L<String|Template::Plugin::String> plugin implements an object-oriented interface for manipulating strings. See L<Template::Plugin::String> for further details. [% USE String 'Hello' %] [% String.append(' World') %] [% msg = String.new('Another string') %] [% msg.replace('string', 'text') %] The string "[% msg %]" is [% msg.length %] characters long. =head2 Table The L<Table|Template::Plugin::Table> plugin allows you to format a list of data items into a virtual table by specifying a fixed number of rows or columns, with an optional overlap. See L<Template::Plugin::Table> for further details. [% USE table(list, rows=10, overlap=1) %] [% FOREACH item = table.col(3) %] [% item %] [% END %] =head2 URL The L<URL|Template::Plugin::URL> plugin provides a simple way of constructing URLs from a base part and a variable set of parameters. See L<Template::Plugin::URL> for further details. [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %] [% mycgi %] # ==> /cgi/bin/bar.pl?debug=1 [% mycgi(mode='submit') %] # ==> /cgi/bin/bar.pl?mode=submit&debug=1 =head2 Wrap The L<Wrap|Template::Plugin::Wrap> plugin uses the L<Text::Wrap> module to provide simple paragraph formatting. See L<Template::Plugin::Wrap> and L<Text::Wrap> for further details. [% USE wrap %] [% wrap(mytext, 40, '* ', ' ') %] # use wrap sub [% mytext FILTER wrap(40) -%] # or wrap FILTER The C<Text::Wrap> module is available from CPAN: http://www.cpan.org/modules/by-module/Text/ =head2 XML The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no longer distributed with the Template Toolkit as of version 2.15 They are now available in a separate L<Template::XML> distribution. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[l�OQ�6 �6 lib/Template/Manual/Filters.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Filters # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =encoding latin1 =head1 NAME Template::Manual::Filters - Standard filters =head1 format(format) The C<format> filter takes a format string as a parameter (as per C<printf()>) and formats each line of text accordingly. [% FILTER format('<!-- %-40s -->') %] This is a block of text filtered through the above format. [% END %] Output: <!-- This is a block of text filtered --> <!-- through the above format. --> =head1 upper Folds the input to UPPER CASE. [% "hello world" FILTER upper %] Output: HELLO WORLD =head1 lower Folds the input to lower case. [% "Hello World" FILTER lower %] Output: hello world =head1 ucfirst Folds the first character of the input to UPPER CASE. [% "hello" FILTER ucfirst %] Output: Hello =head1 lcfirst Folds the first character of the input to lower case. [% "HELLO" FILTER lcfirst %] Output: hELLO =head1 trim Trims any leading or trailing whitespace from the input text. Particularly useful in conjunction with C<INCLUDE>, C<PROCESS>, etc., having the same effect as the C<TRIM> configuration option. [% INCLUDE myfile | trim %] =head1 collapse Collapse any whitespace sequences in the input text into a single space. Leading and trailing whitespace (which would be reduced to a single space) is removed, as per trim. [% FILTER collapse %] The cat sat on the mat [% END %] Output: The cat sat on the mat =head1 html Converts the characters C<E<lt>>, C<E<gt>>, C<&> and C<"> to C<<>, C<>>, C<&>, and C<"> respectively, protecting them from being interpreted as representing HTML tags or entities. [% FILTER html %] Binary "<=>" returns -1, 0, or 1 depending on... [% END %] Output: Binary "<=>" returns -1, 0, or 1 depending on... =head1 html_entity The C<html> filter is fast and simple but it doesn't encode the full range of HTML entities that your text may contain. The C<html_entity> filter uses either the C<Apache::Util> module (which is written in C and is therefore faster) or the C<HTML::Entities> module (written in Perl but equally as comprehensive) to perform the encoding. If one or other of these modules are installed on your system then the text will be encoded (via the C<escape_html()> or C<encode_entities()> subroutines respectively) to convert all extended characters into their appropriate HTML entities (e.g. converting 'C<?>' to 'C<é>'). If neither module is available on your system then an 'C<html_entity>' exception will be thrown reporting an appropriate message. If you want to force TT to use one of the above modules in preference to the other, then call either of the L<Template::Filters> class methods: L<use_html_entities()|Template::Filters/use_html_entities()> or L<use_apache_util()|Template::Filters/use_apache_util()>. use Template::Filters; Template::Filters->use_html_entities; For further information on HTML entity encoding, see L<http://www.w3.org/TR/REC-html40/sgml/entities.html>. =head1 xml Same as the C<html> filter, but adds C<'> which is the fifth XML built-in entity. =head1 html_para This filter formats a block of text into HTML paragraphs. A sequence of two or more newlines is used as the delimiter for paragraphs which are then wrapped in HTML C<E<lt>pE<gt>>...C<E<lt>/pE<gt>> tags. [% FILTER html_para %] The cat sat on the mat. Mary had a little lamb. [% END %] Output: <p> The cat sat on the mat. </p> <p> Mary had a little lamb. </p> =head1 html_break / html_para_break Similar to the html_para filter described above, but uses the HTML tag sequence C<E<lt>brE<gt>E<lt>brE<gt>> to join paragraphs. [% FILTER html_break %] The cat sat on the mat. Mary had a little lamb. [% END %] Output: The cat sat on the mat. <br> <br> Mary had a little lamb. =head1 html_line_break This filter replaces any newlines with C<E<lt>brE<gt>> HTML tags, thus preserving the line breaks of the original text in the HTML output. [% FILTER html_line_break %] The cat sat on the mat. Mary had a little lamb. [% END %] Output: The cat sat on the mat.<br> Mary had a little lamb.<br> =head1 uri This filter URI escapes the input text, converting any characters outside of the permitted URI character set (as defined by RFC 3986) into a C<%nn> hex escape. [% 'my file.html' | uri %] Output: my%20file.html The uri filter correctly encodes all reserved characters, including C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. This filter is typically used to encode parameters in a URL that could otherwise be interpreted as part of the URL. Here's an example: [% path = 'http://tt2.org/example' back = '/other?foo=bar&baz=bam' title = 'Earth: "Mostly Harmless"' %] <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]"> The output generated is rather long so we'll show it split across two lines: <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26 baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22"> Without the uri filter the output would look like this (also split across two lines). <a href="http://tt2.org/example?back=/other?foo=bar &baz=bam&title=Earth: "Mostly Harmless""> In this rather contrived example we've manage to generate both a broken URL (the repeated C<?> is not allowed) and a broken HTML element (the href attribute is terminated by the first C<"> after C<Earth: > leaving C<Mostly Harmless"> dangling on the end of the tag in precisely the way that harmless things shouldn't dangle). So don't do that. Always use the uri filter to encode your URL parameters. However, you should B<not> use the uri filter to encode an entire URL. <a href="[% page_url | uri %]"> # WRONG! This will incorrectly encode any reserved characters like C<:> and C</> and that's almost certainly not what you want in this case. Instead you should use the B<url> (note spelling) filter for this purpose. <a href="[% page_url | url %]"> # CORRECT Please note that this behaviour was changed in version 2.16 of the Template Toolkit. Prior to that, the uri filter did not encode the reserved characters, making it technically incorrect according to the RFC 2396 specification (since superceded by RFC2732 and RFC3986). So we fixed it in 2.16 and provided the url filter to implement the old behaviour of not encoding reserved characters. As of version 2.28 of the Template Toolkit, the C<uri> and L<url> filters use the unsafe character set defined by RFC3986. This means that certain characters ("(", ")", "*", "!", "'", and '"') are now deemed unsafe and will be escaped as hex character sequences. The ability to use the RFC3986 character set was added in 2.26 but not enabled by default; double quote was incorrectly deemed safe in 2.26 but correctly escaped in 2.27. If you want to enable the old behaviour then call the C<use_rfc2732()> method in L<Template::Filters> use Template::Filters Template::Filters->use_rfc2732; =head1 url The url filter is a less aggressive version of the uri filter. It encodes any characters outside of the permitted URI character set (as defined by RFC 2396) into C<%nn> hex escapes. However, unlike the uri filter, the url filter does B<not> encode the reserved characters C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. =head1 indent(pad) Indents the text block by a fixed pad string or width. The 'C<pad>' argument can be specified as a string, or as a numerical value to indicate a pad width (spaces). Defaults to 4 spaces if unspecified. [% FILTER indent('ME> ') %] blah blah blah cabbages, rhubard, onions [% END %] Output: ME> blah blah blah ME> cabbages, rhubard, onions =head1 truncate(length,dots) Truncates the text block to the length specified, or a default length of 32. Truncated text will be terminated with 'C<...>' (i.e. the 'C<...>' falls inside the required length, rather than appending to it). [% FILTER truncate(21) %] I have much to say on this matter that has previously been said on more than one occasion. [% END %] Output: I have much to say... If you want to use something other than 'C<...>' you can pass that as a second argument. [% FILTER truncate(26, '…') %] I have much to say on this matter that has previously been said on more than one occasion. [% END %] Output: I have much to say… =head1 repeat(iterations) Repeats the text block for as many iterations as are specified (default: 1). [% FILTER repeat(3) %] We want more beer and we want more beer, [% END %] We are the more beer wanters! Output: We want more beer and we want more beer, We want more beer and we want more beer, We want more beer and we want more beer, We are the more beer wanters! =head1 remove(string) Searches the input text for any occurrences of the specified string and removes them. A Perl regular expression may be specified as the search string. [% "The cat sat on the mat" FILTER remove('\s+') %] Output: Thecatsatonthemat =head1 replace(search, replace) Similar to the remove filter described above, but taking a second parameter which is used as a replacement string for instances of the search string. [% "The cat sat on the mat" | replace('\s+', '_') %] Output: The_cat_sat_on_the_mat =head1 redirect(file, options) The C<redirect> filter redirects the output of the block into a separate file, specified relative to the C<OUTPUT_PATH> configuration item. [% FOREACH user IN myorg.userlist %] [% FILTER redirect("users/${user.id}.html") %] [% INCLUDE userinfo %] [% END %] [% END %] or more succinctly, using side-effect notation: [% FOREACH user IN myorg.userlist; INCLUDE userinfo FILTER redirect("users/${user.id}.html"); END %] A C<file> exception will be thrown if the C<OUTPUT_PATH> option is undefined. An optional C<binmode> argument can follow the filename to explicitly set the output file to binary mode. [% PROCESS my/png/generator FILTER redirect("images/logo.png", binmode=1) %] For backwards compatibility with earlier versions, a single true/false value can be used to set binary mode. [% PROCESS my/png/generator FILTER redirect("images/logo.png", 1) %] For the sake of future compatibility and clarity, if nothing else, we would strongly recommend you explicitly use the named C<binmode> option as shown in the first example. =head1 eval / evaltt The C<eval> filter evaluates the block as template text, processing any directives embedded within it. This allows template variables to contain template fragments, or for some method to be provided for returning template fragments from an external source such as a database, which can then be processed in the template as required. my $vars = { fragment => "The cat sat on the [% place %]", }; $template->process($file, $vars); The following example: [% fragment | eval %] is therefore equivalent to The cat sat on the [% place %] The C<evaltt> filter is provided as an alias for C<eval>. =head1 perl / evalperl The C<perl> filter evaluates the block as Perl code. The C<EVAL_PERL> option must be set to a true value or a C<perl> exception will be thrown. [% my_perl_code | perl %] In most cases, the C<[% PERL %]> ... C<[% END %]> block should suffice for evaluating Perl code, given that template directives are processed before being evaluate as Perl. Thus, the previous example could have been written in the more verbose form: [% PERL %] [% my_perl_code %] [% END %] as well as [% FILTER perl %] [% my_perl_code %] [% END %] The C<evalperl> filter is provided as an alias for C<perl> for backwards compatibility. =head1 stdout(options) The stdout filter prints the output generated by the enclosing block to C<STDOUT>. The C<binmode> option can be passed as either a named parameter or a single argument to set C<STDOUT> to binary mode (see the binmode perl function). [% PROCESS something/cool FILTER stdout(binmode=1) # recommended %] [% PROCESS something/cool FILTER stdout(1) # alternate %] The C<stdout> filter can be used to force C<binmode> on C<STDOUT>, or also inside C<redirect>, C<null> or C<stderr> blocks to make sure that particular output goes to C<STDOUT>. See the C<null> filter below for an example. =head1 stderr The stderr filter prints the output generated by the enclosing block to C<STDERR>. =head1 null The C<null> filter prints nothing. This is useful for plugins whose methods return values that you don't want to appear in the output. Rather than assigning every plugin method call to a dummy variable to silence it, you can wrap the block in a null filter: [% FILTER null; USE im = GD.Image(100,100); black = im.colorAllocate(0, 0, 0); red = im.colorAllocate(255,0, 0); blue = im.colorAllocate(0, 0, 255); im.arc(50,50,95,75,0,360,blue); im.fill(50,50,red); im.png | stdout(1); END; -%] Notice the use of the C<stdout> filter to ensure that a particular expression generates output to C<STDOUT> (in this case in binary mode). =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��v� � lib/Template/Manual/Config.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Config # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Config - Configuration options =head1 Template Style and Parsing Options =head2 ENCODING The C<ENCODING> option specifies the template files' character encoding: my $template = Template->new({ ENCODING => 'utf8', }); A template which starts with a Unicode byte order mark (BOM) will have its encoding detected automatically. =head2 START_TAG, END_TAG The C<START_TAG> and C<END_TAG> options are used to specify character sequences or regular expressions that mark the start and end of inline template directives. The default values for C<START_TAG> and C<END_TAG> are 'C<[%>' and 'C<%]>' respectively, giving us the familiar directive style: [% example %] Any Perl regex characters can be used and therefore should be escaped (or use the Perl C<quotemeta> function) if they are intended to represent literal characters. my $template = Template->new({ START_TAG => quotemeta('<+'), END_TAG => quotemeta('+>'), }); Example: <+ INCLUDE foobar +> The C<TAGS> directive can also be used to set the C<START_TAG> and C<END_TAG> values on a per-template file basis. [% TAGS <+ +> %] =head2 OUTLINE_TAG The C<OUTLINE_TAG> option can be used to enable single-line "outline" directives. my $template = Template->new({ OUTLINE_TAG => '%%', }); This allows you to use both inline and outline tags like so: %% IF user Hello [% user.name %] %% END The C<OUTLINE_TAG> string (or regex) must appear at the start of a line. The directive continues until the end of the line. The newline character at the end of the line is considered to be the invisible end-of-directive marker and is removed. =head2 TAG_STYLE The C<TAG_STYLE> option can be used to set both C<START_TAG> and C<END_TAG> according to pre-defined tag styles. my $template = Template->new({ TAG_STYLE => 'star', }); Available styles are: template [% ... %] (default) template1 [% ... %] or %% ... %% (TT version 1) metatext %% ... %% (Text::MetaText) star [* ... *] (TT alternate) php <? ... ?> (PHP) asp <% ... %> (ASP) mason <% ... > (HTML::Mason) html <!-- ... --> (HTML comments) The C<outline> style uses the default markers for C<START_TAG> and C<END_TAG> (C<[%> and C<%]> respectively) and additionally defines C<OUTLINE_TAG> to be C<%%>. my $template = Template->new({ TAG_STYLE => 'outline', }); This allows you to use both inline and outline tags like so: %% IF user Hello [% user.name %] %% END Any values specified for C<START_TAG>, C<END_TAG> and/or C<OUTLINE_TAG> will override those defined by a C<TAG_STYLE>. The C<TAGS> directive may also be used to set a C<TAG_STYLE> [% TAGS html %] <!-- INCLUDE header --> =head2 PRE_CHOMP, POST_CHOMP Anything outside a directive tag is considered plain text and is generally passed through unaltered (but see the L<INTERPOLATE> option). This includes all whitespace and newlines characters surrounding directive tags. Directives that don't generate any output will leave gaps in the output document. Example: Foo [% a = 10 %] Bar Output: Foo Bar The C<PRE_CHOMP> and C<POST_CHOMP> options can help to clean up some of this extraneous whitespace. Both are disabled by default. my $template = Template->new({ PRE_CHOMP => 1, POST_CHOMP => 1, }); With C<PRE_CHOMP> set to C<1>, the newline and whitespace preceding a directive at the start of a line will be deleted. This has the effect of concatenating a line that starts with a directive onto the end of the previous line. Foo <----------. | ,---(PRE_CHOMP)----' | `-- [% a = 10 %] --. | ,---(POST_CHOMP)---' | `-> Bar With C<POST_CHOMP> set to C<1>, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line. If C<PRE_CHOMP> or C<POST_CHOMP> is set to C<2>, all whitespace including any number of newline will be removed and replaced with a single space. This is useful for HTML, where (usually) a contiguous block of whitespace is rendered the same as a single space. With C<PRE_CHOMP> or C<POST_CHOMP> set to C<3>, all adjacent whitespace (including newlines) will be removed entirely. These values are defined as C<CHOMP_NONE>, C<CHOMP_ONE>, C<CHOMP_COLLAPSE> and C<CHOMP_GREEDY> constants in the L<Template::Constants> module. C<CHOMP_ALL> is also defined as an alias for C<CHOMP_ONE> to provide backwards compatibility with earlier version of the Template Toolkit. Additionally the chomp tag modifiers listed below may also be used for the C<PRE_CHOMP> and C<POST_CHOMP> configuration. my $template = Template->new({ PRE_CHOMP => '~', POST_CHOMP => '-', }); C<PRE_CHOMP> and C<POST_CHOMP> can be activated for individual directives by placing a 'C<->' immediately at the start and/or end of the directive. [% FOREACH user IN userlist %] [%- user -%] [% END %] This has the same effect as C<CHOMP_ONE> in removing all whitespace before or after the directive up to and including the newline. The template will be processed as if written: [% FOREACH user IN userlist %][% user %][% END %] To remove all whitespace including any number of newlines, use the ('C<~>') tilde character instead. [% FOREACH user IN userlist %] [%~ user ~%] [% END %] To collapse all whitespace to a single space, use the 'C<=>' equals sign character. [% FOREACH user IN userlist %] [%= user =%] [% END %] Here the template is processed as if written: [% FOREACH user IN userlist %] [% user %] [% END %] If you have C<PRE_CHOMP> or C<POST_CHOMP> set as configuration options then you can use the 'C<+>' plus sign to disable any chomping options (i.e. leave the whitespace intact) on a per-directive basis. [% FOREACH user IN userlist %] User: [% user +%] [% END %] With C<POST_CHOMP> set to C<CHOMP_ONE>, the above example would be parsed as if written: [% FOREACH user IN userlist %]User: [% user %] [% END %] For reference, the C<PRE_CHOMP> and C<POST_CHOMP> configuration options may be set to any of the following: Constant Value Tag Modifier ---------------------------------- CHOMP_NONE 0 + CHOMP_ONE 1 - CHOMP_COLLAPSE 2 = CHOMP_GREEDY 3 ~ =head2 TRIM The C<TRIM> option can be set to have any leading and trailing whitespace automatically removed from the output of all template files and C<BLOCK>s. By example, the following C<BLOCK> definition [% BLOCK foo %] Line 1 of foo [% END %] will be processed is as "C<\nLine 1 of foo\n>". When C<INCLUDE>d, the surrounding newlines will also be introduced. before [% INCLUDE foo %] after Generated output: before Line 1 of foo after With the C<TRIM> option set to any true value, the leading and trailing newlines (which count as whitespace) will be removed from the output of the C<BLOCK>. before Line 1 of foo after The C<TRIM> option is disabled (C<0>) by default. =head2 INTERPOLATE The C<INTERPOLATE> flag, when set to any true value will cause variable references in plain text (i.e. not surrounded by C<START_TAG> and C<END_TAG>) to be recognised and interpolated accordingly. my $template = Template->new({ INTERPOLATE => 1, }); Variables should be prefixed by a 'C<$>' dollar sign to identify them. Curly braces 'C<{>' and 'C<}>' can be used in the familiar Perl/shell style to explicitly scope the variable name where required. # INTERPOLATE => 0 <a href="http://[% server %]/[% help %]"> <img src="[% images %]/help.gif"></a> [% myorg.name %] # INTERPOLATE => 1 <a href="http://$server/$help"> <img src="$images/help.gif"></a> $myorg.name # explicit scoping with { } <img src="$images/${icon.next}.gif"> Note that a limitation in Perl's regex engine restricts the maximum length of an interpolated template to around 32 kilobytes or possibly less. Files that exceed this limit in size will typically cause Perl to dump core with a segmentation fault. If you routinely process templates of this size then you should disable C<INTERPOLATE> or split the templates in several smaller files or blocks which can then be joined backed together via C<PROCESS> or C<INCLUDE>. =head2 ANYCASE By default, directive keywords should be expressed in UPPER CASE. The C<ANYCASE> option can be set to allow directive keywords to be specified in any case. # ANYCASE => 0 (default) [% INCLUDE foobar %] # OK [% include foobar %] # ERROR [% include = 10 %] # OK, 'include' is a variable # ANYCASE => 1 [% INCLUDE foobar %] # OK [% include foobar %] # OK [% include = 10 %] # ERROR, 'include' is reserved word One side-effect of enabling C<ANYCASE> is that you cannot use a variable of the same name as a reserved word, regardless of case. The reserved words are currently: GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP CLEAR TO STEP AND OR NOT MOD DIV END The only lower case reserved words that cannot be used for variables, regardless of the C<ANYCASE> option, are the operators: and or not mod div =head1 Template Files and Blocks =head2 INCLUDE_PATH The C<INCLUDE_PATH> is used to specify one or more directories in which template files are located. When a template is requested that isn't defined locally as a C<BLOCK>, each of the C<INCLUDE_PATH> directories is searched in turn to locate the template file. Multiple directories can be specified as a reference to a list or as a single string where each directory is delimited by the 'C<:>' colon character. my $template = Template->new({ INCLUDE_PATH => '/usr/local/templates', }); my $template = Template->new({ INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates', }); my $template = Template->new({ INCLUDE_PATH => [ '/usr/local/templates', '/tmp/my/templates' ], }); On Win32 systems, a little extra magic is invoked, ignoring delimiters that have 'C<:>' colon followed by a 'C</>' slash or 'C<\>' blackslash. This avoids confusion when using directory names like 'C<C:\Blah Blah>'. When specified as a list, the C<INCLUDE_PATH> path can contain elements which dynamically generate a list of C<INCLUDE_PATH> directories. These generator elements can be specified as a reference to a subroutine or an object which implements a C<paths()> method. my $template = Template->new({ INCLUDE_PATH => [ '/usr/local/templates', \&incpath_generator, My::IncPath::Generator->new( ... ) ], }); Each time a template is requested and the C<INCLUDE_PATH> examined, the subroutine or object method will be called. A reference to a list of directories should be returned. Generator subroutines should report errors using C<die()>. Generator objects should return undef and make an error available via its C<error()> method. For example: sub incpath_generator { # ...some code... if ($all_is_well) { return \@list_of_directories; } else { die "cannot generate INCLUDE_PATH...\n"; } } or: package My::IncPath::Generator; # Template::Base (or Class::Base) provides error() method use Template::Base; use base qw( Template::Base ); sub paths { my $self = shift; # ...some code... if ($all_is_well) { return \@list_of_directories; } else { return $self->error("cannot generate INCLUDE_PATH...\n"); } } 1; =head2 DELIMITER Used to provide an alternative delimiter character sequence for separating paths specified in the C<INCLUDE_PATH>. The default value for C<DELIMITER> is the 'C<:>' colon character. my $template = Template->new({ DELIMITER => '; ', INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN', }); On Win32 systems, the default delimiter is a little more intelligent, splitting paths only on 'C<:>' colon characters that aren't followed by a 'C</>' slash character. This means that the following should work as planned, splitting the C<INCLUDE_PATH> into 2 separate directories, C<C:/foo> and C<C:/bar>. # on Win32 only my $template = Template->new({ INCLUDE_PATH => 'C:/Foo:C:/Bar' }); However, if you're using Win32 then it's recommended that you explicitly set the C<DELIMITER> character to something else (e.g. 'C<;>' semicolon) rather than rely on this subtle magic. =head2 ABSOLUTE The C<ABSOLUTE> flag is used to indicate if templates specified with absolute filenames (e.g. 'C</foo/bar>') should be processed. It is disabled by default and any attempt to load a template by such a name will cause a 'C<file>' exception to be raised. my $template = Template->new({ ABSOLUTE => 1, }); # this is why it's disabled by default [% INSERT /etc/passwd %] On Win32 systems, the regular expression for matching absolute pathnames is tweaked slightly to also detect filenames that start with a driver letter and colon, such as: C:/Foo/Bar =head2 RELATIVE The C<RELATIVE> flag is used to indicate if templates specified with filenames relative to the current directory (e.g. 'C<./foo/bar>' or 'C<../../some/where/else>') should be loaded. It is also disabled by default, and will raise a 'C<file>' error if such template names are encountered. my $template = Template->new({ RELATIVE => 1, }); [% INCLUDE ../logs/error.log %] =head2 DEFAULT The C<DEFAULT> option can be used to specify a default template which should be used whenever a specified template can't be found in the C<INCLUDE_PATH>. my $template = Template->new({ DEFAULT => 'notfound.html', }); If a non-existent template is requested through the Template L<process()|Template#process()> method, or by an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive, then the C<DEFAULT> template will instead be processed, if defined. Note that the C<DEFAULT> template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string. =head2 BLOCKS The C<BLOCKS> option can be used to pre-define a default set of template blocks. These should be specified as a reference to a hash array mapping template names to template text, subroutines or L<Template::Document> objects. my $template = Template->new({ BLOCKS => { header => 'The Header. [% title %]', footer => sub { return $some_output_text }, another => Template::Document->new({ ... }), }, }); =head2 VIEWS The VIEWS option can be used to define one or more L<Template::View> objects. They can be specified as a reference to a hash array or list reference. my $template = Template->new({ VIEWS => { my_view => { prefix => 'my_templates/' }, }, }); Be aware of the fact that Perl's hash array are unordered, so if you want to specify multiple views of which one or more are based on other views, then you should use a list reference to preserve the order of definition. my $template = Template->new({ VIEWS => [ bottom => { prefix => 'bottom/' }, middle => { prefix => 'middle/', base => 'bottom' }, top => { prefix => 'top/', base => 'middle' }, ], }); =head2 AUTO_RESET The C<AUTO_RESET> option is set by default and causes the local C<BLOCKS> cache for the L<Template::Context> object to be reset on each call to the Template L<process()|Template#process()> method. This ensures that any C<BLOCK>s defined within a template will only persist until that template is finished processing. This prevents C<BLOCK>s defined in one processing request from interfering with other independent requests subsequently processed by the same context object. The C<BLOCKS> item may be used to specify a default set of block definitions for the L<Template::Context> object. Subsequent C<BLOCK> definitions in templates will over-ride these but they will be reinstated on each reset if C<AUTO_RESET> is enabled (default), or if the L<Template::Context> L<reset()|Template::Context#reset()> method is called. =head2 RECURSION The template processor will raise a file exception if it detects direct or indirect recursion into a template. Setting this option to any true value will allow templates to include each other recursively. =head1 Template Variables =head2 VARIABLES The C<VARIABLES> option (or C<PRE_DEFINE> - they're equivalent) can be used to specify a hash array of template variables that should be used to pre-initialise the stash when it is created. These items are ignored if the C<STASH> item is defined. my $template = Template->new({ VARIABLES => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; or my $template = Template->new({ PRE_DEFINE => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; =head2 CONSTANTS The C<CONSTANTS> option can be used to specify a hash array of template variables that are compile-time constants. These variables are resolved once when the template is compiled, and thus don't require further resolution at runtime. This results in significantly faster processing of the compiled templates and can be used for variables that don't change from one request to the next. my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; =head2 CONSTANT_NAMESPACE Constant variables are accessed via the C<constants> namespace by default. [% constants.title %] The C<CONSTANTS_NAMESPACE> option can be set to specify an alternate namespace. my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', # ...etc... }, CONSTANTS_NAMESPACE => 'const', }; In this case the constants would then be accessed as: [% const.title %] =head2 NAMESPACE The constant folding mechanism described above is an example of a namespace handler. Namespace handlers can be defined to provide alternate parsing mechanisms for variables in different namespaces. Under the hood, the L<Template> module converts a constructor configuration such as: my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', # ...etc... }, CONSTANTS_NAMESPACE => 'const', }; into one like: my $template = Template->new({ NAMESPACE => { const => Template:::Namespace::Constants->new({ title => 'A Demo Page', # ...etc... }), }, }; You can use this mechanism to define multiple constant namespaces, or to install custom handlers of your own. my $template = Template->new({ NAMESPACE => { site => Template:::Namespace::Constants->new({ title => "Wardley's Widgets", version => 2.718, }), author => Template:::Namespace::Constants->new({ name => 'Andy Wardley', email => 'abw@andywardley.com', }), voodoo => My::Namespace::Handler->new( ... ), }, }; Now you have two constant namespaces, for example: [% site.title %] [% author.name %] as well as your own custom namespace handler installed for the 'voodoo' namespace. [% voodoo.magic %] See L<Template::Namespace::Constants> for an example of what a namespace handler looks like on the inside. =head1 Template Processing Options The following options are used to specify any additional templates that should be processed before, after, around or instead of the template passed as the first argument to the L<Template> L<process()|Template#process()> method. These options can be perform various useful tasks such as adding standard headers or footers to all pages, wrapping page output in other templates, pre-defining variables or performing initialisation or cleanup tasks, automatically generating page summary information, navigation elements, and so on. The task of processing the template is delegated internally to the L<Template::Service> module which, unsurprisingly, also has a L<process()|Template::Service#process()> method. Any templates defined by the C<PRE_PROCESS> option are processed first and any output generated is added to the output buffer. Then the main template is processed, or if one or more C<PROCESS> templates are defined then they are instead processed in turn. In this case, one of the C<PROCESS> templates is responsible for processing the main template, by a directive such as: [% PROCESS $template %] The output of processing the main template or the C<PROCESS> template(s) is then wrapped in any C<WRAPPER> templates, if defined. C<WRAPPER> templates don't need to worry about explicitly processing the template because it will have been done for them already. Instead C<WRAPPER> templates access the content they are wrapping via the C<content> variable. wrapper before [% content %] wrapper after This output generated from processing the main template, and/or any C<PROCESS> or C<WRAPPER> templates is added to the output buffer. Finally, any C<POST_PROCESS> templates are processed and their output is also added to the output buffer which is then returned. If the main template throws an exception during processing then any relevant template(s) defined via the C<ERROR> option will be processed instead. If defined and successfully processed, the output from the error template will be added to the output buffer in place of the template that generated the error and processing will continue, applying any C<WRAPPER> and C<POST_PROCESS> templates. If no relevant C<ERROR> option is defined, or if the error occurs in one of the C<PRE_PROCESS>, C<WRAPPER> or C<POST_PROCESS> templates, then the process will terminate immediately and the error will be returned. =head2 PRE_PROCESS, POST_PROCESS These values may be set to contain the name(s) of template files (relative to C<INCLUDE_PATH>) which should be processed immediately before and/or after each template. These do not get added to templates processed into a document via directives such as C<INCLUDE>, C<PROCESS>, C<WRAPPER> etc. my $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }; Multiple templates may be specified as a reference to a list. Each is processed in the order defined. my $template = Template->new({ PRE_PROCESS => [ 'config', 'header' ], POST_PROCESS => 'footer', }; Alternately, multiple template may be specified as a single string, delimited by 'C<:>'. This delimiter string can be changed via the C<DELIMITER> option. my $template = Template->new({ PRE_PROCESS => 'config:header', POST_PROCESS => 'footer', }; The C<PRE_PROCESS> and C<POST_PROCESS> templates are evaluated in the same variable context as the main document and may define or update variables for subsequent use. config: [% # set some site-wide variables bgcolor = '#ffffff' version = 2.718 %] header: [% DEFAULT title = 'My Funky Web Site' %] <html> <head> <title>[% title %]</title> </head> <body bgcolor="[% bgcolor %]"> footer: <hr> Version [% version %] </body> </html> The L<Template::Document> object representing the main template being processed is available within C<PRE_PROCESS> and C<POST_PROCESS> templates as the C<template> variable. Metadata items defined via the C<META> directive may be accessed accordingly. $template->process('mydoc.html', $vars); mydoc.html: [% META title = 'My Document Title' %] blah blah blah ... header: <html> <head> <title>[% template.title %]</title> </head> <body bgcolor="[% bgcolor %]"> =head2 PROCESS The C<PROCESS> option may be set to contain the name(s) of template files (relative to C<INCLUDE_PATH>) which should be processed instead of the main template passed to the L<Template> L<process()|Template#process()> method. This can be used to apply consistent wrappers around all templates, similar to the use of C<PRE_PROCESS> and C<POST_PROCESS> templates. my $template = Template->new({ PROCESS => 'content', }; # processes 'content' instead of 'foo.html' $template->process('foo.html'); A reference to the original template is available in the C<template> variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by C<$>) to an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive. content: <html> <head> <title>[% template.title %]</title> </head> <body> <!-- begin content --> [% PROCESS $template %] <!-- end content --> <hr> © Copyright [% template.copyright %] </body> </html> foo.html: [% META title = 'The Foo Page' author = 'Fred Foo' copyright = '2000 Fred Foo' %] <h1>[% template.title %]</h1> Welcome to the Foo Page, blah blah blah output: <html> <head> <title>The Foo Page</title> </head> <body> <!-- begin content --> <h1>The Foo Page</h1> Welcome to the Foo Page, blah blah blah <!-- end content --> <hr> © Copyright 2000 Fred Foo </body> </html> =head2 WRAPPER The C<WRAPPER> option can be used to specify one or more templates which should be used to wrap around the output of the main page template. The main template is processed first (or any C<PROCESS> template(s)) and the output generated is then passed as the C<content> variable to the C<WRAPPER> template(s) as they are processed. my $template = Template->new({ WRAPPER => 'wrapper', }; # process 'foo' then wrap in 'wrapper' $template->process('foo', { message => 'Hello World!' }); wrapper: <wrapper> [% content %] </wrapper> foo: This is the foo file! Message: [% message %] The output generated from this example is: <wrapper> This is the foo file! Message: Hello World! </wrapper> You can specify more than one C<WRAPPER> template by setting the value to be a reference to a list of templates. The C<WRAPPER> templates will be processed in reverse order with the output of each being passed to the next (or previous, depending on how you look at it) as the 'content' variable. It sounds complicated, but the end result is that it just "Does The Right Thing" to make wrapper templates nest in the order you specify. my $template = Template->new({ WRAPPER => [ 'outer', 'inner' ], }; # process 'foo' then wrap in 'inner', then in 'outer' $template->process('foo', { message => 'Hello World!' }); outer: <outer> [% content %] </outer> inner: <inner> [% content %] </inner> The output generated is then: <outer> <inner> This is the foo file! Message: Hello World! </inner> </outer> One side-effect of the "inside-out" processing of the C<WRAPPER> configuration item (and also the C<WRAPPER> directive) is that any variables set in the template being wrapped will be visible to the template doing the wrapping, but not the other way around. You can use this to good effect in allowing page templates to set pre-defined values which are then used in the wrapper templates. For example, our main page template 'foo' might look like this: foo: [% page = { title = 'Foo Page' subtitle = 'Everything There is to Know About Foo' author = 'Frank Oliver Octagon' } %] <p> Welcome to the page that tells you everything about foo blah blah blah... </p> The C<foo> template is processed before the wrapper template meaning that the C<page> data structure will be defined for use in the wrapper template. wrapper: <html> <head> <title>[% page.title %]</title> </head> <body> <h1>[% page.title %]</h1> <h2>[% page.subtitle %]</h1> <h3>by [% page.author %]</h3> [% content %] </body> </html> It achieves the same effect as defining C<META> items which are then accessed via the C<template> variable (which you are still free to use within C<WRAPPER> templates), but gives you more flexibility in the type and complexity of data that you can define. =head2 ERROR The C<ERROR> (or C<ERRORS> if you prefer) configuration item can be used to name a single template or specify a hash array mapping exception types to templates which should be used for error handling. If an uncaught exception is raised from within a template then the appropriate error template will instead be processed. If specified as a single value then that template will be processed for all uncaught exceptions. my $template = Template->new({ ERROR => 'error.html' }); If the C<ERROR> item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A C<default> template may be provided for the general case. Note that C<ERROR> can be pluralised to C<ERRORS> if you find it more appropriate in this case. my $template = Template->new({ ERRORS => { user => 'user/index.html', dbi => 'error/database', default => 'error/default', }, }); In this example, any C<user> exceptions thrown will cause the F<user/index.html> template to be processed, C<dbi> errors are handled by F<error/database> and all others by the F<error/default> template. Any C<PRE_PROCESS> and/or C<POST_PROCESS> templates will also be applied to these error templates. Note that exception types are hierarchical and a C<foo> handler will catch all C<foo.*> errors (e.g. C<foo.bar>, C<foo.bar.baz>) if a more specific handler isn't defined. Be sure to quote any exception types that contain periods to prevent Perl concatenating them into a single string (i.e. C<user.passwd> is parsed as C<'user'.'passwd'>). my $template = Template->new({ ERROR => { 'user.login' => 'user/login.html', 'user.passwd' => 'user/badpasswd.html', 'user' => 'user/index.html', 'default' => 'error/default', }, }); In this example, any template processed by the C<$template> object, or other templates or code called from within, can raise a C<user.login> exception and have the service redirect to the F<user/login.html> template. Similarly, a C<user.passwd> exception has a specific handling template, F<user/badpasswd.html>, while all other C<user> or C<user.*> exceptions cause a redirection to the F<user/index.html> page. All other exception types are handled by F<error/default>. Exceptions can be raised in a template using the C<THROW> directive, [% THROW user.login 'no user id: please login' %] or by calling the L<throw()|Template::Context#throw()> method on the current L<Template::Context> object, $context->throw('user.passwd', 'Incorrect Password'); $context->throw('Incorrect Password'); # type 'undef' or from Perl code by calling C<die()> with a L<Template::Exception> object, die (Template::Exception->new('user.denied', 'Invalid User ID')); or by simply calling L<die()> with an error string. This is automagically caught and converted to an exception of 'C<undef>' type which can then be handled in the usual way. die "I'm sorry Dave, I can't do that"; Note that the 'C<undef>' we're talking about here is a literal string rather than Perl's C<undef> used to represent undefined values. =head1 Template Runtime Options =head2 EVAL_PERL This flag is used to indicate if C<PERL> and/or C<RAWPERL> blocks should be evaluated. It is disabled by default and any C<PERL> or C<RAWPERL> blocks encountered will raise exceptions of type 'C<perl>' with the message 'C<EVAL_PERL not set>'. Note however that any C<RAWPERL> blocks should always contain valid Perl code, regardless of the C<EVAL_PERL> flag. The parser will fail to compile templates that contain invalid Perl code in C<RAWPERL> blocks and will throw a 'C<file>' exception. When using compiled templates (see L<Caching and Compiling Options>), the C<EVAL_PERL> has an affect when the template is compiled, and again when the templates is subsequently processed, possibly in a different context to the one that compiled it. If the C<EVAL_PERL> is set when a template is compiled, then all C<PERL> and C<RAWPERL> blocks will be included in the compiled template. If the C<EVAL_PERL> option isn't set, then Perl code will be generated which B<always> throws a 'C<perl>' exception with the message 'C<EVAL_PERL not set>' B<whenever> the compiled template code is run. Thus, you must have C<EVAL_PERL> set if you want your compiled templates to include C<PERL> and C<RAWPERL> blocks. At some point in the future, using a different invocation of the Template Toolkit, you may come to process such a pre-compiled template. Assuming the C<EVAL_PERL> option was set at the time the template was compiled, then the output of any C<RAWPERL> blocks will be included in the compiled template and will get executed when the template is processed. This will happen regardless of the runtime C<EVAL_PERL> status. Regular C<PERL> blocks are a little more cautious, however. If the C<EVAL_PERL> flag isn't set for the I<current> context, that is, the one which is trying to process it, then it will throw the familiar 'C<perl>' exception with the message, 'C<EVAL_PERL not set>'. Thus you can compile templates to include C<PERL> blocks, but optionally disable them when you process them later. Note however that it is possible for a C<PERL> block to contain a Perl "C<BEGIN { # some code }>" block which will always get run regardless of the runtime C<EVAL_PERL> status. Thus, if you set C<EVAL_PERL> when compiling templates, it is assumed that you trust the templates to Do The Right Thing. Otherwise you must accept the fact that there's no bulletproof way to prevent any included code from trampling around in the living room of the runtime environment, making a real nuisance of itself if it really wants to. If you don't like the idea of such uninvited guests causing a bother, then you can accept the default and keep C<EVAL_PERL> disabled. =head2 OUTPUT Default output location or handler. This may be specified as one of: a file name (relative to C<OUTPUT_PATH>, if defined, or the current working directory if not specified absolutely); a file handle (e.g. C<GLOB> or L<IO::Handle>) opened for writing; a reference to a text string to which the output is appended (the string isn't cleared); a reference to a subroutine which is called, passing the output text as an argument; as a reference to an array, onto which the content will be C<push()>ed; or as a reference to any object that supports the C<print()> method. This latter option includes the C<Apache::Request> object which is passed as the argument to Apache/mod_perl handlers. example 1 (file name): my $template = Template->new({ OUTPUT => "/tmp/foo", }); example 2 (text string): my $output = ''; my $template = Template->new({ OUTPUT => \$output, }); example 3 (file handle): open (TOUT, ">", $file) || die "$file: $!\n"; my $template = Template->new({ OUTPUT => \*TOUT, }); example 4 (subroutine): sub output { my $out = shift; print "OUTPUT: $out" } my $template = Template->new({ OUTPUT => \&output, }); example 5 (array reference): my $template = Template->new({ OUTPUT => \@output, }) example 6 (Apache/mod_perl handler): sub handler { my $r = shift; my $t = Template->new({ OUTPUT => $r, }); ... } The default C<OUTPUT> location be overridden by passing a third parameter to the L<Template> L<process()|Template#process()> method. This can be specified as any of the above argument types. $t->process($file, $vars, "/tmp/foo"); $t->process($file, $vars, \$output); $t->process($file, $vars, \*MYGLOB); $t->process($file, $vars, \@output); $t->process($file, $vars, $r); # Apache::Request ... =head2 OUTPUT_PATH The C<OUTPUT_PATH> allows a directory to be specified into which output files should be written. An output file can be specified by the C<OUTPUT> option, or passed by name as the third parameter to the L<Template> L<process()|Template#process()> method. my $template = Template->new({ INCLUDE_PATH => "/tmp/src", OUTPUT_PATH => "/tmp/dest", }); my $vars = { ... }; foreach my $file ('foo.html', 'bar.html') { $template->process($file, $vars, $file) || die $template->error(); } This example will read the input files F</tmp/src/foo.html> and F</tmp/src/bar.html> and write the processed output to F</tmp/dest/foo.html> and F</tmp/dest/bar.html>, respectively. =head2 STRICT By default the Template Toolkit will silently ignore the use of undefined variables (a bad design decision that I regret). When the C<STRICT> option is set, the use of any undefined variables or values will cause an exception to be throw. The exception will have a C<type> of C<var.undef> and a message of the form "undefined variable: xxx". my $template = Template->new( STRICT => 1 ); =head2 DEBUG The C<DEBUG> option can be used to enable debugging within the various different modules that comprise the Template Toolkit. The L<Template::Constants> module defines a set of C<DEBUG_XXXX> constants which can be combined using the logical OR operator, 'C<|>'. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_PARSER | DEBUG_PROVIDER, }); For convenience, you can also provide a string containing a list of lower case debug options, separated by any non-word characters. my $template = Template->new({ DEBUG => 'parser, provider', }); The following C<DEBUG_XXXX> flags can be used: =over 4 =item DEBUG_SERVICE Enables general debugging messages for the L<Template::Service> module. =item DEBUG_CONTEXT Enables general debugging messages for the L<Template::Context> module. =item DEBUG_PROVIDER Enables general debugging messages for the L<Template::Provider> module. =item DEBUG_PLUGINS Enables general debugging messages for the L<Template::Plugins> module. =item DEBUG_FILTERS Enables general debugging messages for the L<Template::Filters> module. =item DEBUG_PARSER This flag causes the L<Template::Parser> to generate debugging messages that show the Perl code generated by parsing and compiling each template. =item DEBUG_UNDEF This option causes the Template Toolkit to throw an 'C<undef>' error whenever it encounters an undefined variable value. =item DEBUG_DIRS This option causes the Template Toolkit to generate comments indicating the source file, line and original text of each directive in the template. These comments are embedded in the template output using the format defined in the C<DEBUG_FORMAT> configuration item, or a simple default format if unspecified. For example, the following template fragment: Hello World would generate this output: ## input text line 1 : ## Hello ## input text line 2 : World ## World =item DEBUG_ALL Enables all debugging messages. =item DEBUG_CALLER This option causes all debug messages that aren't newline terminated to have the file name and line number of the caller appended to them. =back =head2 DEBUG_FORMAT The C<DEBUG_FORMAT> option can be used to specify a format string for the debugging messages generated via the C<DEBUG_DIRS> option described above. Any occurrences of C<$file>, C<$line> or C<$text> will be replaced with the current file name, line or directive text, respectively. Notice how the format is single quoted to prevent Perl from interpolating those tokens as variables. my $template = Template->new({ DEBUG => 'dirs', DEBUG_FORMAT => '<!-- $file line $line : [% $text %] -->', }); The following template fragment: [% foo = 'World' %] Hello [% foo %] would then generate this output: <!-- input text line 2 : [% foo = 'World' %] --> Hello <!-- input text line 3 : [% foo %] -->World The DEBUG directive can also be used to set a debug format within a template. [% DEBUG format '<!-- $file line $line : [% $text %] -->' %] =head1 Caching and Compiling Options =head2 CACHE_SIZE The L<Template::Provider> module caches compiled templates to avoid the need to re-parse template files or blocks each time they are used. The C<CACHE_SIZE> option is used to limit the number of compiled templates that the module should cache. By default, the C<CACHE_SIZE> is undefined and all compiled templates are cached. When set to any positive value, the cache will be limited to storing no more than that number of compiled templates. When a new template is loaded and compiled and the cache is full (i.e. the number of entries == C<CACHE_SIZE>), the least recently used compiled template is discarded to make room for the new one. The C<CACHE_SIZE> can be set to C<0> to disable caching altogether. my $template = Template->new({ CACHE_SIZE => 64, # only cache 64 compiled templates }); my $template = Template->new({ CACHE_SIZE => 0, # don't cache any compiled templates }); As well as caching templates as they are found, the L<Template::Provider> also implements negative caching to keep track of templates that are I<not> found. This allows the provider to quickly decline a request for a template that it has previously failed to locate, saving the effort of going to look for it again. This is useful when an C<INCLUDE_PATH> includes multiple providers, ensuring that the request is passed down through the providers as quickly as possible. =head2 STAT_TTL This value can be set to control how long the L<Template::Provider> will keep a template cached in memory before checking to see if the source template has changed. my $provider = Template::Provider->new({ STAT_TTL => 60, # one minute }); The default value is 1 (second). You'll probably want to set this to a higher value if you're running the Template Toolkit inside a persistent web server application (e.g. mod_perl). For example, set it to 60 and the provider will only look for changes to templates once a minute at most. However, during development (or any time you're making frequent changes to templates) you'll probably want to keep it set to a low value so that you don't have to wait for the provider to notice that your templates have changed. =head2 COMPILE_EXT From version 2 onwards, the Template Toolkit has the ability to compile templates to Perl code and save them to disk for subsequent use (i.e. cache persistence). The C<COMPILE_EXT> option may be provided to specify a filename extension for compiled template files. It is undefined by default and no attempt will be made to read or write any compiled template files. my $template = Template->new({ COMPILE_EXT => '.ttc', }); If C<COMPILE_EXT> is defined (and C<COMPILE_DIR> isn't, see below) then compiled template files with the C<COMPILE_EXT> extension will be written to the same directory from which the source template files were loaded. Compiling and subsequent reuse of templates happens automatically whenever the C<COMPILE_EXT> or C<COMPILE_DIR> options are set. The Template Toolkit will automatically reload and reuse compiled files when it finds them on disk. If the corresponding source file has been modified since the compiled version as written, then it will load and re-compile the source and write a new compiled version to disk. This form of cache persistence offers significant benefits in terms of time and resources required to reload templates. Compiled templates can be reloaded by a simple call to Perl's C<require()>, leaving Perl to handle all the parsing and compilation. This is a Good Thing. =head2 COMPILE_DIR The C<COMPILE_DIR> option is used to specify an alternate directory root under which compiled template files should be saved. my $template = Template->new({ COMPILE_DIR => '/tmp/ttc', }); The C<COMPILE_EXT> option may also be specified to have a consistent file extension added to these files. my $template1 = Template->new({ COMPILE_DIR => '/tmp/ttc', COMPILE_EXT => '.ttc1', }); my $template2 = Template->new({ COMPILE_DIR => '/tmp/ttc', COMPILE_EXT => '.ttc2', }); When C<COMPILE_EXT> is undefined, the compiled template files have the same name as the original template files, but reside in a different directory tree. Each directory in the C<INCLUDE_PATH> is replicated in full beneath the C<COMPILE_DIR> directory. This example: my $template = Template->new({ COMPILE_DIR => '/tmp/ttc', INCLUDE_PATH => '/home/abw/templates:/usr/share/templates', }); would create the following directory structure: /tmp/ttc/home/abw/templates/ /tmp/ttc/usr/share/templates/ Files loaded from different C<INCLUDE_PATH> directories will have their compiled forms save in the relevant C<COMPILE_DIR> directory. On Win32 platforms a filename may by prefixed by a drive letter and colon. e.g. C:/My Templates/header The colon will be silently stripped from the filename when it is added to the C<COMPILE_DIR> value(s) to prevent illegal filename being generated. Any colon in C<COMPILE_DIR> elements will be left intact. For example: # Win32 only my $template = Template->new({ DELIMITER => ';', COMPILE_DIR => 'C:/TT2/Cache', INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates', }); This would create the following cache directories: C:/TT2/Cache/C/TT2/Templates C:/TT2/Cache/D/My Templates =head1 Plugins and Filters =head2 PLUGINS The C<PLUGINS> options can be used to provide a reference to a hash array that maps plugin names to Perl module names. A number of standard plugins are defined (e.g. C<table>, C<format>, C<cgi>, etc.) which map to their corresponding C<Template::Plugin::*> counterparts. These can be redefined by values in the C<PLUGINS> hash. my $template = Template->new({ PLUGINS => { cgi => 'MyOrg::Template::Plugin::CGI', foo => 'MyOrg::Template::Plugin::Foo', bar => 'MyOrg::Template::Plugin::Bar', }, }); The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified. [% USE Foo %] # look for 'Foo' then 'foo' If you define all your C<PLUGINS> with lower case names then they will be located regardless of how the user specifies the name in the USE directive. If, on the other hand, you define your C<PLUGINS> with upper or mixed case names then the name specified in the C<USE> directive must match the case exactly. The C<USE> directive is used to create plugin objects and does so by calling the L<plugin()|Template::Context#plugin()> method on the current L<Template::Context> object. If the plugin name is defined in the C<PLUGINS> hash then the corresponding Perl module is loaded via C<require()>. The context then calls the L<load()|Template::Plugin#load()> class method which should return the class name (default and general case) or a prototype object against which the L<new()|Template::Plugin#new()> method can be called to instantiate individual plugin objects. If the plugin name is not defined in the C<PLUGINS> hash then the C<PLUGIN_BASE> and/or C<LOAD_PERL> options come into effect. =head2 PLUGIN_BASE If a plugin is not defined in the C<PLUGINS> hash then the C<PLUGIN_BASE> is used to attempt to construct a correct Perl module name which can be successfully loaded. The C<PLUGIN_BASE> can be specified as a reference to an array of module namespaces, or as a single value which is automatically converted to a list. The default C<PLUGIN_BASE> value (C<Template::Plugin>) is then added to the end of this list. example 1: my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin', }); [% USE Foo %] # => MyOrg::Template::Plugin::Foo or Template::Plugin::Foo example 2: my $template = Template->new({ PLUGIN_BASE => [ 'MyOrg::Template::Plugin', 'YourOrg::Template::Plugin' ], }); template: [% USE Foo %] # => MyOrg::Template::Plugin::Foo or YourOrg::Template::Plugin::Foo or Template::Plugin::Foo If you don't want the default C<Template::Plugin> namespace added to the end of the C<PLUGIN_BASE>, then set the C<$Template::Plugins::PLUGIN_BASE> variable to a false value before calling the L<new()|Template> L<Template#new()> constructor method. This is shown in the example below where the C<Foo> plugin is located as C<My::Plugin::Foo> or C<Your::Plugin::Foo> but not as C<Template::Plugin::Foo>. example 3: use Template::Plugins; $Template::Plugins::PLUGIN_BASE = ''; my $template = Template->new({ PLUGIN_BASE => [ 'My::Plugin', 'Your::Plugin' ], }); template: [% USE Foo %] # => My::Plugin::Foo or Your::Plugin::Foo =head2 LOAD_PERL If a plugin cannot be loaded using the C<PLUGINS> or C<PLUGIN_BASE> approaches then the provider can make a final attempt to load the module without prepending any prefix to the module path. This allows regular Perl modules (i.e. those that don't reside in the L<Template::Plugin> or some other such namespace) to be loaded and used as plugins. By default, the C<LOAD_PERL> option is set to C<0> and no attempt will be made to load any Perl modules that aren't named explicitly in the C<PLUGINS> hash or reside in a package as named by one of the C<PLUGIN_BASE> components. Plugins loaded using the C<PLUGINS> or C<PLUGIN_BASE> receive a reference to the current context object as the first argument to the L<new()|Template::Plugin#new()> constructor. Modules loaded using C<LOAD_PERL> are assumed to not conform to the plugin interface. They must provide a C<new()> class method for instantiating objects but it will not receive a reference to the context as the first argument. Plugin modules should provide a L<load()|Template::Plugin#load()> class method (or inherit the default one from the L<Template::Plugin> base class) which is called the first time the plugin is loaded. Regular Perl modules need not. In all other respects, regular Perl objects and Template Toolkit plugins are identical. If a particular Perl module does not conform to the common, but not unilateral, C<new()> constructor convention then a simple plugin wrapper can be written to interface to it. =head2 FILTERS The C<FILTERS> option can be used to specify custom filters which can then be used with the C<FILTER> directive like any other. These are added to the standard filters which are available by default. Filters specified via this option will mask any standard filters of the same name. The C<FILTERS> option should be specified as a reference to a hash array in which each key represents the name of a filter. The corresponding value should contain a reference to an array containing a subroutine reference and a flag which indicates if the filter is static (C<0>) or dynamic (C<1>). A filter may also be specified as a solitary subroutine reference and is assumed to be static. $template = Template->new({ FILTERS => { 'sfilt1' => \&static_filter, # static 'sfilt2' => [ \&static_filter, 0 ], # same as above 'dfilt1' => [ \&dyanamic_filter_factory, 1 ], }, }); Additional filters can be specified at any time by calling the L<define_filter()|Template::Context#define_filter()> method on the current L<Template::Context> object. The method accepts a filter name, a reference to a filter subroutine and an optional flag to indicate if the filter is dynamic. my $context = $template->context(); $context->define_filter('new_html', \&new_html); $context->define_filter('new_repeat', \&new_repeat, 1); Static filters are those where a single subroutine reference is used for all invocations of a particular filter. Filters that don't accept any configuration parameters (e.g. C<html>) can be implemented statically. The subroutine reference is simply returned when that particular filter is requested. The subroutine is called to filter the output of a template block which is passed as the only argument. The subroutine should return the modified text. sub static_filter { my $text = shift; # do something to modify $text... return $text; } The following template fragment: [% FILTER sfilt1 %] Blah blah blah. [% END %] is approximately equivalent to: &static_filter("\nBlah blah blah.\n"); Filters that can accept parameters (e.g. C<truncate>) should be implemented dynamically. In this case, the subroutine is taken to be a filter 'factory' that is called to create a unique filter subroutine each time one is requested. A reference to the current L<Template::Context> object is passed as the first parameter, followed by any additional parameters specified. The subroutine should return another subroutine reference (usually a closure) which implements the filter. sub dynamic_filter_factory { my ($context, @args) = @_; return sub { my $text = shift; # do something to modify $text... return $text; } } The following template fragment: [% FILTER dfilt1(123, 456) %] Blah blah blah [% END %] is approximately equivalent to: my $filter = &dynamic_filter_factory($context, 123, 456); &$filter("\nBlah blah blah.\n"); See the C<FILTER> directive for further examples. =head1 Customisation and Extension =head2 LOAD_TEMPLATES The C<LOAD_TEMPLATES> option can be used to provide a reference to a list of L<Template::Provider> objects or sub-classes thereof which will take responsibility for loading and compiling templates. my $template = Template->new({ LOAD_TEMPLATES => [ MyOrg::Template::Provider->new({ ... }), Template::Provider->new({ ... }), ], }); When a C<PROCESS>, C<INCLUDE> or C<WRAPPER> directive is encountered, the named template may refer to a locally defined C<BLOCK> or a file relative to the C<INCLUDE_PATH> (or an absolute or relative path if the appropriate C<ABSOLUTE> or C<RELATIVE> options are set). If a C<BLOCK> definition can't be found (see the L<Template::Context> L<template()|Template::Context#template()> method for a discussion of C<BLOCK> locality) then each of the C<LOAD_TEMPLATES> provider objects is queried in turn via the L<fetch()|Template::Provider#fetch()> method to see if it can supply the required template. Each provider can return a compiled template, an error, or decline to service the request in which case the responsibility is passed to the next provider. If none of the providers can service the request then a 'not found' error is returned. The same basic provider mechanism is also used for the C<INSERT> directive but it bypasses any C<BLOCK> definitions and doesn't attempt is to parse or process the contents of the template file. If C<LOAD_TEMPLATES> is undefined, a single default provider will be instantiated using the current configuration parameters. For example, the L<Template::Provider> C<INCLUDE_PATH> option can be specified in the L<Template> configuration and will be correctly passed to the provider's constructor method. my $template = Template->new({ INCLUDE_PATH => '/here:/there', }); =head2 LOAD_PLUGINS The C<LOAD_PLUGINS> options can be used to specify a list of provider objects (i.e. they implement the L<fetch()|Template::Plugins#fetch()> method) which are responsible for loading and instantiating template plugin objects. The L<Template::Context> L<plugin()|Template::Context#plugin()> method queries each provider in turn in a "Chain of Responsibility" as per the L<template()|Template::Context#template()> and L<filter()|Template::Context#filter()> methods. my $template = Template->new({ LOAD_PLUGINS => [ MyOrg::Template::Plugins->new({ ... }), Template::Plugins->new({ ... }), ], }); By default, a single L<Template::Plugins> object is created using the current configuration hash. Configuration items destined for the L<Template::Plugins> constructor may be added to the Template constructor. my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugins', LOAD_PERL => 1, }); =head2 LOAD_FILTERS The C<LOAD_FILTERS> option can be used to specify a list of provider objects (i.e. they implement the L<fetch()|Template::Filters#fetch()> method) which are responsible for returning and/or creating filter subroutines. The L<Template::Context> L<filter()|Template::Context#filter()> method queries each provider in turn in a "Chain of Responsibility" as per the L<template()|Template::Context#template()> and L<plugin()|Template::Context#plugin()> methods. my $template = Template->new({ LOAD_FILTERS => [ MyTemplate::Filters->new(), Template::Filters->new(), ], }); By default, a single L<Template::Filters> object is created for the C<LOAD_FILTERS> list. =head2 TOLERANT The C<TOLERANT> flag is used by the various Template Toolkit provider modules (L<Template::Provider>, L<Template::Plugins>, L<Template::Filters>) to control their behaviour when errors are encountered. By default, any errors are reported as such, with the request for the particular resource (C<template>, C<plugin>, C<filter>) being denied and an exception raised. When the C<TOLERANT> flag is set to any true values, errors will be silently ignored and the provider will instead return C<STATUS_DECLINED>. This allows a subsequent provider to take responsibility for providing the resource, rather than failing the request outright. If all providers decline to service the request, either through tolerated failure or a genuine disinclination to comply, then a 'C<E<lt>resourceE<gt> not found>' exception is raised. =head2 SERVICE A reference to a L<Template::Service> object, or sub-class thereof, to which the L<Template> module should delegate. If unspecified, a L<Template::Service> object is automatically created using the current configuration hash. my $template = Template->new({ SERVICE => MyOrg::Template::Service->new({ ... }), }); =head2 CONTEXT A reference to a L<Template::Context> object which is used to define a specific environment in which template are processed. A L<Template::Context> object is passed as the only parameter to the Perl subroutines that represent "compiled" template documents. Template subroutines make callbacks into the context object to access Template Toolkit functionality, for example, to C<INCLUDE> or C<PROCESS> another template (L<include()|Template::Context#include()> and L<process()|Template::Context#process()> methods, respectively), to C<USE> a plugin (L<plugin()|Template::Context#plugin()>) or instantiate a filter (L<filter()|Template::Context#filter()>) or to access the stash (L<stash()|Template::Context#stash()>) which manages variable definitions via the L<get()|Template::Stash#get()> and L<set()|Template::Stash#set()> methods. my $template = Template->new({ CONTEXT => MyOrg::Template::Context->new({ ... }), }); =head2 STASH A reference to a L<Template::Stash> object or sub-class which will take responsibility for managing template variables. my $stash = MyOrg::Template::Stash->new({ ... }); my $template = Template->new({ STASH => $stash, }); If unspecified, a default stash object is created using the C<VARIABLES> configuration item to initialise the stash variables. my $template = Template->new({ VARIABLES => { id => 'abw', name => 'Andy Wardley', }, }; =head2 PARSER The L<Template::Parser> module implements a parser object for compiling templates into Perl code which can then be executed. A default object of this class is created automatically and then used by the L<Template::Provider> whenever a template is loaded and requires compilation. The C<PARSER> option can be used to provide a reference to an alternate parser object. my $template = Template->new({ PARSER => MyOrg::Template::Parser->new({ ... }), }); =head2 GRAMMAR The C<GRAMMAR> configuration item can be used to specify an alternate grammar for the parser. This allows a modified or entirely new template language to be constructed and used by the Template Toolkit. Source templates are compiled to Perl code by the L<Template::Parser> using the L<Template::Grammar> (by default) to define the language structure and semantics. Compiled templates are thus inherently "compatible" with each other and there is nothing to prevent any number of different template languages being compiled and used within the same Template Toolkit processing environment (other than the usual time and memory constraints). The L<Template::Grammar> file is constructed from a YACC like grammar (using C<Parse::YAPP>) and a skeleton module template. These files are provided, along with a small script to rebuild the grammar, in the F<parser> sub-directory of the distribution. You don't have to know or worry about these unless you want to hack on the template language or define your own variant. There is a F<README> file in the same directory which provides some small guidance but it is assumed that you know what you're doing if you venture herein. If you grok LALR parsers, then you should find it comfortably familiar. By default, an instance of the default L<Template::Grammar> will be created and used automatically if a C<GRAMMAR> item isn't specified. use MyOrg::Template::Grammar; my $template = Template->new({ GRAMMAR = MyOrg::Template::Grammar->new(); }); =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�v�# �# lib/Template/Manual/Syntax.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Syntax # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Syntax - Directive syntax, structure and semantics =head1 Tag Styles Template directives are embedded between start and end markers tags. By default these tag markers are C<[%> and C<%]>. [% PROCESS header %] <h1>Hello World!</h1> <a href="[% page.next %]"><img src="[% icon.next %].gif"></a> [% PROCESS footer %] You can change the tag characters using the C<START_TAG>, C<END_TAG> and C<TAG_STYLE> configuration options. You can also use the C<TAGS> directive to define a new tag style for the current template file. You can also set the C<INTERPOLATE> option to allow simple variable references to be embedded directly in templates, prefixed by a C<$>. # INTERPOLATE = 0 <td>[% name %]</td> <td>[% email %]</td> # INTERPOLATE = 1 <td>$name</td> <td>$email</td> Directives may be embedded anywhere in a line of text and can be split across several lines. Insignificant whitespace is generally ignored within the directive. [% INCLUDE header title = 'Hello World' bgcol = '#ffffff' %] [%INCLUDE menu align='right'%] Name: [% name %] ([%id%]) =head1 Outline Tags As of version 2.26, the Template Toolkit supports "outline" tags. These have a designated marker at the start of a line (C<%%> by default) and continue to the end of a line. The newline character at the end of the line is discarded (aka "chomped"). So rather than writing something like this: [% IF some.list.size -%] <ul> [% FOREACH item IN some.list -%] <li>[% item.html %]</li> [% END -%] </ul> [% END -%] You can write it like this instead: %% IF some.list.size <ul> %% FOREACH item IN some.list <li>[% item.html %]</li> %% END </ul> %% END Outline tags aren't enabled by default. There are a numbers of ways you can enable them. The first is to use the C<TAGS> directive to set the tag style to C<outline> in any templates where you want to use them. This will enable outline tags from that point on. [% TAGS outline -%] %% INCLUDE header You can set the C<TAGS> back to the C<default> value at some point later in the template if you want to disable them: [% TAGS default -%] You can set the C<TAG_STYLE> configuration option if you want then enabled in all templates by default. You can always use the C<[% TAGS default %]> directive to disable them in any templates or parts of templates if necessary. my $tt = Template->new({ TAG_STYLE => 'outline', }); The C<OUTLINE_TAG> option allows you to set the outline tag marker to something else if you're not a fan of percent signs. Setting this option will automatically enable outline tags. my $tt = Template->new({ OUTLINE_TAG => '>>', }); You can also use the C<TAGS> directive to define your own custom tags (start, end and now optionally, outline) for a template or part of a template. [% TAGS <* *> >> %] >> INCLUDE header # outline tag Hello <* name *> # inline tag If you only specify a start and end tag then outline tags will be disabled. [% TAGS <* *> %] # no outline tags =head1 Comments The C<#> character is used to indicate comments within a directive. When placed immediately inside the opening directive tag, it causes the entire directive to be ignored. [%# this entire directive is ignored no matter how many lines it wraps onto %] In any other position, it causes the remainder of the current line to be treated as a comment. [% # this is a comment theta = 20 # so is this rho = 30 # <aol>me too!</aol> %] =head1 Chomping Whitespace You can add C<-> or C<+> to the immediate start or end of a directive tag to control the whitespace chomping options. See the C<PRE_CHOMP> and C<POST_CHOMP> options for further details. [% BLOCK foo -%] # remove trailing newline This is block foo [%- END %] # remove leading newline =head1 Implicit Directives: GET and SET The simplest directives are C<GET> and C<SET> which retrieve and update variable values respectively. The C<GET> and C<SET> keywords are actually optional as the parser is smart enough to see them for what they really are (but note the caveat below on using side-effect notation). Thus, you'll generally see: [% SET foo = 10 %] [% GET foo %] written as: [% foo = 10 %] [% foo %] You can also express simple logical statements as implicit C<GET> directives: [% title or template.title or 'Default Title' %] [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %] All other directives should start with a keyword specified in UPPER CASE (but see the C<ANYCASE> option). All directives keywords are in UPPER CASE to make them visually distinctive and to distinguish them from variables of the same name but different case. It is perfectly valid, for example, to define a variable called C<stop> which is entirely separate from the C<STOP> directive. [% stop = 'Clackett Lane Bus Depot' %] The bus will next stop at [% stop %] # variable [% STOP %] # directive =head1 Block Directives Directives such as C<FOREACH>, C<WHILE>, C<BLOCK>, C<FILTER>, etc., mark the start of a block which may contain text or other directives up to the matching C<END> directive. Blocks may be nested indefinitely. The C<IF>, C<UNLESS>, C<ELSIF> and C<ELSE> directives also define blocks and may be grouped together in the usual manner. [% FOREACH item = [ 'foo' 'bar' 'baz' ] %] * Item: [% item %] [% END %] [% BLOCK footer %] Copyright 2000 [% me %] [% INCLUDE company/logo %] [% END %] [% IF foo %] [% FOREACH thing = foo.things %] [% thing %] [% END %] [% ELSIF bar %] [% INCLUDE barinfo %] [% ELSE %] do nothing... [% END %] Block directives can also be used in a convenient side-effect notation. [% INCLUDE userinfo FOREACH user = userlist %] [% INCLUDE debugtxt msg="file: $error.info" IF debugging %] [% "Danger Will Robinson" IF atrisk %] versus: [% FOREACH user = userlist %] [% INCLUDE userinfo %] [% END %] [% IF debugging %] [% INCLUDE debugtxt msg="file: $error.info" %] [% END %] [% IF atrisk %] Danger Will Robinson [% END %] =head1 Capturing Block Output The output of a directive can be captured by simply assigning the directive to a variable. [% headtext = PROCESS header title="Hello World" %] [% people = PROCESS userinfo FOREACH user = userlist %] This can be used in conjunction with the C<BLOCK> directive for defining large blocks of text or other content. [% poem = BLOCK %] The boy stood on the burning deck, His fleece was white as snow. A rolling stone gathers no moss, And Keith is sure to follow. [% END %] Note one important caveat of using this syntax in conjunction with side-effect notation. The following directive does not behave as might be expected: [% var = 'value' IF some_condition %] # does not work In this case, the directive is interpreted as (spacing added for clarity) [% var = IF some_condition %] value [% END %] rather than [% IF some_condition %] [% var = 'value' %] [% END %] The variable is assigned the output of the C<IF> block which returns C<'value'> if true, but nothing if false. In other words, the following directive will always cause 'var' to be cleared. [% var = 'value' IF 0 %] To achieve the expected behaviour, the directive should be written as: [% SET var = 'value' IF some_condition %] =head1 Chaining Filters Multiple C<FILTER> directives can be chained together in sequence. They are called in the order defined, piping the output of one into the input of the next. [% PROCESS somefile FILTER truncate(100) FILTER html %] The pipe character, C<|>, can also be used as an alias for C<FILTER>. [% PROCESS somefile | truncate(100) | html %] =head1 Multiple Directive Blocks Multiple directives can be included within a single tag when delimited by semi-colons. Note however that the C<TAGS> directive must always be specified in a tag by itself. [% IF title; INCLUDE header; ELSE; INCLUDE other/header title="Some Other Title"; END %] versus [% IF title %] [% INCLUDE header %] [% ELSE %] [% INCLUDE other/header title="Some Other Title" %] [% END %] =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�J�e5b 5b ! lib/Template/Manual/Variables.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Variables # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Variables - Template variables and code bindings =head1 Template Variables A reference to a hash array may be passed as the second argument to the L<process()|Template#process()> method, containing definitions of template variables. The C<VARIABLES> (a.k.a. C<PRE_DEFINE>) option can also be used to pre-define variables for all templates processed by the object. my $tt = Template->new({ VARIABLES => { version => 3.14, release => 'Sahara', }, }); my $vars = { serial_no => 271828, }; $tt->process('myfile', $vars); F<myfile> template: This is version [% version %] ([% release %]). Serial number: [% serial_no %] Generated Output: This is version 3.14 (Sahara) Serial number: 271828 Variable names may contain any alphanumeric characters or underscores. They may be lower, upper or mixed case although the usual convention is to use lower case. The case I<is> significant however, and 'C<foo>', 'C<Foo>' and 'C<FOO>' are all different variables. Upper case variable names are permitted, but not recommended due to a possible conflict with an existing or future reserved word. As of version 2.00, these are: GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP CLEAR TO STEP AND OR NOT MOD DIV END The variable values may be of virtually any Perl type, including simple scalars, references to lists, hash arrays, subroutines or objects. The Template Toolkit will automatically apply the correct procedure to accessing these values as they are used in the template. Example data: my $vars = { article => 'The Third Shoe', person => { id => 314, name => 'Mr. Blue', email => 'blue@nowhere.org', }, primes => [ 2, 3, 5, 7, 11, 13 ], wizard => sub { return join(' ', 'Abracadabra!', @_) }, cgi => CGI->new('mode=submit&debug=1'), }; Example template: [% article %] [% person.id %]: [% person.name %] <[% person.email %]> [% primes.first %] - [% primes.last %], including [% primes.3 %] [% primes.size %] prime numbers: [% primes.join(', ') %] [% wizard %] [% wizard('Hocus Pocus!') %] [% cgi.param('mode') %] Generated output: The Third Shoe 314: Mr. Blue <blue@nowhere.org> 2 - 13, including 7 6 prime numbers: 2, 3, 5, 7, 11, 13 Abracadabra! Abracadabra! Hocus Pocus! submit =head2 Scalar Values Regular scalar variables are accessed by simply specifying their name. As these are just entries in the top-level variable hash they can be considered special cases of hash array referencing as described below, with the main namespace hash automatically implied. [% article %] =head2 Hash Array References Members of hash arrays are accessed by specifying the hash reference and key separated by the dot 'C<.>' operator. Example data: my $vars = { 'home' => 'http://www.myserver.com/homepage.html', 'page' => { 'this' => 'mypage.html', 'next' => 'nextpage.html', 'prev' => 'prevpage.html', }, }; Example template: <a href="[% home %]">Home</a> <a href="[% page.prev %]">Previous Page</a> <a href="[% page.next %]">Next Page</a> Generated output: <a href="http://www.myserver.com/homepage.html">Home</a> <a href="prevpage.html">Previous Page</a> <a href="nextpage.html">Next Page</a> Any key in a hash which starts with a 'C<_>' or 'C<.>' character will be considered private and cannot be evaluated or updated from within a template. The undefined value will be returned for any such variable accessed which the Template Toolkit will silently ignore (unless the C<DEBUG> option is enabled). Example data: my $vars = { message => 'Hello World!', _secret => "On the Internet, no-one knows you're a dog", thing => { public => 123, _private => 456, '.hidden' => 789, }, }; Example template: [% message %] # outputs "Hello World!" [% _secret %] # no output [% thing.public %] # outputs "123" [% thing._private %] # no output [% thing..hidden %] # ERROR: unexpected token (..) You can disable this feature by setting the C<$Template::Stash::PRIVATE> package variable to a false value. $Template::Stash::PRIVATE = undef; # now you can thing._private To access a hash entry using a key stored in another variable, prefix the key variable with 'C<$>' to have it interpolated before use (see L<Variable Interpolation>). [% pagename = 'next' %] [% page.$pagename %] # same as [% page.next %] You can also access hash entry using C<item()> method. This might be helpful if you have complex key name. <pre> [% files.item('example.txt').content %] </pre> See L<Template::Manual::VMethods|Template::Manual::VMethods/"item"> for more info. When you assign to a variable that contains multiple namespace elements (i.e. it has one or more 'C<.>' characters in the name), any hashes required to represent intermediate namespaces will be created automatically. In this following example, the C<product> variable automatically springs into life as a hash array unless otherwise defined. [% product.id = 'XYZ-2000' product.desc = 'Bogon Generator' product.price = 666 %] The [% product.id %] [% product.desc %] costs $[% product.price %].00 Generated output: The XYZ-2000 Bogon Generator costs $666.00 You can use Perl's familiar C<{> ... C<}> construct to explicitly create a hash and assign it to a variable. Note that commas are optional between key/value pairs and C<=> can be used in place of C<=E<gt>>. # minimal TT style [% product = { id = 'XYZ-2000' desc = 'Bogon Generator' price = 666 } %] # perl style [% product = { id => 'XYZ-2000', desc => 'Bogon Generator', price => 666, } %] =head2 List References Items in lists are also accessed by use of the dot operator. Example data: my $vars = { people => [ 'Tom', 'Dick', 'Larry' ], }; Example template: [% people.0 %] # Tom [% people.1 %] # Dick [% people.2 %] # Larry The C<FOREACH> directive can be used to iterate through items in a list. [% FOREACH person IN people %] Hello [% person %] [% END %] Generated output: Hello Tom Hello Dick Hello Larry Lists can be constructed in-situ using the regular anonymous list C<[> ... C<]> construct. Commas between items are optional. [% cols = [ 'red', 'green', 'blue' ] %] [% FOREACH c IN cols %] [% c %] [% END %] or: [% FOREACH c IN [ 'red', 'green', 'blue' ] %] [% c %] [% END %] You can also create simple numerical sequences using the C<..> range operator: [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ] [% x = 4 y = 8 z = [x..y] # z is [ 4, 5, 6, 7, 8 ] %] =head2 Subroutines Template variables can contain references to Perl subroutines. When the variable is used, the Template Toolkit will automatically call the subroutine, passing any additional arguments specified. The return value from the subroutine is used as the variable value and inserted into the document output. my $vars = { wizard => sub { return join(' ', 'Abracadabra!', @_) }, }; Example template: [% wizard %] # Abracadabra! [% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus! =head2 Objects Template variables can also contain references to Perl objects. Methods are called using the dot operator to specify the method against the object variable. Additional arguments can be specified as with subroutines. use CGI; my $vars = { # hard coded CGI params for purpose of example cgi => CGI->new('mode=submit&debug=1'), }; Example template: [% FOREACH p IN cgi.param %] # returns list of param keys [% p %] => [% cgi.param(p) %] # fetch each param value [% END %] Generated output: mode => submit debug => 1 Object methods can also be called as lvalues. That is, they can appear on the left side of an assignment. The method will be called passing the assigning value as an argument. [% myobj.method = 10 %] equivalent to: [% myobj.method(10) %] =head2 Passing Parameters and Returning Values Subroutines and methods will be passed any arguments specified in the template. Any template variables in the argument list will first be evaluated and their resultant values passed to the code. my $vars = { mycode => sub { return 'received ' . join(', ', @_) }, }; template: [% foo = 10 %] [% mycode(foo, 20) %] # received 10, 20 Named parameters may also be specified. These are automatically collected into a single hash array which is passed by reference as the B<last> parameter to the sub-routine. Named parameters can be specified using either C<=E<gt>> or C<=> and can appear anywhere in the argument list. my $vars = { myjoin => \&myjoin, }; sub myjoin { # look for hash ref as last argument my $params = ref $_[-1] eq 'HASH' ? pop : { }; return join($params->{ joint } || ' + ', @_); } Example template: [% myjoin(10, 20, 30) %] [% myjoin(10, 20, 30, joint = ' - ' %] [% myjoin(joint => ' * ', 10, 20, 30 %] Generated output: 10 + 20 + 30 10 - 20 - 30 10 * 20 * 30 Parenthesised parameters may be added to any element of a variable, not just those that are bound to code or object methods. At present, parameters will be ignored if the variable isn't "callable" but are supported for future extensions. Think of them as "hints" to that variable, rather than just arguments passed to a function. [% r = 'Romeo' %] [% r(100, 99, s, t, v) %] # outputs "Romeo" User code should return a value for the variable it represents. This can be any of the Perl data types described above: a scalar, or reference to a list, hash, subroutine or object. Where code returns a list of multiple values the items will automatically be folded into a list reference which can be accessed as per normal. my $vars = { # either is OK, first is recommended items1 => sub { return [ 'foo', 'bar', 'baz' ] }, items2 => sub { return ( 'foo', 'bar', 'baz' ) }, }; Example template: [% FOREACH i IN items1 %] ... [% END %] [% FOREACH i IN items2 %] ... [% END %] =head2 Error Handling Errors can be reported from user code by calling C<die()>. Errors raised in this way are caught by the Template Toolkit and converted to structured exceptions which can be handled from within the template. A reference to the exception object is then available as the C<error> variable. my $vars = { barf => sub { die "a sick error has occurred\n"; }, }; Example template: [% TRY %] [% barf %] # calls sub which throws error via die() [% CATCH %] [% error.info %] # outputs "a sick error has occurred\n" [% END %] Error messages thrown via C<die()> are converted to exceptions of type C<undef> (the literal string "undef" rather than the undefined value). Exceptions of user-defined types can be thrown by calling C<die()> with a reference to a L<Template::Exception> object. use Template::Exception; my $vars = { login => sub { ...do something... die Template::Exception->new( badpwd => 'password too silly' ); }, }; Example template: [% TRY %] [% login %] [% CATCH badpwd %] Bad password: [% error.info %] [% CATCH %] Some other '[% error.type %]' error: [% error.info %] [% END %] The exception types C<stop> and C<return> are used to implement the C<STOP> and C<RETURN> directives. Throwing an exception as: die (Template::Exception->new('stop')); has the same effect as the directive: [% STOP %] =head1 Virtual Methods The Template Toolkit implements a number of "virtual methods" which can be applied to scalars, hashes or lists. For example: [% mylist = [ 'foo', 'bar', 'baz' ] %] [% newlist = mylist.sort %] Here C<mylist> is a regular reference to a list, and 'sort' is a virtual method that returns a new list of the items in sorted order. You can chain multiple virtual methods together. For example: [% mylist.sort.join(', ') %] Here the C<join> virtual method is called to join the sorted list into a single string, generating the following output: bar, baz, foo See L<Template::Manual::VMethods> for details of all the virtual methods available. =head1 Variable Interpolation The Template Toolkit uses C<$> consistently to indicate that a variable should be interpolated in position. Most frequently, you see this in double-quoted strings: [% fullname = "$honorific $firstname $surname" %] Or embedded in plain text when the C<INTERPOLATE> option is set: Dear $honorific $firstname $surname, The same rules apply within directives. If a variable is prefixed with a C<$> then it is replaced with its value before being used. The most common use is to retrieve an element from a hash where the key is stored in a variable. [% uid = 'abw' %] [% users.$uid %] # same as 'users.abw' Curly braces can be used to delimit interpolated variable names where necessary. [% users.${me.id}.name %] Directives such as C<INCLUDE>, C<PROCESS>, etc., that accept a template name as the first argument, will automatically quote it for convenience. [% INCLUDE foo/bar.txt %] The above example is equivalent to: [% INCLUDE "foo/bar.txt" %] To C<INCLUDE> a template whose name is stored in a variable, simply prefix the variable name with C<$> to have it interpolated. [% myfile = 'header' %] [% INCLUDE $myfile %] This is equivalent to: [% INCLUDE header %] Note also that a variable containing a reference to a L<Template::Document> object can also be processed in this way. my $vars = { header => Template::Document->new({ ... }), }; Example template: [% INCLUDE $header %] =head1 Local and Global Variables Any simple variables that you create, or any changes you make to existing variables, will only persist while the template is being processed. The top-level variable hash is copied before processing begins and any changes to variables are made in this copy, leaving the original intact. The same thing happens when you C<INCLUDE> another template. The current namespace hash is cloned to prevent any variable changes made in the included template from interfering with existing variables. The C<PROCESS> option bypasses the localisation step altogether making it slightly faster, but requiring greater attention to the possibility of side effects caused by creating or changing any variables within the processed template. [% BLOCK change_name %] [% name = 'bar' %] [% END %] [% name = 'foo' %] [% INCLUDE change_name %] [% name %] # foo [% PROCESS change_name %] [% name %] # bar Dotted compound variables behave slightly differently because the localisation process is only skin deep. The current variable namespace hash is copied, but no attempt is made to perform a deep-copy of other structures within it (hashes, arrays, objects, etc). A variable referencing a hash, for example, will be copied to create a new reference but which points to the same hash. Thus, the general rule is that simple variables (undotted variables) are localised, but existing complex structures (dotted variables) are not. [% BLOCK all_change %] [% x = 20 %] # changes copy [% y.z = 'zulu' %] # changes original [% END %] [% x = 10 y = { z => 'zebra' } %] [% INCLUDE all_change %] [% x %] # still '10' [% y.z %] # now 'zulu' If you create a complex structure such as a hash or list reference within a local template context then it will cease to exist when the template is finished processing. [% BLOCK new_stuff %] [% # define a new 'y' hash array in local context y = { z => 'zulu' } %] [% END %] [% x = 10 %] [% INCLUDE new_stuff %] [% x %] # outputs '10' [% y %] # nothing, y is undefined Similarly, if you update an element of a compound variable which I<doesn't> already exists then a hash will be created automatically and deleted again at the end of the block. [% BLOCK new_stuff %] [% y.z = 'zulu' %] [% END %] However, if the hash I<does> already exist then you will modify the original with permanent effect. To avoid potential confusion, it is recommended that you don't update elements of complex variables from within blocks or templates included by another. If you want to create or update truly global variables then you can use the 'global' namespace. This is a hash array automatically created in the top-level namespace which all templates, localised or otherwise see the same reference to. Changes made to variables within this hash are visible across all templates. [% global.version = 123 %] =head1 Compile Time Constant Folding In addition to variables that get resolved each time a template is processed, you can also define variables that get resolved just once when the template is compiled. This generally results in templates processing faster because there is less work to be done. To define compile-time constants, specify a C<CONSTANTS> hash as a constructor item as per C<VARIABLES>. The C<CONSTANTS> hash can contain any kind of complex, nested, or dynamic data structures, just like regular variables. my $tt = Template->new({ CONSTANTS => { version => 3.14, release => 'skyrocket', col => { back => '#ffffff', fore => '#000000', }, myobj => My::Object->new(), mysub => sub { ... }, joint => ', ', }, }); Within a template, you access these variables using the C<constants> namespace prefix. Version [% constants.version %] ([% constants.release %]) Background: [% constants.col.back %] When the template is compiled, these variable references are replaced with the corresponding value. No further variable lookup is then required when the template is processed. You can call subroutines, object methods, and even virtual methods on constant variables. [% constants.mysub(10, 20) %] [% constants.myobj(30, 40) %] [% constants.col.keys.sort.join(', ') %] One important proviso is that any arguments you pass to subroutines or methods must also be literal values or compile time constants. For example, these are both fine: # literal argument [% constants.col.keys.sort.join(', ') %] # constant argument [% constants.col.keys.sort.join(constants.joint) %] But this next example will raise an error at parse time because C<joint> is a runtime variable and cannot be determined at compile time. # ERROR: runtime variable argument! [% constants.col.keys.sort.join(joint) %] The C<CONSTANTS_NAMESPACE> option can be used to provide a different namespace prefix for constant variables. For example: my $tt = Template->new({ CONSTANTS => { version => 3.14, # ...etc... }, CONSTANTS_NAMESPACE => 'const', }); Constants would then be referenced in templates as: [% const.version %] =head1 Special Variables A number of special variables are automatically defined by the Template Toolkit. =head2 template The C<template> variable contains a reference to the main template being processed, in the form of a L<Template::Document> object. This variable is correctly defined within C<PRE_PROCESS>, C<PROCESS> and C<POST_PROCESS> templates, allowing standard headers, footers, etc., to access metadata items from the main template. The C<name> and C<modtime> metadata items are automatically provided, giving the template name and modification time in seconds since the epoch. Note that the C<template> variable always references the top-level template, even when processing other template components via C<INCLUDE>, C<PROCESS>, etc. =head2 component The C<component> variable is like C<template> but always contains a reference to the current, innermost template component being processed. In the main template, the C<template> and C<component> variable will reference the same L<Template::Document> object. In any other template component called from the main template, the C<template> variable will remain unchanged, but C<component> will contain a new reference to the current component. This example should demonstrate the difference: $template->process('foo') || die $template->error(), "\n"; F<foo> template: [% template.name %] # foo [% component.name %] # foo [% PROCESS footer %] F<footer> template: [% template.name %] # foo [% component.name %] # footer Additionally, the C<component> variable has two special fields: C<caller> and C<callers>. C<caller> contains the name of the template that called the current template (or undef if the values of C<template> and C<component> are the same). C<callers> contains a reference to a list of all the templates that have been called on the road to calling the current component template (like a call stack), with the outer-most template first. Here's an example: F<outer.tt2> template: [% component.name %] # 'outer.tt2' [% component.caller %] # undef [% component.callers %] # undef [% PROCESS 'middle.tt2' %] F<middle.tt2> template: [% component.name %] # 'middle.tt2' [% component.caller %] # 'outer.tt2' [% component.callers %] # [ 'outer.tt2' ] [% PROCESS 'inner.tt2' %] F<inner.tt2> template: [% component.name %] # 'inner.tt2' [% component.caller %] # 'middle.tt2' [% component.callers %] # [ 'outer.tt2', 'middle.tt2' ] =head2 loop Within a C<FOREACH> loop, the C<loop> variable references the L<Template::Iterator> object responsible for controlling the loop. [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%] [% "Items:\n" IF loop.first -%] [% loop.count %]/[% loop.size %]: [% item %] [% END %] =head2 error Within a C<CATCH> block, the C<error> variable contains a reference to the L<Template::Exception> object thrown from within the C<TRY> block. The C<type> and C<info> methods can be called or the variable itself can be printed for automatic stringification into a message of the form "C<$type error - $info>". See L<Template::Exception> for further details. [% TRY %] ... [% CATCH %] [% error %] [% END %] =head2 content The C<WRAPPER> method captures the output from a template block and then includes a named template, passing the captured output as the 'content' variable. [% WRAPPER box %] Be not afeard; the isle is full of noises, Sounds and sweet airs, that give delight and hurt not. [% END %] [% BLOCK box %] <blockquote class="prose"> [% content %] </blockquote> [% END %] =head1 Compound Variables Compound 'dotted' variables may contain any number of separate elements. Each element may evaluate to any of the permitted variable types and the processor will then correctly use this value to evaluate the rest of the variable. Arguments may be passed to any of the intermediate elements. [% myorg.people.sort('surname').first.fullname %] Intermediate variables may be used and will behave entirely as expected. [% sorted = myorg.people.sort('surname') %] [% sorted.first.fullname %] This simplified dotted notation has the benefit of hiding the implementation details of your data. For example, you could implement a data structure as a hash array one day and then change it to an object the next without requiring any change to the templates. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[ �R�J �J lib/Template/Manual/Views.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Views # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Views - Template Toolkit views (experimental) =head1 Overview A view is effectively a collection of templates and/or variable definitions which can be passed around as a self-contained unit. This then represents a particular interface or presentation style for other objects or items of data. You can use views to implement custom "skins" for an application or content set. You can use them to help simplify the presentation of common objects or data types. You can even use then to automate the presentation of complex data structures such as that generated in an C<XML::DOM> tree or similar. You let an iterator do the walking, and the view does the talking (or in this case, the presenting). Voila - you have view independent, structure shy traversal using templates. In general, views can be used in a number of different ways to achieve several different things. They elegantly solve some problems which were otherwise difficult or complicated, and make easy some things that were previously hard. At the moment, they're still very experimental. The directive syntax and underlying API are likely to change quite considerably over the next version or two. Please be very wary about building your multi-million dollar e-commerce solutions based around this feature. =head1 Views as Template Collectors/Providers The C<VIEW> directive starts a view definition and includes a name by which the view can be referenced. The view definition continues up to the matching C<END> directive. [% VIEW myview %] ... [% END %] The first role of a view is to act as a collector and provider of templates. The C<include()> method can be called on a view to effectively do the same thing as the C<INCLUDE> directive. The template name is passed as the first argument, followed by any local variable definitions for the template. [% myview.include('header', title='The Title') %] # equivalent to [% INCLUDE header title='The Title' %] Views accept a number of configuration options which can be used to control different aspects of their behaviour. The 'C<prefix>' and 'C<suffix>' options can be specified to add a fixed prefix and/or suffix to the name of each template. [% VIEW myview prefix = 'my/' suffix = '.tt2' ; END %] Now the call [% myview.include('header', title='The Title') %] is equivalent to [% INCLUDE my/header.tt2 title='The Title' %] Views provide an C<AUTOLOAD> method which maps method names to the C<include()> method. Thus, the following are all equivalent: [% myview.include('header', title='Hello World') %] [% myview.include_header(title='Hello World') %] [% myview.header(title='Hello World') %] =head1 Local BLOCK Definitions A C<VIEW> definition can include C<BLOCK> definitions which remain local to the view. A request for a particular template will return a C<BLOCK>, if defined, in preference to any other template of the same name. [% BLOCK foo %] public foo block [% END %] [% VIEW plain %] [% BLOCK foo %] plain foo block [% END %] [% END %] [% VIEW fancy %] [% BLOCK foo %] fancy foo block [% END %] [% END %] [% INCLUDE foo %] # public foo block [% plain.foo %] # plain foo block [% fancy.foo %] # fancy foo block In addition to C<BLOCK> definitions, a C<VIEW> can contain any other template directives. The entire C<VIEW> definition block is processed to initialise the view but no output is generated (this may change RSN - and get stored as 'C<output>' item, subsequently accessible as C<[% view.output %]>). However, directives that have side-effects, such as those that update a variable, will have noticeable consequences. =head1 Preserving Variable State within Views Views can also be used to save the values of any existing variables, or to create new ones at the point at which the view is defined. Unlike simple template metadata (C<META>) which can only contain static string values, the view initialisation block can contain any template directives and generate any kind of dynamic output and/or data items. [% VIEW my_web_site %] [% view.title = title or 'My Cool Web Site' %] [% view.author = "$abw.name, $abw.email" %] [% view.sidebar = INCLUDE my/sidebar.tt2 %] [% END %] Note that additional data items can be specified as arguments to the C<VIEW> directive. Anything that doesn't look like a configuration parameter is assumed to be a data item. This can be a little hazardous, of course, because you never know when a new configuration item might get added which interferes with your data. [% VIEW my_web_site # config options prefix = 'my/' # misc data title = title or 'My Cool Web Site' author = "$abw.name, $abw.email" sidebar = INCLUDE my/sidebar.tt2 %] ... [% END %] Outside of the view definition you can access the view variables as, for example: [% my_web_site.title %] One important feature is the equivalence of simple variables and templates. You can implement the view item 'C<title>' as a simple variable, a template defined in an external file, possibly with a prefix/suffix automatically appended, or as a local C<BLOCK> definition within the C<[% VIEW %] ... [% END %]> definition. If you use the syntax above then the view will Do The Right Thing to return the appropriate output. At the C<END> of the C<VIEW> definition the view is "sealed" to prevent you from accidentally updating any variable values. If you attempt to change the value of a variable after the C<END> of the C<VIEW> definition block then a C<view> error will be thrown. [% TRY; my_web_site.title = 'New Title'; CATCH; error; END %] The error above will be reported as: view error - cannot update item in sealed view: title The same is true if you pass a parameter to a view variable. This is interpreted as an attempt to update the variable and will raise the same warning. [% my_web_site.title('New Title') %] # view error! You can set the C<silent> parameter to have the view ignore these parameters and simply return the variable value. [% VIEW my_web_site silent = 1 title = title or 'My Cool Web Site' # ... ; END %] [% my_web_site.title('Blah Blah') %] # My Cool Web Site Alternately, you can specify that a view is unsealed allowing existing variables to be updated and new variables defined. [% VIEW my_web_site sealed = 0 title = title or 'My Cool Web Site' # ... ; END %] [% my_web_site.title('Blah Blah') %] # Blah Blah [% my_web_site.title %] # Blah Blah =head2 Inheritance, Delegation and Reuse Views can be inherited from previously defined views by use of the C<base> parameter. This example shows how a base class view is defined which applies a C<view/default/> prefix to all template names. [% VIEW my.view.default prefix = 'view/default/'; END %] Thus the directive: [% my.view.default.header(title='Hello World') %] is now equivalent to: [% INCLUDE view/default/header title='Hello World' %] A second view can be defined which specifies the default view as a base. [% VIEW my.view.fancy base = my.view.default prefix = 'view/fancy/'; END %] Now the directive: [% my.view.fancy.header(title='Hello World') %] will resolve to: [% INCLUDE view/fancy/header title='Hello World' %] or if that doesn't exist, it will be handled by the base view as: [% INCLUDE view/default/header title='Hello World' %] When a parent view is specified via the C<base> parameter, the delegation of a view to its parent for fetching templates and accessing user defined variables is automatic. You can also implement your own inheritance, delegation or other reuse patterns by explicitly delegating to other views. [% BLOCK foo %] public foo block [% END %] [% VIEW plain %] [% BLOCK foo %] <plain>[% PROCESS foo %]</plain> [% END %] [% END %] [% VIEW fancy %] [% BLOCK foo %] [% plain.foo | replace('plain', 'fancy') %] [% END %] [% END %] [% plain.foo %] # <plain>public foo block</plain> [% fancy.foo %] # <fancy>public foo block</fancy> Note that the regular C<INCLUDE/PROCESS/WRAPPER> directives work entirely independently of views and will always get the original, unaltered template name rather than any local per-view definition. =head2 Self-Reference A reference to the view object under definition is available with the C<VIEW ... END> block by its specified name and also by the special name 'C<view>' (similar to the C<my $self = shift;> in a Perl method or the 'C<this>' pointer in C++, etc). The view is initially unsealed allowing any data items to be defined and updated within the C<VIEW ... END> block. The view is automatically sealed at the end of the definition block, preventing any view data from being subsequently changed. (NOTE: sealing should be optional. As well as sealing a view to prevent updates (C<SEALED>), it should be possible to set an option in the view to allow external contexts to update existing variables (C<UPDATE>) or even create totally new view variables (C<CREATE>)). [% VIEW fancy %] [% fancy.title = 'My Fancy Title' %] [% fancy.author = 'Frank Open' %] [% fancy.col = { bg => '#ffffff', bar => '#a0a0ff' } %] [% END %] or [% VIEW fancy %] [% view.title = 'My Fancy Title' %] [% view.author = 'Frank Open' %] [% view.col = { bg => '#ffffff', bar => '#a0a0ff' } %] [% END %] It makes no real difference in this case if you refer to the view by its name, 'C<fancy>', or by the general name, 'C<view>'. Outside of the view block, however, you should always use the given name, 'C<fancy>': [% fancy.title %] [% fancy.author %] [% fancy.col.bg %] The choice of given name or 'C<view>' is much more important when it comes to C<BLOCK> definitions within a C<VIEW>. It is generally recommended that you use 'C<view>' inside a C<VIEW> definition because this is guaranteed to be correctly defined at any point in the future when the block gets called. The original name of the view might have long since been changed or reused but the self-reference via 'C<view>' should always be intact and valid. Take the following VIEW as an example: [% VIEW foo %] [% view.title = 'Hello World' %] [% BLOCK header %] Title: [% view.title %] [% END %] [% END %] Even if we rename the view, or create a new C<foo> variable, the header block still correctly accesses the C<title> attribute of the view to which it belongs. Whenever a view C<BLOCK> is processed, the C<view> variable is always updated to contain the correct reference to the view object to which it belongs. [% bar = foo %] [% foo = { title => "New Foo" } %] # no problem [% bar.header %] # => Title: Hello World =head2 Saving References to External Views When it comes to view inheritance, it's always a good idea to take a local copy of a parent or delegate view and store it as an attribute within the view for later use. This ensures that the correct view reference is always available, even if the external name of a view has been changed. [% VIEW plain %] ... [% END %] [% VIEW fancy %] [% view.plain = plain %] [% BLOCK foo %] [% view.plain.foo | replace('plain', 'fancy') %] [% END %] [% END %] [% plain.foo %] # => <plain>public foo block</plain> [% plain = 'blah' %] # no problem [% fancy.foo %] # => <fancy>public foo block</fancy> =head2 Views as Data Presenters Another key role of a view is to act as a dispatcher to automatically apply the correct template to present a particular object or data item. This is handled via the C<print()> method. Here's an example: [% VIEW foo %] [% BLOCK text %] Some text: [% item %] [% END %] [% BLOCK hash %] a hash: [% FOREACH key = item.keys.sort -%] [% key %] => [% item.$key %] [% END -%] [% END %] [% BLOCK list %] a list: [% item.sort.join(', ') %] [% END %] [% END %] We can now use the view to print text, hashes or lists. The C<print()> method includes the right template depending on the typing of the argument (or arguments) passed. [% some_text = 'I read the news today, oh boy.' %] [% a_hash = { house => 'Lords', hall => 'Albert' } %] [% a_list = [ 'sure', 'Nobody', 'really' ] %] [% view.print(some_text) %] # Some text: I read the news today, oh boy. [% view.print(a_hash) %] # a hash: hall => Albert house => Lords [% view.print(a_list) %] # a list: Nobody, really, sure You can also provide templates to print objects of any other class. The class name is mapped to a template name with all non-word character sequences such as 'C<::>' converted to a single 'C<_>'. [% VIEW foo %] [% BLOCK Foo_Bar %] a Foo::Bar object: thingies: [% view.print(item.thingies) %] doodahs: [% view.print(item.doodahs) %] [% END %] [% END %] [% USE fubar = Foo::Bar(...) %] [% foo.print(fubar) %] Note how we use the view object to display various items within the objects ('C<thingies>' and 'C<doodahs>'). We don't need to worry what kind of data these represent (text, list, hash, etc) because we can let the view worry about it, automatically mapping the data type to the correct template. Views may define their own type =E<gt> template map. [% VIEW foo map = { TEXT => 'plain_text', ARRAY => 'show_list', HASH => 'show_hash', My::Module => 'template_name' default => 'any_old_data' } %] [% BLOCK plain_text %] ... [% END %] ... [% END %] They can also provide a C<default> map entry, specified as part of the C<map> hash or as a parameter by itself. [% VIEW foo map = { ... }, default = 'whatever' %] ... [% END %] or [% VIEW foo %] [% view.map = { ... } view.default = 'whatever' %] ... [% END %] The C<print()> method provides one more piece of magic. If you pass it a reference to an object which provides a C<present()> method, then the method will be called passing the view as an argument. This then gives any object a chance to determine how it should be presented via the view. package Foo::Bar; ... sub present { my ($self, $view) = @_; return "a Foo::Bar object:\n" . "thingies: " . $view->print($self->{ _THINGIES }) . "\n" . "doodahs: " . $view->print($self->{ _DOODAHS }) . "\n"; } The object is free to delve deeply into its innards and mess around with its own private data, before presenting the relevant data via the view. In a more complex example, a C<present()> method might walk part of a tree making calls back against the view to present different nodes within the tree. We may not want to expose the internal structure of the tree (because that would break encapsulation and make our presentation code dependant on it) but we want to have some way of walking the tree and presenting items found in a particular manner. This is known as I<Structure Shy Traversal>. Our view object doesn't require prior knowledge about the internal structure of any data set to be able to traverse it and present the data contained therein. The data items themselves, via the C<present()> method, can implement the internal iterators to guide the view along the right path to presentation happiness. The upshot is that you can use views to greatly simplify the display of data structures like C<XML::DOM> trees. The documentation for the C<Template::Plugin::XML::DOM> module contains an example of this. In essence, it looks something like this: XML source: <user name="Andy Wardley"> <project id="iCan" title="iCan, but theyCan't"/> <project id="p45" title="iDid, but theyDidn't"/> </user> TT View: [% VIEW fancy %] [% BLOCK user %] User: [% item.name %] [% item.content(myview) %] [% END %] [% BLOCK project %] Project: [% project.id %] - [% project.name %] [% END %] [% END %] Generate view: [% USE dom = XML.DOM %] [% fancy.print(dom.parse(xml_source)) %] Output: User: Andy Wardley Project: iCan - iCan, but theyCan't Project: p45 - iDid, but theyDidn't The same approach can be applied to many other areas. Here's an example from the C<File>/C<Directory> plugins. [% VIEW myview %] [% BLOCK file %] - [% item.name %] [% END %] [% BLOCK directory %] * [% item.name %] [% item.content(myview) FILTER indent %] [% END %] [% END %] [% USE dir = Directory(dirpath) %] [% myview.print(dir) %] And here's the same approach use to convert POD documentation to any other format via template. [% # load Pod plugin and parse source file into Pod Object Model USE Pod; pom = Pod.parse_file(my_pod_file); # define view to map all Pod elements to "pod/html/xxx" templates VIEW pod2html prefix='pod/html'; END; # now print document via view (i.e. as HTML) pod2html.print(pom) %] Here we simply define a template prefix for the view which causes the view to look for C<pod/html/head1>, C<pod/html/head2>, C<pod/html/over> as templates to present the different sections of the parsed Pod document. There are some examples in the Template Toolkit test suite: F<t/pod.t> and F<t/view.t> which may shed some more light on this. See the distribution sub-directory F<examples/pod/html> for examples of Pod -E<gt> HTML templates. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�H} R R lib/Template/Manual/VMethods.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::VMethods # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::VMethods - Virtual Methods =head1 Scalar Virtual Methods =head2 chunk(size) Splits the value into a list of chunks of a certain size. [% ccard_no = "1234567824683579"; ccard_no.chunk(4).join %] Output: 1234 5678 2468 3579 If the size is specified as a negative number then the text will be chunked from right-to-left. This gives the correct grouping for numbers, for example. [% number = 1234567; number.chunk(-3).join(',') %] Output: 1,234,567 =head2 collapse Returns the text with any leading and trailing whitespace removed and any internal sequences of whitespace converted to a single space [% text = " The bird\n is the word" %] [% text.collapse %] # The bird is the word =head2 defined Returns true if the value is defined. [% user = get_user(uid) IF uid.defined %] =head2 dquote Returns the text with any double quote characters escaped with a backslash prefix. Any newline characters in the text will be replaced with "\n". [% quote = 'He said "Oh really?"' %] [% quote.dquote %] # He said \"Oh really?\" =head2 hash Return the value as a hash reference containing a single entry with the key C<value> indicating the original scalar value. As with the C<list> virtual method, this is generally used to help massage data into different formats. =head2 lcfirst Returns the text with the first letter converted to lower case. [% word = 'BIRD' %] [% word.lcfirst %] # bIRD =head2 length Returns the length of the string representation of the item: [% IF password.length < 8 %] Password too short, dumbass! [% END %] =head2 empty Returns true if the string is empty: [% IF details.empty %] No details specified [% END %] =head2 list Return the value as a single element list. This can be useful if you have a variable which may contain a single item or a list and you want to treat them equally. The C<list> method can be called against a list reference and will simply return the original reference, effectively a no-op. [% thing.list.size %] # thing can be a scalar or a list =head2 lower Returns the text in lower case. [% word = 'BIRD' %] [% word.lower %] # bird =head2 match(pattern, global) Performs a regular expression match on the string using the pattern passed as an argument. If the pattern matches the string then the method returns a reference to a list of any strings captured within parenthesis in the pattern. [% name = 'Larry Wall' %] [% matches = name.match('(\w+) (\w+)') %] [% matches.1 %], [% matches.0 %] # Wall, Larry If the pattern does not match then the method returns false, rather than returning an empty list which Perl and the Template Toolkit both consider to be a true value. This allows you to write expression like this. [% "We're not worthy!" IF name.match('Larry Wall') %] [% IF (matches = name.match('(\w+) (\w+)')) %] pattern matches: [% matches.join(', ') %] [% ELSE %] pattern does not match [% END %] Any regex modifiers, like C</s>, should be added in the regex using the C<(?s)> syntax. For example, to modify the regex to disregard whitespace (the C</x> switch), use: [% re = '(?x) (\w+) [ ] (\w+) '; matches = name.match(re); %] To perform a global search to match the pattern as many times as it appears in the source string, provide a true value for the C<global> argument following the pattern. [% text = 'bandanna'; text.match('an+', 1).join(', ') # an, ann %] =head2 repeat(n) Repeat the string a specified number of times. [% name = 'foo' %] [% name.repeat(3) %] # foofoofoo =head2 replace(search, replace) Outputs the string with all instances of the first argument (specified as a Perl regular expression) with the second. [% name = 'foo, bar & baz' %] [% name.replace('\W+', '_') %] # foo_bar_baz You can use C<$1>, C<$2>, etc., to reference captured parts (in parentheses) in the regular expression. Just be careful to I<single> quote the replacement string. If you use I<double> quotes then TT will try and interpolate the variables before passing the string to the C<replace> vmethod. [% name = 'FooBarBaz' %] [% name.replace('([A-Z])', ' $1') %] # Foo Bar Baz =head2 remove(pattern) Outputs the string with all instances of the pattern (specified as a Perl regular expression) removed. [% name = 'foo, bar & baz' %] [% name.remove('\W+') %] # foobarbaz =head2 search(pattern) Performs a similar function to L<match> but simply returns true if the string matches the regular expression pattern passed as an argument. [% name = 'foo bar baz' %] [% name.search('bar') ? 'bar' : 'no bar' %] # bar This virtual method is now deprecated in favour of L<match>. Move along now, there's nothing more to see here. =head2 size Always returns 1 for scalar values. This method is provided for consistency with the hash and list size methods. =head2 split(pattern) Calls Perl's C<split()> function to split a string into a list of strings. [% FOREACH dir IN mypath.split(':') %] [% dir %] [% END %] =head2 substr(offset, length, replacement) Returns a substring starting at C<offset>, for C<length> characters. [% str 'foo bar baz wiz waz woz') %] [% str.substr(4, 3) %] # bar If C<length> is not specified then it returns everything from the C<offset> to the end of the string. [% str.substr(12) %] # wiz waz woz If both C<length> and C<replacement> are specified, then the method replaces everything from C<offset> for C<length> characters with C<$replacement>. The substring removed from the string is then returned. [% str.substr(0, 11, 'FOO') %] # foo bar baz [% str %] # FOO wiz waz woz =head2 squote Returns the text with any single quote characters escaped with a backslash prefix. [% tim = "Tim O'Reilly" %] [% tim.squote %] # Tim O\'Reilly =head2 trim Returns the text with any leading and trailing whitespace removed. [% text = ' hello world ' %] [% text.trim %] # hello world =head2 ucfirst Returns the text with the first letter converted to upper case. [% word = 'bird' %] [% word.ucfirst %] # Bird =head2 upper Returns the text in upper case. [% word = 'bird' %] [% word.upper %] # BIRD =head1 Hash Virtual Methods =head2 keys Returns a list of keys in the hash. They are not returned in any particular order, but the order is the same as for the corresponding values method. [% FOREACH key IN hash.keys %] * [% key %] [% END %] If you want the keys in sorted order, use the list C<sort> method. [% FOREACH key IN hash.keys.sort %] * [% key %] [% END %] Having got the keys in sorted order, you can then use variable interpolation to fetch the value. This is shown in the following example by the use of C<$key> to fetch the item from C<hash> whose key is stored in the C<key> variable. [% FOREACH key IN hash.keys.sort %] * [% key %] = [% hash.$key %] [% END %] Alternately, you can use the C<pairs> method to get a list of key/value pairs in sorted order. =head2 values Returns a list of the values in the hash. As with the C<keys> method, they are not returned in any particular order, although it is the same order that the keys are returned in. [% hash.values.join(', ') %] =head2 items Returns a list of both the keys and the values expanded into a single list. [% hash = { a = 10 b = 20 }; hash.items.join(', ') # a, 10, b, 20 %] =head2 each This method currently returns the same thing as the C<items> method. However, please note that this method will change in the next major version of the Template Toolkit (v3) to return the same thing as the C<pairs> method. This will be done in an effort to make these virtual method more consistent with each other and how Perl works. In anticipation of this, we recommend that you stop using C<hash.each> and instead use C<hash.items>. =head2 pairs This method returns a list of key/value pairs. They are returned in sorted order according to the keys. [% FOREACH pair IN product.pairs %] * [% pair.key %] is [% pair.value %] [% END %] =head2 list Returns the contents of the hash in list form. An argument can be passed to indicate the desired items required in the list: C<keys> to return a list of the keys (same as C<hash.keys>), C<values> to return a list of the values (same as C<hash.values>), C<each> to return as list of key and values (same as C<hash.each>), or C<pairs> to return a list of key/value pairs (same as C<hash.pairs>). [% keys = hash.list('keys') %] [% values = hash.list('values') %] [% items = hash.list('each') %] [% pairs = hash.list('pairs') %] When called without an argument it currently returns the same thing as the C<pairs> method. However, please note that this method will change in the next major version of the Template Toolkit (v3) to return a reference to a list containing the single hash reference (as per the scalar list method). In anticipation of this, we recommend that you stop using C<hash.list> and instead use C<hash.pairs>. =head2 sort, nsort Return a list of the keys, sorted alphabetically (C<sort>) or numerically (C<nsort>) according to the corresponding values in the hash. [% FOREACH n IN phones.sort %] [% phones.$n %] is [% n %], [% END %] =head2 import The C<import> method can be called on a hash array to import the contents of another hash array. [% hash1 = { foo = 'Foo' bar = 'Bar' } hash2 = { wiz = 'Wiz' woz = 'Woz' } %] [% hash1.import(hash2) %] [% hash1.wiz %] # Wiz You can also call the C<import()> method by itself to import a hash array into the current namespace hash. [% user = { id => 'lwall', name => 'Larry Wall' } %] [% import(user) %] [% id %]: [% name %] # lwall: Larry Wall =head2 defined, exists Returns a true or false value if an item in the hash denoted by the key passed as an argument is defined or exists, respectively. [% hash.defined('somekey') ? 'yes' : 'no' %] [% hash.exists('somekey') ? 'yes' : 'no' %] When called without any argument, C<hash.defined> returns true if the hash itself is defined (e.g. the same effect as C<scalar.defined>). =head2 delete Delete one or more items from the hash. [% hash.delete('foo', 'bar') %] =head2 size Returns the number of key/value pairs in the hash. =head2 empty Returns true if the hash is empty: [% IF config.empty %] No configuration available [% END %] =head2 item Returns an item from the hash using a key passed as an argument. [% hash.item('foo') %] # same as hash.foo =head1 List Virtual Methods =head2 first, last Returns the first/last item in the list. The item is not removed from the list. [% results.first %] to [% results.last %] If either is given a numeric argument C<n>, they return the first or last C<n> elements: The first 5 results are [% results.first(5).join(", ") %]. =head2 size, max Returns the size of a list (number of elements) and the maximum index number (size - 1), respectively. [% results.size %] search results matched your query =head2 empty Returns true if the list is empty: [% IF results.empty %] No results found [% END %] =head2 defined Returns a true or false value if the item in the list denoted by the argument is defined. [% list.defined(3) ? 'yes' : 'no' %] When called without any argument, C<list.defined> returns true if the list itself is defined (e.g. the same effect as C<scalar.defined>). =head2 reverse Returns the items of the list in reverse order. [% FOREACH s IN scores.reverse %] ... [% END %] =head2 join Joins the items in the list into a single string, using Perl's C<join()> function. [% items.join(', ') %] =head2 grep Returns a list of the items in the list that match a regular expression pattern. [% FOREACH directory.files.grep('\.txt$') %] ... [% END %] =head2 sort, nsort Returns the items in alpha (C<sort>) or numerical (C<nsort>) order. [% library = books.sort %] An argument can be provided to specify a search key. Where an item in the list is a hash reference, the search key will be used to retrieve a value from the hash which will then be used as the comparison value. Where an item is an object which implements a method of that name, the method will be called to return a comparison value. [% library = books.sort('author') %] In the example, the C<books> list can contains hash references with an C<author> key or objects with an C<author> method. You can also specify multiple sort keys. [% library = books.sort('author', 'title') %] In this case the books will be sorted primarily by author. If two or more books have authors with the same name then they will be sorted by title. =head2 unshift(item), push(item) The C<push()> method adds an item or items to the end of list. [% mylist.push(foo) %] [% mylist.push(foo, bar) %] The C<unshift()> method adds an item or items to the start of a list. [% mylist.unshift(foo) %] [% mylist.push(foo, bar) %] =head2 shift, pop Removes the first/last item from the list and returns it. [% first = mylist.shift %] [% last = mylist.pop %] =head2 unique Returns a list of the unique elements in a list, in the same order as in the list itself. [% mylist = [ 1, 2, 3, 2, 3, 4, 1, 4, 3, 4, 5 ] %] [% numbers = mylist.unique %] While this can be explicitly sorted, it is not required that the list be sorted before the unique elements are pulled out (unlike the Unix command line utility). [% numbers = mylist.unique.sort %] =head2 import Appends the contents of one or more other lists to the end of the current list. [% one = [ 1 2 3 ]; two = [ 4 5 6 ]; three = [ 7 8 9 ]; one.import(two, three); one.join(', '); # 1, 2, 3, 4, 5, 6, 7, 8, 9 %] Import also allows chaining. The below syntax is equivalent. [% one = [ 1 2 3 ]; two = [ 4 5 6 ]; three = [ 7 8 9 ]; one.import(two, three).join(', '); # 1, 2, 3, 4, 5, 6, 7, 8, 9 # or: one.import(two).import(three).join(', '); # 1, 2, 3, 4, 5, 6, 7, 8, 9 %] =head2 merge Returns a list composed of zero or more other lists: [% list_one = [ 1 2 3 ]; list_two = [ 4 5 6 ]; list_three = [ 7 8 9 ]; list_four = list_one.merge(list_two, list_three); %] The original lists are not modified. =head2 slice(from, to) Returns a slice of items in the list between the bounds passed as arguments. If the second argument, C<to>, isn't specified, then it defaults to the last item in the list. The original list is not modified. [% first_three = list.slice(0,2) %] [% last_three = list.slice(-3, -1) %] =head2 splice(offset, length, list) Behaves just like Perl's C<splice()> function allowing you to selectively remove and/or replace elements in a list. It removes C<length> items from the list, starting at C<offset> and replaces them with the items in C<list>. [% play_game = [ 'play', 'scrabble' ]; ping_pong = [ 'ping', 'pong' ]; redundant = play_game.splice(1, 1, ping_pong); redundant.join; # scrabble play_game.join; # play ping pong %] The method returns a list of the items removed by the splice. You can use the C<CALL> directive to ignore the output if you're not planning to do anything with it. [% CALL play_game.splice(1, 1, ping_pong) %] As well as providing a reference to a list of replacement values, you can pass in a list of items. [% CALL list.splice(-1, 0, 'foo', 'bar') %] Be careful about passing just one item in as a replacement value. If it is a reference to a list then the contents of the list will be used. If it's not a list, then it will be treated as a single value. You can use square brackets around a single item if you need to be explicit: [% # push a single item, an_item CALL list.splice(-1, 0, an_item); # push the items from another_list CALL list.splice(-1, 0, another_list); # push a reference to another_list CALL list.splice(-1, 0, [ another_list ]); %] =head2 hash Returns a reference to a hash array comprised of the elements in the list. The even-numbered elements (0, 2, 4, etc) become the keys and the odd-numbered elements (1, 3, 5, etc) the values. [% list = ['pi', 3.14, 'e', 2.718] %] [% hash = list.hash %] [% hash.pi %] # 3.14 [% hash.e %] # 2.718 If a numerical argument is provided then the hash returned will have keys generated for each item starting at the number specified. [% list = ['beer', 'peanuts'] %] [% hash = list.hash(1) %] [% hash.1 %] # beer [% hash.2 %] # peanuts =head2 item Returns an item from the list using an index passed as an argument. [% list.item(0) %] # same as list.0 =head1 Automagic Promotion of Scalar to List for Virtual Methods In addition to the scalar virtual methods listed in the previous section, you can also call any list virtual method against a scalar. The item will be automagically promoted to a single element list and the appropriate list virtual method will be called. One particular benefit of this comes when calling subroutines or object methods that return a list of items, rather than the preferred reference to a list of items. In this case, the Template Toolkit automatically folds the items returned into a list. The upshot is that you can continue to use existing Perl modules or code that returns lists of items, without having to refactor it just to keep the Template Toolkit happy (by returning references to list). C<Class::DBI> module is just one example of a particularly useful module which returns values this way. If only a single item is returned from a subroutine then the Template Toolkit assumes it meant to return a single item (rather than a list of 1 item) and leaves it well alone, returning the single value as it is. If you're executing a database query, for example, you might get 1 item returned, or perhaps many items which are then folded into a list. The C<FOREACH> directive will happily accept either a list or a single item which it will treat as a list. So it's safe to write directives like this, where we assume that the C<something> variable is bound to a subroutine which may return one or more items: [% FOREACH item IN something %] ... [% END %] The automagic promotion of scalars to single item lists means that you can also use list virtual methods safely, even if you only get one item returned. For example: [% something.first %] [% something.join %] [% something.reverse.join(', ') %] Note that this is very much a last-ditch behaviour. If the single item return is an object with a C<first> method, for example, then that will be called, as expected, in preference to the list virtual method. =head1 Defining Custom Virtual Methods You can define your own virtual methods for scalars, lists and hash arrays. The L<Template::Stash> package variables C<$SCALAR_OPS>, C<$LIST_OPS> and C<$HASH_OPS> are references to hash arrays that define these virtual methods. C<HASH_OPS> and C<LIST_OPS> methods are subroutines that accept a hash/list reference as the first item. C<SCALAR_OPS> are subroutines that accept a scalar value as the first item. Any other arguments specified when the method is called will be passed to the subroutine. # load Template::Stash to make method tables visible use Template::Stash; # define list method to return new list of odd numbers only $Template::Stash::LIST_OPS->{ odd } = sub { my $list = shift; return [ grep { $_ % 2 } @$list ]; }; Example template: [% primes = [ 2, 3, 5, 7, 9 ] %] [% primes.odd.join(', ') %] # 3, 5, 7, 9 TODO: document the define_vmethod() method which makes this even easier =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�Y�P�� �� " lib/Template/Manual/Directives.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual::Directives # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Directives - Template directives =head1 Accessing and Updating Template Variables =head2 GET The C<GET> directive retrieves and outputs the value of the named variable. [% GET foo %] The C<GET> keyword is optional. A variable can be specified in a directive tag by itself. [% foo %] The variable can have an unlimited number of elements, each separated by a dot. Each element can have arguments specified within parentheses. [% foo %] [% bar.baz %] [% biz.baz(10) %] ...etc... See L<Template::Manual::Variables> for a full discussion on template variables. You can also specify expressions using the logical (C<and>, C<or>, C<not>, C<?>, C<:>) and mathematic operators (C<+>, C<->, C<*>, C</>, C<%>, C<mod>, C<div>). [% template.title or default.title %] [% score * 100 %] [% order.nitems ? checkout(order.total) : 'no items' %] The C<div> operator returns the integer result of division. Both C<%> and C<mod> return the modulus (i.e. remainder) of division. [% 15 / 6 %] # 2.5 [% 15 div 6 %] # 2 [% 15 mod 6 %] # 3 =head2 CALL The C<CALL> directive is similar to C<GET> in evaluating the variable named, but doesn't print the result returned. This can be useful when a variable is bound to a sub-routine or object method which you want to call but aren't interested in the value returned. [% CALL dbi.disconnect %] [% CALL inc_page_counter(page_count) %] =head2 SET The C<SET> directive allows you to assign new values to existing variables or create new temporary variables. [% SET title = 'Hello World' %] The C<SET> keyword is also optional. [% title = 'Hello World' %] Variables may be assigned the values of other variables, unquoted numbers (2.718), literal text ('single quotes') or quoted text ("double quotes"). In the latter case, any variable references within the text will be interpolated when the string is evaluated. Variables should be prefixed by C<$>, using curly braces to explicitly scope the variable name where necessary. [% foo = 'Foo' %] # literal value 'Foo' [% bar = foo %] # value of variable 'foo' [% cost = '$100' %] # literal value '$100' [% item = "$bar: ${cost}.00" %] # value "Foo: $100.00" Multiple variables may be assigned in the same directive and are evaluated in the order specified. Thus, the above could have been written: [% foo = 'Foo' bar = foo cost = '$100' item = "$bar: ${cost}.00" %] Simple expressions can also be used, as per C<GET>. [% ten = 10 twenty = 20 thirty = twenty + ten forty = 2 * twenty fifty = 100 div 2 six = twenty mod 7 %] You can concatenate strings together using the C<'_'> underscore operator. In Perl 5, the C<.> dot is used for string concatenation, but in Perl 6, as in the Template Toolkit, the C<.> dot will be used as the method calling operator and C<'_'> underscore will be used for string concatenation. Note that the operator must be specified with surrounding whitespace which, as Larry says, is construed as a feature: [% copyright = '(C) Copyright' _ year _ ' ' _ author %] You can, of course, achieve a similar effect with double quoted string interpolation. [% copyright = "(C) Copyright $year $author" %] =head2 DEFAULT The C<DEFAULT> directive is similar to C<SET> but only updates variables that are currently undefined or have no "true" value (in the Perl sense). [% DEFAULT name = 'John Doe' id = 'jdoe' %] This can be particularly useful in common template components to ensure that some sensible default are provided for otherwise undefined variables. [% DEFAULT title = 'Hello World' bgcol = '#ffffff' %] <html> <head> <title>[% title %]</title> </head> <body bgcolor="[% bgcol %]"> ...etc... =head1 Processing Template Files and Blocks =head2 INSERT The C<INSERT> directive is used to insert the contents of an external file at the current position. [% INSERT myfile %] No attempt to parse or process the file is made. The contents, possibly including any embedded template directives, are inserted intact. The filename specified should be relative to one of the C<INCLUDE_PATH> directories. Absolute (i.e. starting with C</>) and relative (i.e. starting with C<.>) filenames may be used if the C<ABSOLUTE> and C<RELATIVE> options are set, respectively. Both these options are disabled by default. my $template = Template->new({ INCLUDE_PATH => '/here:/there', }); $template->process('myfile'); F<myfile>: [% INSERT foo %] # looks for /here/foo then /there/foo [% INSERT /etc/passwd %] # file error: ABSOLUTE not set [% INSERT ../secret %] # file error: RELATIVE not set For convenience, the filename does not need to be quoted as long as it contains only alphanumeric characters, underscores, dots or forward slashes. Names containing any other characters should be quoted. [% INSERT misc/legalese.txt %] [% INSERT 'dos98/Program Files/stupid' %] To evaluate a variable to specify a filename, you should explicitly prefix it with a C<$> or use double-quoted string interpolation. [% language = 'en' legalese = 'misc/legalese.txt' %] [% INSERT $legalese %] # misc/legalese.txt [% INSERT "$language/$legalese" %] # en/misc/legalese.txt Multiple files can be specified using C<+> as a delimiter. All files should be unquoted names or quoted strings. Any variables should be interpolated into double-quoted strings. [% INSERT legalese.txt + warning.txt %] [% INSERT "$legalese" + warning.txt %] # requires quoting =head2 INCLUDE The C<INCLUDE> directive is used to process and include the output of another template file or block. [% INCLUDE header %] If a C<BLOCK> of the specified name is defined in the same file, or in a file from which the current template has been called (i.e. a parent template) then it will be used in preference to any file of the same name. [% INCLUDE table %] # uses BLOCK defined below [% BLOCK table %] <table> ... </table> [% END %] If a C<BLOCK> definition is not currently visible then the template name should be a file relative to one of the C<INCLUDE_PATH> directories, or an absolute or relative file name if the C<ABSOLUTE>/C<RELATIVE> options are appropriately enabled. The C<INCLUDE> directive automatically quotes the filename specified, as per C<INSERT> described above. When a variable contains the name of the template for the C<INCLUDE> directive, it should be explicitly prefixed by C<$> or double-quoted [% myheader = 'my/misc/header' %] [% INCLUDE myheader %] # 'myheader' [% INCLUDE $myheader %] # 'my/misc/header' [% INCLUDE "$myheader" %] # 'my/misc/header' Any template directives embedded within the file will be processed accordingly. All variables currently defined will be visible and accessible from within the included template. [% title = 'Hello World' %] [% INCLUDE header %] <body> ... F<header>: <html> <title>[% title %]</title> output: <html> <title>Hello World</title> <body> ... Local variable definitions may be specified after the template name, temporarily masking any existing variables. Insignificant whitespace is ignored within directives so you can add variable definitions on the same line, the next line or split across several line with comments interspersed, if you prefer. [% INCLUDE table %] [% INCLUDE table title="Active Projects" %] [% INCLUDE table title = "Active Projects" bgcolor = "#80ff00" # chartreuse border = 2 %] The C<INCLUDE> directive localises (i.e. copies) all variables before processing the template. Any changes made within the included template will not affect variables in the including template. [% foo = 10 %] foo is originally [% foo %] [% INCLUDE bar %] foo is still [% foo %] [% BLOCK bar %] foo was [% foo %] [% foo = 20 %] foo is now [% foo %] [% END %] output: foo is originally 10 foo was 10 foo is now 20 foo is still 10 Technical Note: the localisation of the stash (that is, the process by which variables are copied before an C<INCLUDE> to prevent being overwritten) is only skin deep. The top-level variable namespace (hash) is copied, but no attempt is made to perform a deep-copy of other structures (hashes, arrays, objects, etc.) Therefore, a C<foo> variable referencing a hash will be copied to create a new C<foo> variable but which points to the same hash array. Thus, if you update compound variables (e.g. C<foo.bar>) then you will change the original copy, regardless of any stash localisation. If you're not worried about preserving variable values, or you trust the templates you're including then you might prefer to use the C<PROCESS> directive which is faster by virtue of not performing any localisation. You can specify dotted variables as "local" variables to an C<INCLUDE> directive. However, be aware that because of the localisation issues explained above (if you skipped the previous Technical Note above then you might want to go back and read it or skip this section too), the variables might not actually be "local". If the first element of the variable name already references a hash array then the variable update will affect the original variable. [% foo = { bar = 'Baz' } %] [% INCLUDE somefile foo.bar='Boz' %] [% foo.bar %] # Boz This behaviour can be a little unpredictable (and may well be improved upon in a future version). If you know what you're doing with it and you're sure that the variables in question are defined (nor not) as you expect them to be, then you can rely on this feature to implement some powerful "global" data sharing techniques. Otherwise, you might prefer to steer well clear and always pass simple (undotted) variables as parameters to C<INCLUDE> and other similar directives. If you want to process several templates in one go then you can specify each of their names (quoted or unquoted names only, no unquoted C<$variables>) joined together by C<+>. The C<INCLUDE> directive will then process them in order. [% INCLUDE html/header + "site/$header" + site/menu title = "My Groovy Web Site" %] The variable stash is localised once and then the templates specified are processed in order, all within that same variable context. This makes it slightly faster than specifying several separate C<INCLUDE> directives (because you only clone the variable stash once instead of n times), but not quite as "safe" because any variable changes in the first file will be visible in the second, third and so on. This might be what you want, of course, but then again, it might not. =head2 PROCESS The PROCESS directive is similar to C<INCLUDE> but does not perform any localisation of variables before processing the template. Any changes made to variables within the included template will be visible in the including template. [% foo = 10 %] foo is [% foo %] [% PROCESS bar %] foo is [% foo %] [% BLOCK bar %] [% foo = 20 %] changed foo to [% foo %] [% END %] output: foo is 10 changed foo to 20 foo is 20 Parameters may be specified in the C<PROCESS> directive, but these too will become visible changes to current variable values. [% foo = 10 %] foo is [% foo %] [% PROCESS bar foo = 20 %] foo is [% foo %] [% BLOCK bar %] this is bar, foo is [% foo %] [% END %] output: foo is 10 this is bar, foo is 20 foo is 20 The C<PROCESS> directive is slightly faster than C<INCLUDE> because it avoids the need to localise (i.e. copy) the variable stash before processing the template. As with C<INSERT> and C<INCLUDE>, the first parameter does not need to be quoted as long as it contains only alphanumeric characters, underscores, periods or forward slashes. A C<$> prefix can be used to explicitly indicate a variable which should be interpolated to provide the template name: [% myheader = 'my/misc/header' %] [% PROCESS myheader %] # 'myheader' [% PROCESS $myheader %] # 'my/misc/header' As with C<INCLUDE>, multiple templates can be specified, delimited by C<+>, and are processed in order. [% PROCESS html/header + my/header %] =head2 WRAPPER It's not unusual to find yourself adding common headers and footers to pages or sub-sections within a page. Something like this: [% INCLUDE section/header title = 'Quantum Mechanics' %] Quantum mechanics is a very interesting subject wish should prove easy for the layman to fully comprehend. [% INCLUDE section/footer %] [% INCLUDE section/header title = 'Desktop Nuclear Fusion for under $50' %] This describes a simple device which generates significant sustainable electrical power from common tap water by process of nuclear fusion. [% INCLUDE section/footer %] The individual template components being included might look like these: section/header: <p> <h2>[% title %]</h2> section/footer: </p> The C<WRAPPER> directive provides a way of simplifying this a little. It encloses a block up to a matching C<END> directive, which is first processed to generate some output. This is then passed to the named template file or C<BLOCK> as the C<content> variable. [% WRAPPER section title = 'Quantum Mechanics' %] Quantum mechanics is a very interesting subject wish should prove easy for the layman to fully comprehend. [% END %] [% WRAPPER section title = 'Desktop Nuclear Fusion for under $50' %] This describes a simple device which generates significant sustainable electrical power from common tap water by process of nuclear fusion. [% END %] The single 'section' template can then be defined as: <h2>[% title %]</h2> <p> [% content %] </p> Like other block directives, it can be used in side-effect notation: [% INSERT legalese.txt WRAPPER big_bold_table %] It's also possible to specify multiple templates to a C<WRAPPER> directive. The specification order indicates outermost to innermost wrapper templates. For example, given the following template block definitions: [% BLOCK bold %]<b>[% content %]</b>[% END %] [% BLOCK italic %]<i>[% content %]</i>[% END %] the directive [% WRAPPER bold+italic %]Hello World[% END %] would generate the following output: <b><i>Hello World</i></b> =head2 BLOCK The C<BLOCK>...C<END> construct can be used to define template component blocks which can be processed with the C<INCLUDE>, C<PROCESS> and C<WRAPPER> directives. [% BLOCK tabrow %] <tr> <td>[% name %]<td> <td>[% email %]</td> </tr> [% END %] <table> [% PROCESS tabrow name='Fred' email='fred@nowhere.com' %] [% PROCESS tabrow name='Alan' email='alan@nowhere.com' %] </table> A C<BLOCK> definition can be used before it is defined, as long as the definition resides in the same file. The block definition itself does not generate any output. [% PROCESS tmpblk %] [% BLOCK tmpblk %] This is OK [% END %] You can use an anonymous C<BLOCK> to capture the output of a template fragment. [% julius = BLOCK %] And Caesar's spirit, ranging for revenge, With Ate by his side come hot from hell, Shall in these confines with a monarch's voice Cry 'Havoc', and let slip the dogs of war; That this foul deed shall smell above the earth With carrion men, groaning for burial. [% END %] Like a named block, it can contain any other template directives which are processed when the block is defined. The output generated by the block is then assigned to the variable C<julius>. Anonymous C<BLOCK>s can also be used to define block macros. The enclosing block is processed each time the macro is called. [% MACRO locate BLOCK %] The [% animal %] sat on the [% place %]. [% END %] [% locate(animal='cat', place='mat') %] # The cat sat on the mat [% locate(animal='dog', place='log') %] # The dog sat on the log =head1 Conditional Processing =head2 IF / UNLESS / ELSIF / ELSE The C<IF> and C<UNLESS> directives can be used to process or ignore a block based on some run-time condition. [% IF frames %] [% INCLUDE frameset %] [% END %] [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %] Multiple conditions may be joined with C<ELSIF> and/or C<ELSE> blocks. [% IF age < 10 %] Hello [% name %], does your mother know you're using her AOL account? [% ELSIF age < 18 %] Sorry, you're not old enough to enter (and too dumb to lie about your age) [% ELSE %] Welcome [% name %]. [% END %] The following conditional and boolean operators may be used: == != < <= > >= && || ! and or not Conditions may be arbitrarily complex and are evaluated with the same precedence as in Perl. Parenthesis may be used to explicitly determine evaluation order. # ridiculously contrived complex example [% IF (name == 'admin' || uid <= 0) && mode == 'debug' %] I'm confused. [% ELSIF more > less %] That's more or less correct. [% END %] The C<and>, C<or> and C<not> operator are provided as aliases for C<&&>, C<||> and C<!>, respectively. Unlike Perl, which treats C<and>, C<or> and C<not> as separate, lower-precedence versions of the other operators, the Template Toolkit performs a straightforward substitution of C<and> for C<&&>, and so on. That means that C<and>, C<or> and C<not> have the same operator precedence as C<&&>, C<||> and C<!>. =head2 SWITCH / CASE The C<SWITCH> / C<CASE> construct can be used to perform a multi-way conditional test. The C<SWITCH> directive expects an expression which is first evaluated and then compared against each CASE statement in turn. Each C<CASE> directive should contain a single value or a list of values which should match. C<CASE> may also be left blank or written as C<[% CASE DEFAULT %]> to specify a default match. Only one C<CASE> matches, there is no drop-through between C<CASE> statements. [% SWITCH myvar %] [% CASE 'value1' %] ... [% CASE ['value2', 'value3'] %] # multiple values ... [% CASE myhash.keys %] # ditto ... [% CASE %] # default ... [% END %] =head1 Loop Processing =head2 FOREACH The C<FOREACH> directive will iterate through the items in a list, processing the enclosed block for each one. [% foo = 'Foo' items = [ 'one', 'two', 'three' ] %] Things: [% FOREACH thing IN [ foo 'Bar' "$foo Baz" ] %] * [% thing %] [% END %] Items: [% FOREACH i IN items %] * [% i %] [% END %] Stuff: [% stuff = [ foo "$foo Bar" ] %] [% FOREACH s IN stuff %] * [% s %] [% END %] output: Things: * Foo * Bar * Foo Baz Items: * one * two * three Stuff: * Foo * Foo Bar You can use also use C<=> instead of C<IN> if you prefer. [% FOREACH i = items %] When the C<FOREACH> directive is used without specifying a target variable, any iterated values which are hash references will be automatically imported. [% userlist = [ { id => 'tom', name => 'Thomas' }, { id => 'dick', name => 'Richard' }, { id => 'larry', name => 'Lawrence' }, ] %] [% FOREACH user IN userlist %] [% user.id %] [% user.name %] [% END %] short form: [% FOREACH userlist %] [% id %] [% name %] [% END %] Note that this particular usage creates a localised variable context to prevent the imported hash keys from overwriting any existing variables. The imported definitions and any other variables defined in such a C<FOREACH> loop will be lost at the end of the loop, when the previous context and variable values are restored. However, under normal operation, the loop variable remains in scope after the C<FOREACH> loop has ended (caveat: overwriting any variable previously in scope). This is useful as the loop variable is secretly an iterator object (see below) and can be used to analyse the last entry processed by the loop. The C<FOREACH> directive can also be used to iterate through the entries in a hash array. Each entry in the hash is returned in sorted order (based on the key) as a hash array containing 'key' and 'value' items. [% users = { tom => 'Thomas', dick => 'Richard', larry => 'Lawrence', } %] [% FOREACH u IN users %] * [% u.key %] : [% u.value %] [% END %] Output: * dick : Richard * larry : Lawrence * tom : Thomas The C<NEXT> directive starts the next iteration in the C<FOREACH> loop. [% FOREACH user IN userlist %] [% NEXT IF user.isguest %] Name: [% user.name %] Email: [% user.email %] [% END %] The C<LAST> directive can be used to prematurely exit the loop. C<BREAK> is also provided as an alias for C<LAST>. [% FOREACH match IN results.nsort('score').reverse %] [% LAST IF match.score < 50 %] [% match.score %] : [% match.url %] [% END %] The C<FOREACH> directive is implemented using the L<Template::Iterator> module. A reference to the iterator object for a C<FOREACH> directive is implicitly available in the C<loop> variable. The following methods can be called on the C<loop> iterator. size() number of elements in the list max() index number of last element (size - 1) index() index of current iteration from 0 to max() count() iteration counter from 1 to size() (i.e. index() + 1) first() true if the current iteration is the first last() true if the current iteration is the last prev() return the previous item in the list next() return the next item in the list See L<Template::Iterator> for further details. Example: [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%] [%- "<ul>\n" IF loop.first %] <li>[% loop.count %]/[% loop.size %]: [% item %] [%- "</ul>\n" IF loop.last %] [% END %] Output: <ul> <li>1/3: foo <li>2/3: bar <li>3/3: baz </ul> Nested loops will work as expected, with the C<loop> variable correctly referencing the innermost loop and being restored to any previous value (i.e. an outer loop) at the end of the loop. [% FOREACH group IN grouplist; # loop => group iterator "Groups:\n" IF loop.first; FOREACH user IN group.userlist; # loop => user iterator "$loop.count: $user.name\n"; END; # loop => group iterator "End of Groups\n" IF loop.last; END %] The C<iterator> plugin can also be used to explicitly create an iterator object. This can be useful within nested loops where you need to keep a reference to the outer iterator within the inner loop. The iterator plugin effectively allows you to create an iterator by a name other than C<loop>. See L<Template::Plugin::Iterator> for further details. [% USE giter = iterator(grouplist) %] [% FOREACH group IN giter %] [% FOREACH user IN group.userlist %] user #[% loop.count %] in group [% giter.count %] is named [% user.name %] [% END %] [% END %] =head2 WHILE The C<WHILE> directive can be used to repeatedly process a template block while a conditional expression evaluates true. The expression may be arbitrarily complex as per C<IF> / C<UNLESS>. [% WHILE total < 100 %] ... [% total = calculate_new_total %] [% END %] An assignment can be enclosed in parenthesis to evaluate the assigned value. [% WHILE (user = get_next_user_record) %] [% user.name %] [% END %] The C<NEXT> directive can be used to start the next iteration of a C<WHILE> loop and C<BREAK> can be used to exit the loop, both as per C<FOREACH>. The Template Toolkit uses a failsafe counter to prevent runaway C<WHILE> loops which would otherwise never terminate. If the loop exceeds 1000 iterations then an C<undef> exception will be thrown, reporting the error: WHILE loop terminated (> 1000 iterations) The C<$Template::Directive::WHILE_MAX> variable controls this behaviour and can be set to a higher value if necessary. =head1 Filters, Plugins, Macros and Perl =head2 FILTER The C<FILTER> directive can be used to post-process the output of a block. A number of standard filters are provided with the Template Toolkit. The C<html> filter, for example, escapes the 'E<lt>', 'E<gt>' and '&' characters to prevent them from being interpreted as HTML tags or entity reference markers. [% FILTER html %] HTML text may have < and > characters embedded which you want converted to the correct HTML entities. [% END %] output: HTML text may have < and > characters embedded which you want converted to the correct HTML entities. The C<FILTER> directive can also follow various other non-block directives. For example: [% INCLUDE mytext FILTER html %] The C<|> character can also be used as an alias for C<FILTER>. [% INCLUDE mytext | html %] Multiple filters can be chained together and will be called in sequence. [% INCLUDE mytext FILTER html FILTER html_para %] or [% INCLUDE mytext | html | html_para %] Filters come in two flavours, known as 'static' or 'dynamic'. A static filter is a simple subroutine which accepts a text string as the only argument and returns the modified text. The C<html> filter is an example of a static filter, implemented as: sub html_filter { my $text = shift; for ($text) { s/&/&/g; s/</</g; s/>/>/g; } return $text; } Dynamic filters can accept arguments which are specified when the filter is called from a template. The C<repeat> filter is such an example, accepting a numerical argument which specifies the number of times that the input text should be repeated. [% FILTER repeat(3) %]blah [% END %] output: blah blah blah These are implemented as filter 'factories'. The factory subroutine is passed a reference to the current L<Template::Context> object along with any additional arguments specified. It should then return a subroutine reference (e.g. a closure) which implements the filter. The C<repeat> filter factory is implemented like this: sub repeat_filter_factory { my ($context, $iter) = @_; $iter = 1 unless defined $iter; return sub { my $text = shift; $text = '' unless defined $text; return join('\n', $text) x $iter; } } The C<FILTERS> option, described in L<Template::Manual::Config>, allows custom filters to be defined when a Template object is instantiated. The L<define_filter()|Template::Context#define_filter()> method allows further filters to be defined at any time. When using a filter, it is possible to assign an alias to it for further use. This is most useful for dynamic filters that you want to re-use with the same configuration. [% FILTER echo = repeat(2) %] Is there anybody out there? [% END %] [% FILTER echo %] Mother, should I build a wall? [% END %] Output: Is there anybody out there? Is there anybody out there? Mother, should I build a wall? Mother, should I build a wall? The C<FILTER> directive automatically quotes the name of the filter. As with C<INCLUDE> et al, you can use a variable to provide the name of the filter, prefixed by C<$>. [% myfilter = 'html' %] [% FILTER $myfilter %] # same as [% FILTER html %] ... [% END %] A template variable can also be used to define a static filter subroutine. However, the Template Toolkit will automatically call any subroutine bound to a variable and use the value returned. Thus, the above example could be implemented as: my $vars = { myfilter => sub { return 'html' }, }; template: [% FILTER $myfilter %] # same as [% FILTER html %] ... [% END %] To define a template variable that evaluates to a subroutine reference that can be used by the C<FILTER> directive, you should create a subroutine that, when called automatically by the Template Toolkit, returns another subroutine reference which can then be used to perform the filter operation. Note that only static filters can be implemented in this way. my $vars = { myfilter => sub { \&my_filter_sub }, }; sub my_filter_sub { my $text = shift; # do something return $text; } template: [% FILTER $myfilter %] ... [% END %] Alternately, you can bless a subroutine reference into a class (any class will do) to fool the Template Toolkit into thinking it's an object rather than a subroutine. This will then bypass the automatic "call-a-subroutine-to-return-a-value" magic. my $vars = { myfilter => bless(\&my_filter_sub, 'anything_you_like'), }; template: [% FILTER $myfilter %] ... [% END %] Filters bound to template variables remain local to the variable context in which they are defined. That is, if you define a filter in a C<PERL> block within a template that is loaded via C<INCLUDE>, then the filter definition will only exist until the end of that template when the stash is delocalised, restoring the previous variable state. If you want to define a filter which persists for the lifetime of the processor, or define additional dynamic filter factories, then you can call the L<define_filter()|Template::Context#define_filter()> method on the current L<Template::Context> object. See L<Template::Manual::Filters> for a complete list of available filters, their descriptions and examples of use. =head2 USE The C<USE> directive can be used to load and initialise "plugin" extension modules. [% USE myplugin %] A plugin is a regular Perl module that conforms to a particular object-oriented interface, allowing it to be loaded into and used automatically by the Template Toolkit. For details of this interface and information on writing plugins, consult L<Template::Plugin>. A number of standard plugins are included with the Template Toolkit (see below and L<Template::Manual::Plugins>). The names of these standard plugins are case insensitive. [% USE CGI %] # => Template::Plugin::CGI [% USE Cgi %] # => Template::Plugin::CGI [% USE cgi %] # => Template::Plugin::CGI You can also define further plugins using the C<PLUGINS> option. my $tt = Template->new({ PLUGINS => { foo => 'My::Plugin::Foo', bar => 'My::Plugin::Bar', }, }); The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified. [% USE Foo %] # look for 'Foo' then 'foo' If you define all your C<PLUGINS> with lower case names then they will be located regardless of how the user specifies the name in the C<USE> directive. If, on the other hand, you define your C<PLUGINS> with upper or mixed case names then the name specified in the C<USE> directive must match the case exactly. If the plugin isn't defined in either the standard plugins (C<$Template::Plugins::STD_PLUGINS>) or via the C<PLUGINS> option, then the C<PLUGIN_BASE> is searched. In this case the plugin name I<is> case-sensitive. It is appended to each of the C<PLUGIN_BASE> module namespaces in turn (default: C<Template::Plugin>) to construct a full module name which it attempts to locate and load. Any periods, 'C<.>', in the name will be converted to 'C<::>'. [% USE MyPlugin %] # => Template::Plugin::MyPlugin [% USE Foo.Bar %] # => Template::Plugin::Foo::Bar The C<LOAD_PERL> option (disabled by default) provides a further way by which external Perl modules may be loaded. If a regular Perl module (i.e. not a C<Template::Plugin::*> or other module relative to some C<PLUGIN_BASE>) supports an object-oriented interface and a C<new()> constructor then it can be loaded and instantiated automatically. The following trivial example shows how the IO::File module might be used. [% USE file = IO.File('/tmp/mydata') %] [% WHILE (line = file.getline) %] <!-- [% line %] --> [% END %] Any additional parameters supplied in parenthesis after the plugin name will be also be passed to the C<new()> constructor. A reference to the current L<Template::Context> object is passed as the first parameter. [% USE MyPlugin('foo', 123) %] equivalent to: Template::Plugin::MyPlugin->new($context, 'foo', 123); The only exception to this is when a module is loaded via the C<LOAD_PERL> option. In this case the C<$context> reference is I<not> passed to the C<new()> constructor. This is based on the assumption that the module is a regular Perl module rather than a Template Toolkit plugin so isn't expecting a context reference and wouldn't know what to do with it anyway. Named parameters may also be specified. These are collated into a hash which is passed by reference as the last parameter to the constructor, as per the general code calling interface. [% USE url('/cgi-bin/foo', mode='submit', debug=1) %] equivalent to: Template::Plugin::URL->new( $context, '/cgi-bin/foo' { mode => 'submit', debug => 1 } ); The plugin may represent any data type; a simple variable, hash, list or code reference, but in the general case it will be an object reference. Methods can be called on the object (or the relevant members of the specific data type) in the usual way: [% USE table(mydata, rows=3) %] [% FOREACH row IN table.rows %] <tr> [% FOREACH item IN row %] <td>[% item %]</td> [% END %] </tr> [% END %] An alternative name may be provided for the plugin by which it can be referenced: [% USE scores = table(myscores, cols=5) %] [% FOREACH row IN scores.rows %] ... [% END %] You can use this approach to create multiple plugin objects with different configurations. This example shows how the L<format|Template::Plugin::Format> plugin is used to create sub-routines bound to variables for formatting text as per C<printf()>. [% USE bold = format('<b>%s</b>') %] [% USE ital = format('<i>%s</i>') %] [% bold('This is bold') %] [% ital('This is italic') %] Output: <b>This is bold</b> <i>This is italic</i> This next example shows how the L<URL|Template::Plugin::URL> plugin can be used to build dynamic URLs from a base part and optional query parameters. [% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %] <a href="[% mycgi %]">... <a href="[% mycgi(mode='submit') %]"... Output: <a href="/cgi-bin/foo.pl?debug=1">... <a href="/cgi-bin/foo.pl?mode=submit&debug=1">... The L<CGI|Template::Plugin::CGI> plugin is an example of one which delegates to another Perl module. In this case, to Lincoln Stein's C<CGI> module. All of the methods provided by the C<CGI> module are available via the plugin. [% USE CGI; CGI.start_form; CGI.checkbox_group( name = 'colours', values = [ 'red' 'green' 'blue' ] ); CGI.popup_menu( name = 'items', values = [ 'foo' 'bar' 'baz' ] ); CGI.end_form %] See L<Template::Manual::Plugins> for more information on the plugins distributed with the toolkit or available from CPAN. =head2 MACRO The C<MACRO> directive allows you to define a directive or directive block which is then evaluated each time the macro is called. [% MACRO header INCLUDE header %] Calling the macro as: [% header %] is then equivalent to: [% INCLUDE header %] Macros can be passed named parameters when called. These values remain local to the macro. [% header(title='Hello World') %] equivalent to: [% INCLUDE header title='Hello World' %] A C<MACRO> definition may include parameter names. Values passed to the macros are then mapped to these local variables. Other named parameters may follow these. [% MACRO header(title) INCLUDE header %] [% header('Hello World') %] [% header('Hello World', bgcol='#123456') %] equivalent to: [% INCLUDE header title='Hello World' %] [% INCLUDE header title='Hello World' bgcol='#123456' %] Here's another example, defining a macro for display numbers in comma-delimited groups of 3, using the chunk and join virtual method. [% MACRO number(n) GET n.chunk(-3).join(',') %] [% number(1234567) %] # 1,234,567 A C<MACRO> may precede any directive and must conform to the structure of the directive. [% MACRO header IF frames %] [% INCLUDE frames/header %] [% ELSE %] [% INCLUDE header %] [% END %] [% header %] A C<MACRO> may also be defined as an anonymous C<BLOCK>. The block will be evaluated each time the macro is called. [% MACRO header BLOCK %] ...content... [% END %] [% header %] If you've got the C<EVAL_PERL> option set, then you can even define a C<MACRO> as a C<PERL> block (see below): [% MACRO triple(n) PERL %] my $n = $stash->get('n'); print $n * 3; [% END -%] =head2 PERL (for the advanced reader) The C<PERL> directive is used to mark the start of a block which contains Perl code for evaluation. The C<EVAL_PERL> option must be enabled for Perl code to be evaluated or a C<perl> exception will be thrown with the message 'C<EVAL_PERL not set>'. Perl code is evaluated in the C<Template::Perl> package. The C<$context> package variable contains a reference to the current L<Template::Context> object. This can be used to access the functionality of the Template Toolkit to process other templates, load plugins, filters, etc. See L<Template::Context> for further details. [% PERL %] print $context->include('myfile'); [% END %] The L<$stash> variable contains a reference to the top-level stash object which manages template variables. Through this, variable values can be retrieved and updated. See L<Template::Stash> for further details. [% PERL %] $stash->set(foo => 'bar'); print "foo value: ", $stash->get('foo'); [% END %] Output: foo value: bar Output is generated from the C<PERL> block by calling C<print()>. Note that the C<Template::Perl::PERLOUT> handle is selected (tied to an output buffer) instead of C<STDOUT>. [% PERL %] print "foo\n"; # OK print PERLOUT "bar\n"; # OK, same as above print Template::Perl::PERLOUT "baz\n"; # OK, same as above print STDOUT "qux\n"; # WRONG! [% END %] The C<PERL> block may contain other template directives. These are processed before the Perl code is evaluated. [% name = 'Fred Smith' %] [% PERL %] print "[% name %]\n"; [% END %] Thus, the Perl code in the above example is evaluated as: print "Fred Smith\n"; Exceptions may be thrown from within C<PERL> blocks using C<die()>. They will be correctly caught by enclosing C<TRY> blocks. [% TRY %] [% PERL %] die "nothing to live for\n"; [% END %] [% CATCH %] error: [% error.info %] [% END %] output: error: nothing to live for =head2 RAWPERL (for the very advanced reader) The Template Toolkit parser reads a source template and generates the text of a Perl subroutine as output. It then uses C<eval()> to evaluate it into a subroutine reference. This subroutine is then called to process the template, passing a reference to the current L<Template::Context> object through which the functionality of the Template Toolkit can be accessed. The subroutine reference can be cached, allowing the template to be processed repeatedly without requiring any further parsing. For example, a template such as: [% PROCESS header %] The [% animal %] sat on the [% location %] [% PROCESS footer %] is converted into the following Perl subroutine definition: sub { my $context = shift; my $stash = $context->stash; my $output = ''; my $error; eval { BLOCK: { $output .= $context->process('header'); $output .= "The "; $output .= $stash->get('animal'); $output .= " sat on the "; $output .= $stash->get('location'); $output .= $context->process('footer'); $output .= "\n"; } }; if ($@) { $error = $context->catch($@, \$output); die $error unless $error->type eq 'return'; } return $output; } To examine the Perl code generated, such as in the above example, set the C<$Template::Parser::DEBUG> package variable to any true value. You can also set the C<$Template::Directive::PRETTY> variable true to have the code formatted in a readable manner for human consumption. The source code for each generated template subroutine will be printed to C<STDERR> on compilation (i.e. the first time a template is used). $Template::Parser::DEBUG = 1; $Template::Directive::PRETTY = 1; $template->process($file, $vars) || die $template->error(), "\n"; The C<PERL> ... C<END> construct allows Perl code to be embedded into a template when the C<EVAL_PERL> option is set. It is evaluated at "runtime" using C<eval()> each time the template subroutine is called. This is inherently flexible, but not as efficient as it could be, especially in a persistent server environment where a template may be processed many times. The C<RAWPERL> directive allows you to write Perl code that is integrated directly into the generated Perl subroutine text. It is evaluated once at compile time and is stored in cached form as part of the compiled template subroutine. This makes C<RAWPERL> blocks more efficient than C<PERL> blocks. The downside is that you must code much closer to the metal. For example, in a C<PERL> block you can call L<print()> to generate some output. C<RAWPERL> blocks don't afford such luxury. The code is inserted directly into the generated subroutine text and should conform to the convention of appending to the C<$output> variable. [% PROCESS header %] [% RAWPERL %] $output .= "Some output\n"; ... $output .= "Some more output\n"; [% END %] The critical section of the generated subroutine for this example would then look something like: ... eval { BLOCK: { $output .= $context->process('header'); $output .= "\n"; $output .= "Some output\n"; ... $output .= "Some more output\n"; $output .= "\n"; } }; ... As with C<PERL> blocks, the L<$context|Template::Context> and L<$stash|Template::Stash> references are pre-defined and available for use within C<RAWPERL> code. =head1 Exception Handling and Flow Control =head2 TRY / THROW / CATCH / FINAL (more advanced material) The Template Toolkit supports fully functional, nested exception handling. The C<TRY> directive introduces an exception handling scope which continues until the matching C<END> directive. Any errors that occur within that block will be caught and can be handled by one of the C<CATCH> blocks defined. [% TRY %] ...blah...blah... [% CALL somecode %] ...etc... [% INCLUDE someblock %] ...and so on... [% CATCH %] An error occurred! [% END %] Errors are raised as exceptions (objects of the L<Template::Exception> class) which contain two fields: C<type> and C<info>. The exception C<type> is used to indicate the kind of error that occurred. It is a simple text string which can contain letters, numbers, 'C<_>' or 'C<.>'. The C<info> field contains an error message indicating what actually went wrong. Within a catch block, the exception object is aliased to the C<error> variable. You can access the C<type> and C<info> fields directly. [% mydsn = 'dbi:MySQL:foobar' %] ... [% TRY %] [% USE DBI(mydsn) %] [% CATCH %] ERROR! Type: [% error.type %] Info: [% error.info %] [% END %] output (assuming a non-existent database called 'C<foobar>'): ERROR! Type: DBI Info: Unknown database "foobar" The C<error> variable can also be specified by itself and will return a string of the form "C<$type error - $info>". ... [% CATCH %] ERROR: [% error %] [% END %] Output: ERROR: DBI error - Unknown database "foobar" Each C<CATCH> block may be specified with a particular exception type denoting the kind of error that it should catch. Multiple C<CATCH> blocks can be provided to handle different types of exception that may be thrown in the C<TRY> block. A C<CATCH> block specified without any type, as in the previous example, is a default handler which will catch any otherwise uncaught exceptions. This can also be specified as C<[% CATCH DEFAULT %]>. [% TRY %] [% INCLUDE myfile %] [% USE DBI(mydsn) %] [% CALL somecode %] [% CATCH file %] File Error! [% error.info %] [% CATCH DBI %] [% INCLUDE database/error.html %] [% CATCH %] [% error %] [% END %] Remember that you can specify multiple directives within a single tag, each delimited by 'C<;>'. So the above example can be written more concisely as: [% TRY; INCLUDE myfile; USE DBI(mydsn); CALL somecode; CATCH file; "File Error! $error.info"; CATCH DBI; INCLUDE database/error.html; CATCH; error; END %] The C<DBI> plugin throws exceptions of the C<DBI> type (in case that wasn't already obvious). The other specific exception caught here is of the C<file> type. A C<file> exception is automatically thrown by the Template Toolkit when it can't find a file, or fails to load, parse or process a file that has been requested by an C<INCLUDE>, C<PROCESS>, C<INSERT> or C<WRAPPER> directive. If C<myfile> can't be found in the example above, the C<[% INCLUDE myfile %]> directive will raise a C<file> exception which is then caught by the C<[% CATCH file %]> block. The output generated would be: File Error! myfile: not found Note that the C<DEFAULT> option (disabled by default) allows you to specify a default file to be used any time a template file can't be found. This will prevent file exceptions from ever being raised when a non-existent file is requested (unless, of course, the C<DEFAULT> file your specify doesn't exist). Errors encountered once the file has been found (i.e. read error, parse error) will be raised as file exceptions as per usual. Uncaught exceptions (i.e. if the C<TRY> block doesn't have a type specific or default C<CATCH> handler) may be caught by enclosing C<TRY> blocks which can be nested indefinitely across multiple templates. If the error isn't caught at any level then processing will stop and the Template L<process()|Template#process()> method will return a false value to the caller. The relevant L<Template::Exception> object can be retrieved by calling the L<error()|Template#error()> method. [% TRY %] ... [% TRY %] [% INCLUDE $user.header %] [% CATCH file %] [% INCLUDE header %] [% END %] ... [% CATCH DBI %] [% INCLUDE database/error.html %] [% END %] In this example, the inner C<TRY> block is used to ensure that the first C<INCLUDE> directive works as expected. We're using a variable to provide the name of the template we want to include, C<user.header>, and it's possible this contains the name of a non-existent template, or perhaps one containing invalid template directives. If the C<INCLUDE> fails with a C<file> error then we C<CATCH> it in the inner block and C<INCLUDE> the default C<header> file instead. Any C<DBI> errors that occur within the scope of the outer C<TRY> block will be caught in the relevant C<CATCH> block, causing the C<database/error.html> template to be processed. Note that included templates inherit all currently defined template variable so these error files can quite happily access the <error> variable to retrieve information about the currently caught exception. For example, the C<database/error.html> template might look like this: <h2>Database Error</h2> A database error has occurred: [% error.info %] You can also specify a C<FINAL> block. This is always processed regardless of the outcome of the C<TRY> and/or C<CATCH> blocks. If an exception is uncaught then the C<FINAL> block is processed before jumping to the enclosing block or returning to the caller. [% TRY %] ... [% CATCH this %] ... [% CATCH that %] ... [% FINAL %] All done! [% END %] The output from the C<TRY> block is left intact up to the point where an exception occurs. For example, this template: [% TRY %] This gets printed [% THROW food 'carrots' %] This doesn't [% CATCH food %] culinary delights: [% error.info %] [% END %] generates the following output: This gets printed culinary delights: carrots The C<CLEAR> directive can be used in a C<CATCH> or C<FINAL> block to clear any output created in the C<TRY> block. [% TRY %] This gets printed [% THROW food 'carrots' %] This doesn't [% CATCH food %] [% CLEAR %] culinary delights: [% error.info %] [% END %] Output: culinary delights: carrots Exception types are hierarchical, with each level being separated by the familiar dot operator. A C<DBI.connect> exception is a more specific kind of C<DBI> error. Similarly, an C<example.error.barf> is a more specific kind of C<example.error> type which itself is also a C<example> error. A C<CATCH> handler that specifies a general exception type (such as C<DBI> or C<example.error>) will also catch more specific types that have the same prefix as long as a more specific handler isn't defined. Note that the order in which C<CATCH> handlers are defined is irrelevant; a more specific handler will always catch an exception in preference to a more generic or default one. [% TRY %] ... [% CATCH DBI ; INCLUDE database/error.html ; CATCH DBI.connect ; INCLUDE database/connect.html ; CATCH ; INCLUDE error.html ; END %] In this example, a C<DBI.connect> error has it's own handler, a more general C<DBI> block is used for all other C<DBI> or C<DBI.*> errors and a default handler catches everything else. Exceptions can be raised in a template using the C<THROW> directive. The first parameter is the exception type which doesn't need to be quoted (but can be, it's the same as C<INCLUDE>) followed by the relevant error message which can be any regular value such as a quoted string, variable, etc. [% THROW food "Missing ingredients: $recipe.error" %] [% THROW user.login 'no user id: please login' %] [% THROW $myerror.type "My Error: $myerror.info" %] It's also possible to specify additional positional or named parameters to the C<THROW> directive if you want to pass more than just a simple message back as the error info field. [% THROW food 'eggs' 'flour' msg='Missing Ingredients' %] In this case, the error C<info> field will be a hash array containing the named arguments and an C<args> item which contains a list of the positional arguments. type => 'food', info => { msg => 'Missing Ingredients', args => ['eggs', 'flour'], } In addition to specifying individual positional arguments as C<[% error.info.args.n %]>, the C<info> hash contains keys directly pointing to the positional arguments, as a convenient shortcut. [% error.info.0 %] # same as [% error.info.args.0 %] Exceptions can also be thrown from Perl code which you've bound to template variables, or defined as a plugin or other extension. To raise an exception, call C<die()> passing a reference to a L<Template::Exception> object as the argument. This will then be caught by any enclosing C<TRY> blocks from where the code was called. use Template::Exception; ... my $vars = { foo => sub { # ... do something ... die Template::Exception->new('myerr.naughty', 'Bad, bad error'); }, }; Template: [% TRY %] [% foo %] [% CATCH myerr ; "Error: $error" ; END %] Output: Error: myerr.naughty error - Bad, bad error The C<info> field can also be a reference to another object or data structure, if required. die Template::Exception->new('myerror', { module => 'foo.pl', errors => [ 'bad permissions', 'naughty boy' ], }); Later, in a template: [% TRY %] ... [% CATCH myerror %] [% error.info.errors.size or 'no'; error.info.errors.size == 1 ? ' error' : ' errors' %] in [% error.info.module %]: [% error.info.errors.join(', ') %]. [% END %] Generating the output: 2 errors in foo.pl: bad permissions, naughty boy. You can also call C<die()> with a single string, as is common in much existing Perl code. This will automatically be converted to an exception of the 'C<undef>' type (that's the literal string 'C<undef>', not the undefined value). If the string isn't terminated with a newline then Perl will append the familiar C<" at $file line $line"> message. sub foo { # ... do something ... die "I'm sorry, Dave, I can't do that\n"; } If you're writing a plugin, or some extension code that has the current L<Template::Context> in scope (you can safely skip this section if this means nothing to you) then you can also raise an exception by calling the context L<throw()|Template::Context#throw()> method. You can pass it an L<Template::Exception> object reference, a pair of C<($type, $info)> parameters or just an C<$info> string to create an exception of 'C<undef>' type. $context->throw($e); # exception object $context->throw('Denied'); # 'undef' type $context->throw('user.passwd', 'Bad Password'); =head2 NEXT The C<NEXT> directive can be used to start the next iteration of a C<FOREACH> or C<WHILE> loop. [% FOREACH user IN users %] [% NEXT IF user.isguest %] Name: [% user.name %] Email: [% user.email %] [% END %] =head2 LAST The C<LAST> directive can be used to prematurely exit a C<FOREACH> or C<WHILE> loop. [% FOREACH user IN users %] Name: [% user.name %] Email: [% user.email %] [% LAST IF some.condition %] [% END %] C<BREAK> can also be used as an alias for C<LAST>. =head2 RETURN The C<RETURN> directive can be used to stop processing the current template and return to the template from which it was called, resuming processing at the point immediately after the C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive. If there is no enclosing template then the Template L<process()|Template#process()> method will return to the calling code with a true value. Before [% INCLUDE half_wit %] After [% BLOCK half_wit %] This is just half... [% RETURN %] ...a complete block [% END %] Output: Before This is just half... After =head2 STOP The C<STOP> directive can be used to indicate that the processor should stop gracefully without processing any more of the template document. This is a planned stop and the Template L<process()|Template#process()> method will return a B<true> value to the caller. This indicates that the template was processed successfully according to the directives within it. [% IF something.terrible.happened %] [% INCLUDE fatal/error.html %] [% STOP %] [% END %] [% TRY %] [% USE DBI(mydsn) %] ... [% CATCH DBI.connect %] <h1>Cannot connect to the database: [% error.info %]</h1> <p> We apologise for the inconvenience. </p> [% INCLUDE footer %] [% STOP %] [% END %] =head2 CLEAR The C<CLEAR> directive can be used to clear the output buffer for the current enclosing block. It is most commonly used to clear the output generated from a C<TRY> block up to the point where the error occurred. [% TRY %] blah blah blah # this is normally left intact [% THROW some 'error' %] # up to the point of error ... [% CATCH %] [% CLEAR %] # clear the TRY output [% error %] # print error string [% END %] =head1 Miscellaneous =head2 META The C<META> directive allows simple metadata items to be defined within a template. These are evaluated when the template is parsed and as such may only contain simple values (e.g. it's not possible to interpolate other variables values into C<META> variables). [% META title = 'The Cat in the Hat' author = 'Dr. Seuss' version = 1.23 %] The C<template> variable contains a reference to the main template being processed. These metadata items may be retrieved as attributes of the template. <h1>[% template.title %]</h1> <h2>[% template.author %]</h2> The C<name> and C<modtime> metadata items are automatically defined for each template to contain its name and modification time in seconds since the epoch. [% USE date %] # use Date plugin to format time ... [% template.name %] last modified at [% date.format(template.modtime) %] The C<PRE_PROCESS> and C<POST_PROCESS> options allow common headers and footers to be added to all templates. The C<template> reference is correctly defined when these templates are processed, allowing headers and footers to reference metadata items from the main template. $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }); $template->process('cat_in_hat'); header: <html> <head> <title>[% template.title %]</title> </head> <body> cat_in_hat: [% META title = 'The Cat in the Hat' author = 'Dr. Seuss' version = 1.23 year = 2000 %] The cat in the hat sat on the mat. footer: <hr> © [% template.year %] [% template.author %] </body> </html> The output generated from the above example is: <html> <head> <title>The Cat in the Hat</title> </head> <body> The cat in the hat sat on the mat. <hr> © 2000 Dr. Seuss </body> </html> =head2 TAGS The C<TAGS> directive can be used to set the C<START_TAG> and C<END_TAG> values on a per-template file basis. [% TAGS <+ +> %] <+ INCLUDE header +> The TAGS directive may also be used to set a named C<TAG_STYLE> [% TAGS html %] <!-- INCLUDE header --> See the L<TAGS|Template::Manual::Config#TAGS> and L<TAG_STYLE|Template::Manual::Config#TAG_STYLE> configuration options for further details. =head2 DEBUG The C<DEBUG> directive can be used to enable or disable directive debug messages within a template. The C<DEBUG> configuration option must be set to include C<DEBUG_DIRS> for the C<DEBUG> directives to have any effect. If C<DEBUG_DIRS> is not set then the parser will automatically ignore and remove any C<DEBUG> directives. The C<DEBUG> directive can be used with an C<on> or C<off> parameter to enable or disable directive debugging messages from that point forward. When enabled, the output of each directive in the generated output will be prefixed by a comment indicate the file, line and original directive text. [% DEBUG on %] directive debugging is on (assuming DEBUG option is set true) [% DEBUG off %] directive debugging is off The C<format> parameter can be used to change the format of the debugging message. [% DEBUG format '<!-- $file line $line : [% $text %] -->' %] =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[B ���a �a lib/Template/Filters.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Filters # # DESCRIPTION # Defines filter plugins as used by the FILTER directive. # # AUTHORS # Andy Wardley <abw@wardley.org>, with a number of filters contributed # by Leslie Michael Orchard <deus_x@nijacode.com> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Filters; use strict; use warnings; use locale; use base 'Template::Base'; use Template::Constants; use Scalar::Util 'blessed'; our $VERSION = '3.100'; our $AVAILABLE = { }; our $TRUNCATE_LENGTH = 32; our $TRUNCATE_ADDON = '...'; #------------------------------------------------------------------------ # standard filters, defined in one of the following forms: # name => \&static_filter # name => [ \&subref, $is_dynamic ] # If the $is_dynamic flag is set then the sub-routine reference # is called to create a new filter each time it is requested; if # not set, then it is a single, static sub-routine which is returned # for every filter request for that name. #------------------------------------------------------------------------ our $FILTERS = { # static filters 'html' => \&html_filter, 'html_para' => \&html_paragraph, 'html_break' => \&html_para_break, 'html_para_break' => \&html_para_break, 'html_line_break' => \&html_line_break, 'xml' => \&xml_filter, 'uri' => \&uri_filter, 'url' => \&url_filter, 'upper' => sub { uc $_[0] }, 'lower' => sub { lc $_[0] }, 'ucfirst' => sub { ucfirst $_[0] }, 'lcfirst' => sub { lcfirst $_[0] }, 'stderr' => sub { print STDERR @_; return '' }, 'trim' => sub { for ($_[0]) { s/^\s+//; s/\s+$// }; $_[0] }, 'null' => sub { return '' }, 'collapse' => sub { for ($_[0]) { s/^\s+//; s/\s+$//; s/\s+/ /g }; $_[0] }, # dynamic filters 'html_entity' => [ \&html_entity_filter_factory, 1 ], 'indent' => [ \&indent_filter_factory, 1 ], 'format' => [ \&format_filter_factory, 1 ], 'truncate' => [ \&truncate_filter_factory, 1 ], 'repeat' => [ \&repeat_filter_factory, 1 ], 'replace' => [ \&replace_filter_factory, 1 ], 'remove' => [ \&remove_filter_factory, 1 ], 'eval' => [ \&eval_filter_factory, 1 ], 'evaltt' => [ \&eval_filter_factory, 1 ], # alias 'perl' => [ \&perl_filter_factory, 1 ], 'evalperl' => [ \&perl_filter_factory, 1 ], # alias 'redirect' => [ \&redirect_filter_factory, 1 ], 'file' => [ \&redirect_filter_factory, 1 ], # alias 'stdout' => [ \&stdout_filter_factory, 1 ], }; # name of module implementing plugin filters our $PLUGIN_FILTER = 'Template::Plugin::Filter'; #======================================================================== # -- PUBLIC METHODS -- #======================================================================== #------------------------------------------------------------------------ # fetch($name, \@args, $context) # # Attempts to instantiate or return a reference to a filter sub-routine # named by the first parameter, $name, with additional constructor # arguments passed by reference to a list as the second parameter, # $args. A reference to the calling Template::Context object is # passed as the third parameter. # # Returns a reference to a filter sub-routine or a pair of values # (undef, STATUS_DECLINED) or ($error, STATUS_ERROR) to decline to # deliver the filter or to indicate an error. #------------------------------------------------------------------------ sub fetch { my ($self, $name, $args, $context) = @_; my ($factory, $is_dynamic, $filter, $error); $self->debug("fetch($name, ", defined $args ? ('[ ', join(', ', @$args), ' ]') : '<no args>', ', ', defined $context ? $context : '<no context>', ')') if $self->{ DEBUG }; # allow $name to be specified as a reference to # a plugin filter object; any other ref is # assumed to be a coderef and hence already a filter; # non-refs are assumed to be regular name lookups if (ref $name) { if (blessed($name) && $name->isa($PLUGIN_FILTER)) { $factory = $name->factory() || return $self->error($name->error()); } else { return $name; } } else { return (undef, Template::Constants::STATUS_DECLINED) unless ($factory = $self->{ FILTERS }->{ $name } || $FILTERS->{ $name }); } # factory can be an [ $code, $dynamic ] or just $code if (ref $factory eq 'ARRAY') { ($factory, $is_dynamic) = @$factory; } else { $is_dynamic = 0; } if (ref $factory eq 'CODE') { if ($is_dynamic) { # if the dynamic flag is set then the sub-routine is a # factory which should be called to create the actual # filter... eval { ($filter, $error) = &$factory($context, $args ? @$args : ()); }; $error ||= $@; $error = "invalid FILTER for '$name' (not a CODE ref)" unless $error || ref($filter) eq 'CODE'; } else { # ...otherwise, it's a static filter sub-routine $filter = $factory; } } else { $error = "invalid FILTER entry for '$name' (not a CODE ref)"; } if ($error) { return $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ($error, Template::Constants::STATUS_ERROR) ; } else { return $filter; } } #------------------------------------------------------------------------ # store($name, \&filter) # # Stores a new filter in the internal FILTERS hash. The first parameter # is the filter name, the second a reference to a subroutine or # array, as per the standard $FILTERS entries. #------------------------------------------------------------------------ sub store { my ($self, $name, $filter) = @_; $self->debug("store($name, $filter)") if $self->{ DEBUG }; $self->{ FILTERS }->{ $name } = $filter; return 1; } #======================================================================== # -- PRIVATE METHODS -- #======================================================================== #------------------------------------------------------------------------ # _init(\%config) # # Private initialisation method. #------------------------------------------------------------------------ sub _init { my ($self, $params) = @_; $self->{ FILTERS } = $params->{ FILTERS } || { }; $self->{ TOLERANT } = $params->{ TOLERANT } || 0; $self->{ DEBUG } = ( $params->{ DEBUG } || 0 ) & Template::Constants::DEBUG_FILTERS; return $self; } #======================================================================== # -- STATIC FILTER SUBS -- #======================================================================== #------------------------------------------------------------------------ # uri_filter() and url_filter() below can match using either RFC3986 or # RFC2732. See https://github.com/abw/Template2/issues/13 #----------------------------------------------------------------------- our $UNSAFE_SPEC = { RFC2732 => q{A-Za-z0-9\-_.~!*'()}, RFC3986 => q{A-Za-z0-9\-_.~}, }; our $UNSAFE_CHARS = $UNSAFE_SPEC->{ RFC3986 }; our $URI_REGEX; our $URL_REGEX; our $URI_ESCAPES; sub use_rfc2732 { $UNSAFE_CHARS = $UNSAFE_SPEC->{ RFC2732 }; $URI_REGEX = $URL_REGEX = undef; } sub use_rfc3986 { $UNSAFE_CHARS = $UNSAFE_SPEC->{ RFC3986 }; $URI_REGEX = $URL_REGEX = undef; } sub uri_escapes { return { map { ( chr($_), sprintf("%%%02X", $_) ) } (0..255), }; } #------------------------------------------------------------------------ # uri_filter() [% FILTER uri %] # # URI escape a string. This code is borrowed from Gisle Aas' URI::Escape # module, copyright 1995-2004. See RFC2396, RFC2732 and RFC3986 for # details. #----------------------------------------------------------------------- sub uri_filter { my $text = shift; $URI_REGEX ||= qr/([^$UNSAFE_CHARS])/; $URI_ESCAPES ||= uri_escapes(); if ($] >= 5.008 && utf8::is_utf8($text)) { utf8::encode($text); } $text =~ s/$URI_REGEX/$URI_ESCAPES->{$1}/eg; $text; } #------------------------------------------------------------------------ # url_filter() [% FILTER uri %] # # NOTE: the difference: url vs uri. # This implements the old-style, non-strict behaviour of the uri filter # which allows any valid URL characters to pass through so that # http://example.com/blah.html does not get the ':' and '/' characters # munged. #----------------------------------------------------------------------- sub url_filter { my $text = shift; $URL_REGEX ||= qr/([^;\/?:@&=+\$,$UNSAFE_CHARS])/; $URI_ESCAPES ||= uri_escapes(); if ($] >= 5.008 && utf8::is_utf8($text)) { utf8::encode($text); } $text =~ s/$URL_REGEX/$URI_ESCAPES->{$1}/eg; $text; } #------------------------------------------------------------------------ # html_filter() [% FILTER html %] # # Convert any '<', '>' or '&' characters to the HTML equivalents, '<', # '>' and '&', respectively. #------------------------------------------------------------------------ sub html_filter { my $text = shift; for ($text) { s/&/&/g; s/</</g; s/>/>/g; s/"/"/g; } return $text; } #------------------------------------------------------------------------ # xml_filter() [% FILTER xml %] # # Same as the html filter, but adds the conversion of ' to ' which # is native to XML. #------------------------------------------------------------------------ sub xml_filter { my $text = shift; for ($text) { s/&/&/g; s/</</g; s/>/>/g; s/"/"/g; s/'/'/g; } return $text; } #------------------------------------------------------------------------ # html_paragraph() [% FILTER html_para %] # # Wrap each paragraph of text (delimited by two or more newlines) in the # <p>...</p> HTML tags. #------------------------------------------------------------------------ sub html_paragraph { my $text = shift; return "<p>\n" . join("\n</p>\n\n<p>\n", split(/(?:\r?\n){2,}/, $text)) . "</p>\n"; } #------------------------------------------------------------------------ # html_para_break() [% FILTER html_para_break %] # # Join each paragraph of text (delimited by two or more newlines) with # <br><br> HTML tags. #------------------------------------------------------------------------ sub html_para_break { my $text = shift; $text =~ s|(\r?\n){2,}|$1<br />$1<br />$1|g; return $text; } #------------------------------------------------------------------------ # html_line_break() [% FILTER html_line_break %] # # replaces any newlines with <br> HTML tags. #------------------------------------------------------------------------ sub html_line_break { my $text = shift; $text =~ s|(\r?\n)|<br />$1|g; return $text; } #======================================================================== # -- DYNAMIC FILTER FACTORIES -- #======================================================================== #------------------------------------------------------------------------ # html_entity_filter_factory(\%options) [% FILTER html %] # # Dynamic version of the static html filter which attempts to locate the # Apache::Util or HTML::Entities modules to perform full entity encoding # of the text passed. Returns an exception if one or other of the # modules can't be located. #------------------------------------------------------------------------ sub use_html_entities { require HTML::Entities; return ($AVAILABLE->{ HTML_ENTITY } = \&HTML::Entities::encode_entities); } sub use_apache_util { require Apache::Util; Apache::Util::escape_html(''); # TODO: explain this return ($AVAILABLE->{ HTML_ENTITY } = \&Apache::Util::escape_html); } sub html_entity_filter_factory { my $context = shift; my $haz; # if Apache::Util is installed then we use escape_html $haz = $AVAILABLE->{ HTML_ENTITY } || eval { use_apache_util() } || eval { use_html_entities() } || -1; # we use -1 for "not available" because it's a true value return ref $haz eq 'CODE' ? $haz : (undef, Template::Exception->new( html_entity => 'cannot locate Apache::Util or HTML::Entities' ) ); } #------------------------------------------------------------------------ # indent_filter_factory($pad) [% FILTER indent(pad) %] # # Create a filter to indent text by a fixed pad string or when $pad is # numerical, a number of space. #------------------------------------------------------------------------ sub indent_filter_factory { my ($context, $pad) = @_; $pad = 4 unless defined $pad; $pad = ' ' x $pad if $pad =~ /^\d+$/; return sub { my $text = shift; $text = '' unless defined $text; $text =~ s/^/$pad/mg; return $text; } } #------------------------------------------------------------------------ # format_filter_factory() [% FILTER format(format) %] # # Create a filter to format text according to a printf()-like format # string. #------------------------------------------------------------------------ sub format_filter_factory { my ($context, $format) = @_; $format = '%s' unless defined $format; return sub { my $text = shift; $text = '' unless defined $text; return join("\n", map{ sprintf($format, $_) } split(/\n/, $text)); } } #------------------------------------------------------------------------ # repeat_filter_factory($n) [% FILTER repeat(n) %] # # Create a filter to repeat text n times. #------------------------------------------------------------------------ sub repeat_filter_factory { my ($context, $iter) = @_; $iter = 1 unless defined $iter and length $iter; return sub { my $text = shift; $text = '' unless defined $text; return join('\n', $text) x $iter; } } #------------------------------------------------------------------------ # replace_filter_factory($s, $r) [% FILTER replace(search, replace) %] # # Create a filter to replace 'search' text with 'replace' #------------------------------------------------------------------------ sub replace_filter_factory { my ($context, $search, $replace) = @_; $search = '' unless defined $search; $replace = '' unless defined $replace; return sub { my $text = shift; $text = '' unless defined $text; $text =~ s/$search/$replace/g; return $text; } } #------------------------------------------------------------------------ # remove_filter_factory($text) [% FILTER remove(text) %] # # Create a filter to remove 'search' string from the input text. #------------------------------------------------------------------------ sub remove_filter_factory { my ($context, $search) = @_; return sub { my $text = shift; $text = '' unless defined $text; $text =~ s/$search//g; return $text; } } #------------------------------------------------------------------------ # truncate_filter_factory($n) [% FILTER truncate(n) %] # # Create a filter to truncate text after n characters. #------------------------------------------------------------------------ sub truncate_filter_factory { my ($context, $len, $char) = @_; $len = $TRUNCATE_LENGTH unless defined $len; $char = $TRUNCATE_ADDON unless defined $char; # Length of char is the minimum length my $lchar = length $char; if ($len < $lchar) { $char = substr($char, 0, $len); $lchar = $len; } return sub { my $text = shift; return $text if length $text <= $len; return substr($text, 0, $len - $lchar) . $char; } } #------------------------------------------------------------------------ # eval_filter_factory [% FILTER eval %] # # Create a filter to evaluate template text. #------------------------------------------------------------------------ sub eval_filter_factory { my $context = shift; return sub { my $text = shift; $context->process(\$text); } } #------------------------------------------------------------------------ # perl_filter_factory [% FILTER perl %] # # Create a filter to process Perl text iff the context EVAL_PERL flag # is set. #------------------------------------------------------------------------ sub perl_filter_factory { my $context = shift; my $stash = $context->stash; return (undef, Template::Exception->new('perl', 'EVAL_PERL is not set')) unless $context->eval_perl(); return sub { my $text = shift; local($Template::Perl::context) = $context; local($Template::Perl::stash) = $stash; my $out = eval <<EOF; package Template::Perl; \$stash = \$context->stash(); $text EOF $context->throw($@) if $@; return $out; } } #------------------------------------------------------------------------ # redirect_filter_factory($context, $file) [% FILTER redirect(file) %] # # Create a filter to redirect the block text to a file. #------------------------------------------------------------------------ sub redirect_filter_factory { my ($context, $file, $options) = @_; my $outpath = $context->config->{ OUTPUT_PATH }; return (undef, Template::Exception->new('redirect', 'OUTPUT_PATH is not set')) unless $outpath; $context->throw('redirect', "relative filenames are not supported: $file") if $file =~ m{(^|/)\.\./}; $options = { binmode => $options } unless ref $options; sub { my $text = shift; my $outpath = $context->config->{ OUTPUT_PATH } || return ''; $outpath .= "/$file"; my $error = Template::_output($outpath, \$text, $options); die Template::Exception->new('redirect', $error) if $error; return ''; } } #------------------------------------------------------------------------ # stdout_filter_factory($context, $binmode) [% FILTER stdout(binmode) %] # # Create a filter to print a block to stdout, with an optional binmode. #------------------------------------------------------------------------ sub stdout_filter_factory { my ($context, $options) = @_; $options = { binmode => $options } unless ref $options; sub { my $text = shift; binmode(STDOUT) if $options->{ binmode }; print STDOUT $text; return ''; } } 1; __END__ =head1 NAME Template::Filters - Post-processing filters for template blocks =head1 SYNOPSIS use Template::Filters; $filters = Template::Filters->new(\%config); ($filter, $error) = $filters->fetch($name, \@args, $context); if ($filter) { print &$filter("some text"); } else { print "Could not fetch $name filter: $error\n"; } =head1 DESCRIPTION The C<Template::Filters> module implements a provider for creating subroutines that implement the standard filters. Additional custom filters may be provided via the L<FILTERS> configuration option. =head1 METHODS =head2 new(\%params) Constructor method which instantiates and returns a reference to a C<Template::Filters> object. A reference to a hash array of configuration items may be passed as a parameter. These are described below. my $filters = Template::Filters->new({ FILTERS => { ... }, }); my $template = Template->new({ LOAD_FILTERS => [ $filters ], }); A default C<Template::Filters> module is created by the L<Template> module if the L<LOAD_FILTERS> option isn't specified. All configuration parameters are forwarded to the constructor. $template = Template->new({ FILTERS => { ... }, }); =head2 fetch($name, \@args, $context) Called to request that a filter of a given name be provided. The name of the filter should be specified as the first parameter. This should be one of the standard filters or one specified in the L<FILTERS> configuration hash. The second argument should be a reference to an array containing configuration parameters for the filter. This may be specified as 0, or undef where no parameters are provided. The third argument should be a reference to the current L<Template::Context> object. The method returns a reference to a filter sub-routine on success. It may also return C<(undef, STATUS_DECLINE)> to decline the request, to allow delegation onto other filter providers in the L<LOAD_FILTERS> chain of responsibility. On error, C<($error, STATUS_ERROR)> is returned where $error is an error message or L<Template::Exception> object indicating the error that occurred. When the C<TOLERANT> option is set, errors are automatically downgraded to a C<STATUS_DECLINE> response. =head2 use_html_entities() This class method can be called to configure the C<html_entity> filter to use the L<HTML::Entities> module. An error will be raised if it is not installed on your system. use Template::Filters; Template::Filters->use_html_entities(); =head2 use_apache_util() This class method can be called to configure the C<html_entity> filter to use the L<Apache::Util> module. An error will be raised if it is not installed on your system. use Template::Filters; Template::Filters->use_apache_util(); =head2 use_rfc2732() This class method can be called to configure the C<uri> and C<url> filters to use the older RFC2732 standard for matching unsafe characters. =head2 use_rfc3986() This class method can be called to configure the C<uri> and C<url> filters to use the newer RFC3986 standard for matching unsafe characters. =head1 CONFIGURATION OPTIONS The following list summarises the configuration options that can be provided to the C<Template::Filters> L<new()> constructor. Please see L<Template::Manual::Config> for further information about each option. =head2 FILTERS The L<FILTERS|Template::Manual::Config#FILTERS> option can be used to specify custom filters which can then be used with the L<FILTER|Template::Manual::Directives#FILTER> directive like any other. These are added to the standard filters which are available by default. $filters = Template::Filters->new({ FILTERS => { 'sfilt1' => \&static_filter, 'dfilt1' => [ \&dyanamic_filter_factory, 1 ], }, }); =head2 TOLERANT The L<TOLERANT|Template::Manual::Config#TOLERANT> flag can be set to indicate that the C<Template::Filters> module should ignore any errors and instead return C<STATUS_DECLINED>. =head2 DEBUG The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable debugging messages for the Template::Filters module by setting it to include the C<DEBUG_FILTERS> value. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS, }); =head1 STANDARD FILTERS Please see L<Template::Manual::Filters> for a list of the filters provided with the Template Toolkit, complete with examples of use. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-20202Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Manual::Filters>, L<Template>, L<Template::Context> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[ �? �? lib/Template/Document.pmnu ��6�$ ##============================================================= -*-Perl-*- # # Template::Document # # DESCRIPTION # Module defining a class of objects which encapsulate compiled # templates, storing additional block definitions and metadata # as well as the compiled Perl sub-routine representing the main # template content. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Document; use strict; use warnings; use base 'Template::Base'; use Template::Constants; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $ERROR = ''; our ($COMPERR, $AUTOLOAD, $UNICODE); BEGIN { # UNICODE is supported in versions of Perl from 5.008 onwards if ($UNICODE = $] > 5.007 ? 1 : 0) { if ($] > 5.008) { # utf8::is_utf8() available from Perl 5.8.1 onwards *is_utf8 = \&utf8::is_utf8; } elsif ($] == 5.008) { # use Encode::is_utf8() for Perl 5.8.0 require Encode; *is_utf8 = \&Encode::is_utf8; } } } #======================================================================== # ----- PUBLIC METHODS ----- #======================================================================== #------------------------------------------------------------------------ # new(\%document) # # Creates a new self-contained Template::Document object which # encapsulates a compiled Perl sub-routine, $block, any additional # BLOCKs defined within the document ($defblocks, also Perl sub-routines) # and additional $metadata about the document. #------------------------------------------------------------------------ sub new { my ($class, $doc) = @_; my ($block, $defblocks, $variables, $metadata) = @$doc{ qw( BLOCK DEFBLOCKS VARIABLES METADATA ) }; $defblocks ||= { }; $metadata ||= { }; # evaluate Perl code in $block to create sub-routine reference if necessary unless (ref $block) { local $SIG{__WARN__} = \&catch_warnings; $COMPERR = ''; # DON'T LOOK NOW! - blindly untainting can make you go blind! { no warnings 'syntax'; $block = each %{ { $block => undef } } if ${^TAINT}; #untaint } $block = eval $block; return $class->error($@) unless defined $block; } # same for any additional BLOCK definitions @$defblocks{ keys %$defblocks } = # MORE BLIND UNTAINTING - turn away if you're squeamish map { ref($_) ? $_ : ( /(.*)/s && eval($1) or return $class->error($@) ) } values %$defblocks; bless { %$metadata, _BLOCK => $block, _DEFBLOCKS => $defblocks, _VARIABLES => $variables, _HOT => 0, }, $class; } #------------------------------------------------------------------------ # block() # # Returns a reference to the internal sub-routine reference, _BLOCK, # that constitutes the main document template. #------------------------------------------------------------------------ sub block { return $_[0]->{ _BLOCK }; } #------------------------------------------------------------------------ # blocks() # # Returns a reference to a hash array containing any BLOCK definitions # from the template. The hash keys are the BLOCK name and the values # are references to Template::Document objects. Returns 0 (# an empty hash) # if no blocks are defined. #------------------------------------------------------------------------ sub blocks { return $_[0]->{ _DEFBLOCKS }; } #----------------------------------------------------------------------- # variables() # # Returns a reference to a hash of variables used in the template. # This requires the TRACE_VARS option to be enabled. #----------------------------------------------------------------------- sub variables { return $_[0]->{ _VARIABLES }; } #------------------------------------------------------------------------ # process($context) # # Process the document in a particular context. Checks for recursion, # registers the document with the context via visit(), processes itself, # and then unwinds with a large gin and tonic. #------------------------------------------------------------------------ sub process { my ($self, $context) = @_; my $defblocks = $self->{ _DEFBLOCKS }; my $output; # check we're not already visiting this template return $context->throw( Template::Constants::ERROR_FILE, "recursion into '$self->{ name }'" ) if $self->{ _HOT } && ! $context->{ RECURSION }; ## RETURN ## $context->visit($self, $defblocks); $self->{ _HOT } = 1; eval { my $block = $self->{ _BLOCK }; $output = &$block($context); }; $self->{ _HOT } = 0; $context->leave(); die $context->catch($@) if $@; return $output; } #------------------------------------------------------------------------ # meta() # # Return the META items, i.e. anything that isn't prefixed with a _, e.g. # _BLOCKS, or the name or modtime items. #------------------------------------------------------------------------ sub meta { my $self = shift; return { map { $_ => $self->{ $_ } } grep { ! /^(_|modtime$|name$)/ } keys %$self }; } #------------------------------------------------------------------------ # AUTOLOAD # # Provides pseudo-methods for read-only access to various internal # members. #------------------------------------------------------------------------ sub AUTOLOAD { my $self = shift; my $method = $AUTOLOAD; $method =~ s/.*:://; return if $method eq 'DESTROY'; # my ($pkg, $file, $line) = caller(); # print STDERR "called $self->AUTOLOAD($method) from $file line $line\n"; return $self->{ $method }; } #======================================================================== # ----- CLASS METHODS ----- #======================================================================== #------------------------------------------------------------------------ # as_perl($content) # # This method expects a reference to a hash passed as the first argument # containing 3 items: # METADATA # a hash of template metadata # BLOCK # string containing Perl sub definition for main block # DEFBLOCKS # hash containing further subs for addional BLOCK defs # It returns a string containing Perl code which, when evaluated and # executed, will instantiate a new Template::Document object with the # above data. On error, it returns undef with an appropriate error # message set in $ERROR. #------------------------------------------------------------------------ sub as_perl { my ($class, $content) = @_; my ($block, $defblocks, $metadata) = @$content{ qw( BLOCK DEFBLOCKS METADATA ) }; $block =~ s/\s+$//; $defblocks = join('', map { my $code = $defblocks->{ $_ }; $code =~ s/\s*$//; " '$_' => $code,\n"; } keys %$defblocks); $defblocks =~ s/\s+$//; $metadata = join( '', map { my $x = $metadata->{ $_ }; $x =~ s/(['\\])/\\$1/g; " '$_' => '$x',\n"; } keys %$metadata ); $metadata =~ s/\s+$//; return <<EOF #------------------------------------------------------------------------ # Compiled template generated by the Template Toolkit version $Template::VERSION #------------------------------------------------------------------------ $class->new({ METADATA => { $metadata }, BLOCK => $block, DEFBLOCKS => { $defblocks }, }); EOF } #------------------------------------------------------------------------ # write_perl_file($filename, \%content) # # This method calls as_perl() to generate the Perl code to represent a # compiled template with the content passed as the second argument. # It then writes this to the file denoted by the first argument. # # Returns 1 on success. On error, sets the $ERROR package variable # to contain an error message and returns undef. #------------------------------------------------------------------------ sub write_perl_file { my ($class, $file, $content) = @_; my ($fh, $tmpfile); return $class->error("invalid filename: $file") unless defined $file && length $file; eval { require File::Temp; require File::Basename; ($fh, $tmpfile) = File::Temp::tempfile( DIR => File::Basename::dirname($file) ); my $perlcode = $class->as_perl($content) || die $!; if ($UNICODE && is_utf8($perlcode)) { $perlcode = "use utf8;\n\n$perlcode"; binmode $fh, ":utf8"; } print $fh $perlcode; close($fh); }; return $class->error($@) if $@; return rename($tmpfile, $file) || $class->error($!); } #------------------------------------------------------------------------ # catch_warnings($msg) # # Installed as #------------------------------------------------------------------------ sub catch_warnings { $COMPERR .= join('', @_); } 1; __END__ =head1 NAME Template::Document - Compiled template document object =head1 SYNOPSIS use Template::Document; $doc = Template::Document->new({ BLOCK => sub { # some perl code; return $some_text }, DEFBLOCKS => { header => sub { # more perl code; return $some_text }, footer => sub { # blah blah blah; return $some_text }, }, METADATA => { author => 'Andy Wardley', version => 3.14, } }) || die $Template::Document::ERROR; print $doc->process($context); =head1 DESCRIPTION This module defines an object class whose instances represent compiled template documents. The L<Template::Parser> module creates a C<Template::Document> instance to encapsulate a template as it is compiled into Perl code. The constructor method, L<new()>, expects a reference to a hash array containing the C<BLOCK>, C<DEFBLOCKS> and C<METADATA> items. The C<BLOCK> item should contain a reference to a Perl subroutine or a textual representation of Perl code, as generated by the L<Template::Parser> module. This is then evaluated into a subroutine reference using C<eval()>. The C<DEFBLOCKS> item should reference a hash array containing further named C<BLOCK>s which may be defined in the template. The keys represent C<BLOCK> names and the values should be subroutine references or text strings of Perl code as per the main C<BLOCK> item. The C<METADATA> item should reference a hash array of metadata items relevant to the document. The L<process()> method can then be called on the instantiated C<Template::Document> object, passing a reference to a L<Template::Context> object as the first parameter. This will install any locally defined blocks (C<DEFBLOCKS>) in the C<BLOCKS> cache in the context (via a call to L<visit()|Template::Context#visit()>) so that they may be subsequently resolved by the context. The main C<BLOCK> subroutine is then executed, passing the context reference on as a parameter. The text returned from the template subroutine is then returned by the L<process()> method, after calling the context L<leave()|Template::Context#leave()> method to permit cleanup and de-registration of named C<BLOCKS> previously installed. An C<AUTOLOAD> method provides access to the C<METADATA> items for the document. The L<Template::Service> module installs a reference to the main C<Template::Document> object in the stash as the C<template> variable. This allows metadata items to be accessed from within templates, including C<PRE_PROCESS> templates. header: <html> <head> <title>[% template.title %] </head> ... C<Template::Document> objects are usually created by the L<Template::Parser> but can be manually instantiated or sub-classed to provide custom template components. =head1 METHODS =head2 new(\%config) Constructor method which accept a reference to a hash array containing the structure as shown in this example: $doc = Template::Document->new({ BLOCK => sub { # some perl code; return $some_text }, DEFBLOCKS => { header => sub { # more perl code; return $some_text }, footer => sub { # blah blah blah; return $some_text }, }, METADATA => { author => 'Andy Wardley', version => 3.14, } }) || die $Template::Document::ERROR; C<BLOCK> and C<DEFBLOCKS> items may be expressed as references to Perl subroutines or as text strings containing Perl subroutine definitions, as is generated by the L<Template::Parser> module. These are evaluated into subroutine references using C<eval()>. Returns a new C<Template::Document> object or C<undef> on error. The L<error()|Template::Base#error()> class method can be called, or the C<$ERROR> package variable inspected to retrieve the relevant error message. =head2 process($context) Main processing routine for the compiled template document. A reference to a L<Template::Context> object should be passed as the first parameter. The method installs any locally defined blocks via a call to the context L<visit()|Template::Context#visit()> method, processes its own template, (passing the context reference as a parameter) and then calls L<leave()|Template::Context#leave()> in the context to allow cleanup. print $doc->process($context); Returns a text string representing the generated output for the template. Errors are thrown via C<die()>. =head2 block() Returns a reference to the main C<BLOCK> subroutine. =head2 blocks() Returns a reference to the hash array of named C<DEFBLOCKS> subroutines. =head2 variables() Returns a reference to a hash of variables used in the template. This requires the L<TRACE_VARS|Template::Manual::Config#TRACE_VARS> option to be enabled. =head2 meta() Return a reference to a hash of any META items defined in the template. =head2 AUTOLOAD An autoload method returns C<METADATA> items. print $doc->author(); =head1 CLASS METHODS These methods are used internally. =head2 as_perl($content) This method generate a Perl representation of the template. my $perl = Template::Document->as_perl({ BLOCK => $main_block, DEFBLOCKS => { foo => $foo_block, bar => $bar_block, }, METADATA => { name => 'my_template', } }); =head2 write_perl_file(\%config) This method is used to write compiled Perl templates to disk. If the C<COMPILE_EXT> option (to indicate a file extension for saving compiled templates) then the L<Template::Parser> module calls this subroutine before calling the L<new()> constructor. At this stage, the parser has a representation of the template as text strings containing Perl code. We can write that to a file, enclosed in a small wrapper which will allow us to subsequently C<require()> the file and have Perl parse and compile it into a C<Template::Document>. Thus we have persistence of compiled templates. =head1 INTERNAL FUNCTIONS =head2 catch_warnings() This is a simple handler used to catch any errors that arise when the compiled Perl template is first evaluated (that is, evaluated by Perl to create a template subroutine at compile, rather than the template being processed at runtime). =head2 is_utf8() This is mapped to C<utf8::is_utf8> for versions of Perl that have it (> 5.008) or to C<Encode::is_utf8> for Perl 5.008. Earlier versions of Perl are not supported. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2013 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Parser> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�� ;^ ^ lib/Template/Toolkit.pmnu ��6�$ #============================================================= -*-perl-*- # # Template::Toolkit # # DESCRIPTION # Front-page for the Template Toolkit documentation # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== package Template::Toolkit; our $VERSION = '3.100'; 1; __END__ =head1 NAME Template::Toolkit - Template Processing System =head1 Introduction The Template Toolkit is a collection of Perl modules which implement a fast, flexible, powerful and extensible template processing system. It is "input-agnostic" and can be used equally well for processing any kind of text documents: HTML, XML, CSS, Javascript, Perl code, plain text, and so on. However, it is most often used for generating static and dynamic web content, so that's what we'll focus on here. Although the Template Toolkit is written in Perl, you don't need to be a Perl programmer to use it. It was designed to allow non-programmers to easily create and maintain template-based web sites without having to mess around writing Perl code or going crazy with cut-n-paste. However, the Template Toolkit is also designed to be extremely flexible and extensible. If you are a Perl programmer, or know someone who is, then you can easily hook the Template Toolkit into your existing code, data, databases and web applications. Furthermore, you can easily extend the Template Toolkit through the use of its plugin mechanism and other developer APIs. Whatever context you use it in, the primary purpose of the Template Toolkit is to allow you to create a clear separation between the presentation elements of your web site and everything else. If you're generating static web pages, then you can use it to separate the commonly repeated user interface elements on each page (headers, menus, footers, etc.) from the core content. If you're generating dynamic web pages for the front end of a web application, then you'll also be using it to keep the back-end Perl code entirely separate from the front-end HTML templates. Either way, a I<clear separation of concerns> is what allow you to concentrate on one thing at a time without the other things getting in your way. And that's what the Template Toolkit is all about. =head1 Documentation The documentation for the Template Toolkit is organised into five sections. The L<Template::Manual> contains detailed information about using the Template Toolkit. It gives examples of its use and includes a full reference of the template language, configuration options, filters, plugins and other component parts. The L<Template::Modules> page lists the Perl modules that comprise the Template Toolkit. It gives a brief explanation of what each of them does, and provides a link to the complete documentation for each module for further information. If you're a Perl programmer looking to use the Template Toolkit from your Perl programs then this section is likely to be of interest. Most, if not all of the information you need to call the Template Toolkit from Perl is in the documentation for the L<Template> module. You only really need to start thinking about the other modules if you want to extend or modify the Template Toolkit in some way, or if you're interested in looking under the hood to see how it all works. The documentation for each module is embedded as POD in each module, so you can always use C<perldoc> from the command line to read a module's documentation. e.g. $ perldoc Template $ perldoc Template::Context ...etc... It's worth noting that all the other documentation, including the user manual is available as POD. e.g. $ perldoc Template::Manual $ perldoc Template::Manual::Config ...etc... The L<Template::Tools> section contains the documentation for L<Template::Tools::tpage|tpage> and L<Template::Tools::ttree|ttree>. These are two command line programs that are distributed with the Template Toolkit. L<tpage|Template::Tools::tpage> is used to process a single template file, L<ttree|Template::Tools::ttree> for processing entire directories of template files. The L<Template::Tutorial> section contains two introductory tutorials on using the Template Toolkit. The first is L<Template::Tutorial::Web> on generating web content. The second is L<Template::Tutorial::Datafile> on using the Template Toolkit to generate other data formats including XML. The final section of the manual is L<Template::FAQ> which contains answers to some of the Frequently Asked Questions about the Template Toolkit. You can read the documentation in HTML format either online at the Template Toolkit web site, L<http://template-toolkit.org/>, or by downloading the HTML version of the documentation from L<http://template-toolkit.org/download/index.html#html_docs> and unpacking it on your local machine. =head1 Author The Template Toolkit was written by Andy Wardley (L<http://wardley.org/> L<mailto:abw@wardley.org>) with assistance and contributions from a great number of people. Please see L<Template::Manual::Credits> for a full list. =head1 Copyright Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 See Also L<Template>, L<Template::Manual>, L<Template::Modules>, L<Template::Tools>, L<Template::Tutorial> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[���,| | lib/Template/Manual.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Manual # # DESCRIPTION # Front-page for the TT manual. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual - Template Toolkit User Manual =head1 Template Toolkit Manual The Template Toolkit manual contains documentation on using and extending the Template Toolkit. =head2 Template::Manual::Intro The L<Template::Manual::Intro> page provides an introduction to the Template Toolkit =head2 Template::Manual::Syntax The L<Template::Manual::Syntax> describes the syntax and structure of templates and the directive tags embedded within them. =head2 Template::Manual::Directives The L<Template::Manual::Directives> page lists all the Template Toolkit directives and gives examples of their use. =head2 Template::Manual::Variables The L<Template::Manual::Variables> page describes the use of variables in templates. =head2 Template::Manual::VMethods The L<Template::Manual::VMethods> page provides a full list of virtual methods that can be used in conjunction with variables, and gives examples of their use. =head2 Template::Manual::Config The L<Template::Manual::Config> page describes all of the Template Toolkit configuration options. =head2 Template::Manual::Filters The L<Template::Manual::Filters> page lists all of the Template Toolkit filters and gives examples of their use. =head2 Template::Manual::Plugins The L<Template::Manual::Plugins> page lists all of the standard plugins distributed with Template Toolkit and gives examples of their use. =head2 Template::Manual::Internals The L<Template::Manual::Internals> page describes the internal workings of the Template Toolkit. It is aimed at developers who wish to extend or modify the =head2 Template::Manual::Views The L<Template::Manual::Views> page describes the experimental C<VIEW> directive. =head2 Template::Manual::Credits The L<Template::Manual::Credits> page lists the people who have contributed to the Template Toolkit. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��K�e e # lib/Template/Namespace/Constants.pmnu ��6�$ #================================================================= -*-Perl-*- # # Template::Namespace::Constants # # DESCRIPTION # Plugin compiler module for performing constant folding at compile time # on variables in a particular namespace. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Namespace::Constants; use strict; use warnings; use base 'Template::Base'; use Template::Config; use Template::Directive; use Template::Exception; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; sub _init { my ($self, $config) = @_; $self->{ STASH } = Template::Config->stash($config) || return $self->error(Template::Config->error()); return $self; } #------------------------------------------------------------------------ # ident(\@ident) foo.bar(baz) #------------------------------------------------------------------------ sub ident { my ($self, $ident) = @_; my @save = @$ident; # discard first node indicating constants namespace splice(@$ident, 0, 2); my $nelems = @$ident / 2; my ($e, $result); local $" = ', '; print STDERR "constant ident [ @$ident ] " if $DEBUG; foreach $e (0..$nelems-1) { # node name must be a constant unless ($ident->[$e * 2] =~ s/^'(.+)'$/$1/s) { $self->DEBUG(" * deferred (non-constant item: ", $ident->[$e * 2], ")\n") if $DEBUG; return Template::Directive->ident(\@save); } # if args is non-zero then it must be eval'ed if ($ident->[$e * 2 + 1]) { my $args = $ident->[$e * 2 + 1]; my $comp = eval "$args"; if ($@) { $self->DEBUG(" * deferred (non-constant args: $args)\n") if $DEBUG; return Template::Directive->ident(\@save); } $self->DEBUG("($args) ") if $comp && $DEBUG; $ident->[$e * 2 + 1] = $comp; } } $result = $self->{ STASH }->get($ident); if (! length $result || ref $result) { my $reason = length $result ? 'reference' : 'no result'; $self->DEBUG(" * deferred ($reason)\n") if $DEBUG; return Template::Directive->ident(\@save); } $result =~ s/'/\\'/g; $self->DEBUG(" * resolved => '$result'\n") if $DEBUG; return "'$result'"; } 1; __END__ =head1 NAME Template::Namespace::Constants - Compile time constant folding =head1 SYNOPSIS # easy way to define constants use Template; my $tt = Template->new({ CONSTANTS => { pi => 3.14, e => 2.718, }, }); # nitty-gritty, hands-dirty way use Template::Namespace::Constants; my $tt = Template->new({ NAMESPACE => { constants => Template::Namespace::Constants->new({ pi => 3.14, e => 2.718, }, }, }); =head1 DESCRIPTION The C<Template::Namespace::Constants> module implements a namespace handler which is plugged into the C<Template::Directive> compiler module. This then performs compile time constant folding of variables in a particular namespace. =head1 METHODS =head2 new(\%constants) The new() constructor method creates and returns a reference to a new Template::Namespace::Constants object. This creates an internal stash to store the constant variable definitions passed as arguments. my $handler = Template::Namespace::Constants->new({ pi => 3.14, e => 2.718, }); =head2 ident(\@ident) Method called to resolve a variable identifier into a compiled form. In this case, the method fetches the corresponding constant value from its internal stash and returns it. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Directive> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[A Z�] �] lib/Template/View.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::View # # DESCRIPTION # A custom view of a template processing context. Can be used to # implement custom "skins". # # AUTHOR # Andy Wardley <abw@kfs.org> # # COPYRIGHT # Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # TODO # * allowing print to have a hash ref as final args will cause problems # if you do this: [% view.print(hash1, hash2, hash3) %]. Current # work-around is to do [% view.print(hash1); view.print(hash2); # view.print(hash3) %] or [% view.print(hash1, hash2, hash3, { }) %] # #============================================================================ package Template::View; use strict; use warnings; use base 'Template::Base'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our @BASEARGS = qw( context ); our $AUTOLOAD; our $MAP = { HASH => 'hash', ARRAY => 'list', TEXT => 'text', default => '', }; #------------------------------------------------------------------------ # _init(\%config) # # Initialisation method called by the Template::Base class new() # constructor. $self->{ context } has already been set, by virtue of # being named in @BASEARGS. Remaining config arguments are presented # as a hash reference. #------------------------------------------------------------------------ sub _init { my ($self, $config) = @_; # move 'context' somewhere more private $self->{ _CONTEXT } = $self->{ context }; delete $self->{ context }; # generate table mapping object types to templates my $map = $config->{ map } || { }; $map->{ default } = $config->{ default } unless defined $map->{ default }; $self->{ map } = { %$MAP, %$map, }; # local BLOCKs definition table $self->{ _BLOCKS } = $config->{ blocks } || { }; # name of presentation method which printed objects might provide $self->{ method } = defined $config->{ method } ? $config->{ method } : 'present'; # view is sealed by default preventing variable update after # definition, however we don't actually seal a view until the # END of the view definition my $sealed = $config->{ sealed }; $sealed = 1 unless defined $sealed; $self->{ sealed } = $sealed ? 1 : 0; # copy remaining config items from $config or set defaults foreach my $arg (qw( base prefix suffix notfound silent )) { $self->{ $arg } = $config->{ $arg } || ''; } # check that any base specified is defined return $self->error('Invalid base specified for view') if exists $config->{ base } && ! $self->{ base }; # name of data item used by view() $self->{ item } = $config->{ item } || 'item'; # map methods of form ${include_prefix}_foobar() to include('foobar')? $self->{ include_prefix } = $config->{ include_prefix } || 'include_'; # what about mapping foobar() to include('foobar')? $self->{ include_naked } = defined $config->{ include_naked } ? $config->{ include_naked } : 1; # map methods of form ${view_prefix}_foobar() to include('foobar')? $self->{ view_prefix } = $config->{ view_prefix } || 'view_'; # what about mapping foobar() to view('foobar')? $self->{ view_naked } = $config->{ view_naked } || 0; # the view is initially unsealed, allowing directives in the initial # view template to create data items via the AUTOLOAD; once sealed via # call to seal(), the AUTOLOAD will not update any internal items. delete @$config{ qw( base method map default prefix suffix notfound item include_prefix include_naked silent sealed view_prefix view_naked blocks ) }; $config = { %{ $self->{ base }->{ data } }, %$config } if $self->{ base }; $self->{ data } = $config; $self->{ SEALED } = 0; return $self; } #------------------------------------------------------------------------ # seal() # unseal() # # Seal or unseal the view to allow/prevent new data items from being # automatically created by the AUTOLOAD method. #------------------------------------------------------------------------ sub seal { my $self = shift; $self->{ SEALED } = $self->{ sealed }; } sub unseal { my $self = shift; $self->{ SEALED } = 0; } #------------------------------------------------------------------------ # clone(\%config) # # Cloning method which takes a copy of $self and then applies to it any # modifications specified in the $config hash passed as an argument. # Configuration items may also be specified as a list of "name => $value" # arguments. Returns a reference to the cloned Template::View object. # # NOTE: may need to copy BLOCKS??? #------------------------------------------------------------------------ sub clone { my $self = shift; my $clone = bless { %$self }, ref $self; my $config = ref $_[0] eq 'HASH' ? shift : { @_ }; # merge maps $clone->{ map } = { %{ $self->{ map } }, %{ $config->{ map } || { } }, }; # "map => { default=>'xxx' }" can be specified as "default => 'xxx'" $clone->{ map }->{ default } = $config->{ default } if defined $config->{ default }; # update any remaining config items my @args = qw( base prefix suffix notfound item method include_prefix include_naked view_prefix view_naked ); foreach my $arg (@args) { $clone->{ $arg } = $config->{ $arg } if defined $config->{ $arg }; } push(@args, qw( default map )); delete @$config{ @args }; # anything left is data my $data = $clone->{ data } = { %{ $self->{ data } } }; @$data{ keys %$config } = values %$config; return $clone; } #------------------------------------------------------------------------ # print(@items, ..., \%config) # # Prints @items in turn by mapping each to an appropriate template using # the internal 'map' hash. If an entry isn't found and the item is an # object that implements the method named in the internal 'method' item, # (default: 'present'), then the method will be called passing a reference # to $self, against which the presenter method may make callbacks (e.g. # to view_item()). If the presenter method isn't implemented, then the # 'default' map entry is consulted and used if defined. The final argument # may be a reference to a hash array providing local overrides to the internal # defaults for various items (prefix, suffix, etc). In the presence # of this parameter, a clone of the current object is first made, applying # any configuration updates, and control is then delegated to it. #------------------------------------------------------------------------ sub print { my $self = shift; # if final config hash is specified then create a clone and delegate to it # NOTE: potential problem when called print(\%data_hash1, \%data_hash2); if ((scalar @_ > 1) && (ref $_[-1] eq 'HASH')) { my $cfg = pop @_; my $clone = $self->clone($cfg) || return; return $clone->print(@_) || $self->error($clone->error()); } my ($item, $type, $template, $present); my $method = $self->{ method }; my $map = $self->{ map }; my $output = ''; # print each argument foreach $item (@_) { my $newtype; if (! ($type = ref $item)) { # non-references are TEXT $type = 'TEXT'; $template = $map->{ $type }; } elsif (! defined ($template = $map->{ $type })) { # no specific map entry for object, maybe it implements a # 'present' (or other) method? if ( $method && UNIVERSAL::can($item, $method) ) { $present = $item->$method($self); ## call item method # undef returned indicates error, note that we expect # $item to have called error() on the view return unless defined $present; $output .= $present; next; ## NEXT } elsif ( ref($item) eq 'HASH' && defined($newtype = $item->{$method}) && defined($template = $map->{"$method=>$newtype"})) { } elsif ( defined($newtype) && defined($template = $map->{"$method=>*"}) ) { $template =~ s/\*/$newtype/; } elsif (! ($template = $map->{ default }) ) { # default not defined, so construct template name from type ($template = $type) =~ s/\W+/_/g; } } # else { # $self->DEBUG("defined map type for $type: $template\n"); # } $self->DEBUG("printing view '", $template || '', "', $item\n") if $DEBUG; $output .= $self->view($template, $item) if $template; } return $output; } #------------------------------------------------------------------------ # view($template, $item, \%vars) # # Wrapper around include() which expects a template name, $template, # followed by a data item, $item, and optionally, a further hash array # of template variables. The $item is added as an entry to the $vars # hash (which is created empty if not passed as an argument) under the # name specified by the internal 'item' member, which is appropriately # 'item' by default. Thus an external object present() method can # callback against this object method, simply passing a data item to # be displayed. The external object doesn't have to know what the # view expects the item to be called in the $vars hash. #------------------------------------------------------------------------ sub view { my ($self, $template, $item) = splice(@_, 0, 3); my $vars = ref $_[0] eq 'HASH' ? shift : { @_ }; $vars->{ $self->{ item } } = $item if defined $item; $self->include($template, $vars); } #------------------------------------------------------------------------ # include($template, \%vars) # # INCLUDE a template, $template, mapped according to the current prefix, # suffix, default, etc., where $vars is an optional hash reference # containing template variable definitions. If the template isn't found # then the method will default to any 'notfound' template, if defined # as an internal item. #------------------------------------------------------------------------ sub include { my ($self, $template, $vars) = @_; my $context = $self->{ _CONTEXT }; $template = $self->template($template); $vars = { } unless ref $vars eq 'HASH'; $vars->{ view } ||= $self; $context->include( $template, $vars ); # DEBUGGING # my $out = $context->include( $template, $vars ); # print STDERR "VIEW return [$out]\n"; # return $out; } #------------------------------------------------------------------------ # template($template) # # Returns a compiled template for the specified template name, according # to the current configuration parameters. #------------------------------------------------------------------------ sub template { my ($self, $name) = @_; my $context = $self->{ _CONTEXT }; return $context->throw( Template::Constants::ERROR_VIEW, "no view template specified" ) unless $name; my $notfound = $self->{ notfound }; my $base = $self->{ base }; my ($template, $block, $error); return $block if ($block = $self->{ _BLOCKS }->{ $name }); # try the named template $template = $self->template_name($name); $self->DEBUG("looking for $template\n") if $DEBUG; eval { $template = $context->template($template) }; # try asking the base view if not found if (($error = $@) && $base) { $self->DEBUG("asking base for $name\n") if $DEBUG; eval { $template = $base->template($name) }; } # try the 'notfound' template (if defined) if that failed if (($error = $@) && $notfound) { unless ($template = $self->{ _BLOCKS }->{ $notfound }) { $notfound = $self->template_name($notfound); $self->DEBUG("not found, looking for $notfound\n") if $DEBUG; eval { $template = $context->template($notfound) }; return $context->throw(Template::Constants::ERROR_VIEW, $error) if $@; # return first error } } elsif ($error) { $self->DEBUG("no 'notfound'\n") if $DEBUG; return $context->throw(Template::Constants::ERROR_VIEW, $error); } return $template; } #------------------------------------------------------------------------ # template_name($template) # # Returns the name of the specified template with any appropriate prefix # and/or suffix added. #------------------------------------------------------------------------ sub template_name { my ($self, $template) = @_; $template = $self->{ prefix } . $template . $self->{ suffix } if $template; $self->DEBUG("template name: $template\n") if $DEBUG; return $template; } #------------------------------------------------------------------------ # default($val) # # Special case accessor to retrieve/update 'default' as an alias for # '$map->{ default }'. #------------------------------------------------------------------------ sub default { my $self = shift; return @_ ? ($self->{ map }->{ default } = shift) : $self->{ map }->{ default }; } #------------------------------------------------------------------------ # AUTOLOAD # # Returns/updates public internal data items (i.e. not prefixed '_' or # '.') or presents a view if the method matches the view_prefix item, # e.g. view_foo(...) => view('foo', ...). Similarly, the # include_prefix is used, if defined, to map include_foo(...) to # include('foo', ...). If that fails then the entire method name will # be used as the name of a template to include iff the include_named # parameter is set (default: 1). Last attempt is to match the entire # method name to a view() call, iff view_naked is set. Otherwise, a # 'view' exception is raised reporting the error "no such view member: # $method". #------------------------------------------------------------------------ sub AUTOLOAD { my $self = shift; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; my $starts_with = substr($item,0,1); if ($starts_with eq '.' || $starts_with eq '_') { return $self->{ _CONTEXT }->throw(Template::Constants::ERROR_VIEW, "attempt to view private member: $item"); } elsif (exists $self->{ $item }) { # update existing config item (e.g. 'prefix') if unsealed return $self->{ _CONTEXT }->throw(Template::Constants::ERROR_VIEW, "cannot update config item in sealed view: $item") if @_ && $self->{ SEALED }; $self->DEBUG("accessing item: $item\n") if $DEBUG; return @_ ? ($self->{ $item } = shift) : $self->{ $item }; } elsif (exists $self->{ data }->{ $item }) { # get/update existing data item (must be unsealed to update) if (@_ && $self->{ SEALED }) { return $self->{ _CONTEXT }->throw( Template::Constants::ERROR_VIEW, "cannot update item in sealed view: $item" ) unless $self->{ silent }; # ignore args if silent @_ = (); } $self->DEBUG(@_ ? "updating data item: $item <= $_[0]\n" : "returning data item: $item\n" ) if $DEBUG; return @_ ? ($self->{ data }->{ $item } = shift) : $self->{ data }->{ $item }; } elsif (@_ && ! $self->{ SEALED }) { # set data item if unsealed $self->DEBUG("setting unsealed data: $item => @_\n") if $DEBUG; $self->{ data }->{ $item } = shift; } elsif ($item =~ s/^$self->{ view_prefix }//) { $self->DEBUG("returning view($item)\n") if $DEBUG; return $self->view($item, @_); } elsif ($item =~ s/^$self->{ include_prefix }//) { $self->DEBUG("returning include($item)\n") if $DEBUG; return $self->include($item, @_); } elsif ($self->{ include_naked }) { $self->DEBUG("returning naked include($item)\n") if $DEBUG; return $self->include($item, @_); } elsif ($self->{ view_naked }) { $self->DEBUG("returning naked view($item)\n") if $DEBUG; return $self->view($item, @_); } else { return $self->{ _CONTEXT }->throw( Template::Constants::ERROR_VIEW, "no such view member: $item" ); } } 1; __END__ =head1 NAME Template::View - customised view of a template processing context =head1 SYNOPSIS # define a view [% VIEW view # some standard args prefix => 'my_', suffix => '.tt2', notfound => 'no_such_file' ... # any other data title => 'My View title' other_item => 'Joe Random Data' ... %] # add new data definitions, via 'my' self reference [% my.author = "$abw.name <$abw.email>" %] [% my.copy = "© Copyright 2000 $my.author" %] # define a local block [% BLOCK header %] This is the header block, title: [% title or my.title %] [% END %] [% END %] # access data items for view [% view.title %] [% view.other_item %] # access blocks directly ('include_naked' option, set by default) [% view.header %] [% view.header(title => 'New Title') %] # non-local templates have prefix/suffix attached [% view.footer %] # => [% INCLUDE my_footer.tt2 %] # more verbose form of block access [% view.include( 'header', title => 'The Header Title' ) %] [% view.include_header( title => 'The Header Title' ) %] # very short form of above ('include_naked' option, set by default) [% view.header( title => 'The Header Title' ) %] # non-local templates have prefix/suffix attached [% view.footer %] # => [% INCLUDE my_footer.tt2 %] # fallback on the 'notfound' template ('my_no_such_file.tt2') # if template not found [% view.include('missing') %] [% view.include_missing %] [% view.missing %] # print() includes a template relevant to argument type [% view.print("some text") %] # type=TEXT, template='text' [% BLOCK my_text.tt2 %] # 'text' with prefix/suffix Text: [% item %] [% END %] # now print() a hash ref, mapped to 'hash' template [% view.print(some_hash_ref) %] # type=HASH, template='hash' [% BLOCK my_hash.tt2 %] # 'hash' with prefix/suffix hash keys: [% item.keys.sort.join(', ') [% END %] # now print() a list ref, mapped to 'list' template [% view.print(my_list_ref) %] # type=ARRAY, template='list' [% BLOCK my_list.tt2 %] # 'list' with prefix/suffix list: [% item.join(', ') %] [% END %] # print() maps 'My::Object' to 'My_Object' [% view.print(myobj) %] [% BLOCK my_My_Object.tt2 %] [% item.this %], [% item.that %] [% END %] # update mapping table [% view.map.ARRAY = 'my_list_template' %] [% view.map.TEXT = 'my_text_block' %] # change prefix, suffix, item name, etc. [% view.prefix = 'your_' %] [% view.default = 'anyobj' %] ... =head1 DESCRIPTION TODO =head1 METHODS =head2 new($context, \%config) Creates a new Template::View presenting a custom view of the specified $context object. A reference to a hash array of configuration options may be passed as the second argument. =over 4 =item prefix Prefix added to all template names. [% USE view(prefix => 'my_') %] [% view.view('foo', a => 20) %] # => my_foo =item suffix Suffix added to all template names. [% USE view(suffix => '.tt2') %] [% view.view('foo', a => 20) %] # => foo.tt2 =item map Hash array mapping reference types to template names. The print() method uses this to determine which template to use to present any particular item. The TEXT, HASH and ARRAY items default to 'test', 'hash' and 'list' appropriately. [% USE view(map => { ARRAY => 'my_list', HASH => 'your_hash', My::Foo => 'my_foo', } ) %] [% view.print(some_text) %] # => text [% view.print(a_list) %] # => my_list [% view.print(a_hash) %] # => your_hash [% view.print(a_foo) %] # => my_foo [% BLOCK text %] Text: [% item %] [% END %] [% BLOCK my_list %] list: [% item.join(', ') %] [% END %] [% BLOCK your_hash %] hash keys: [% item.keys.sort.join(', ') [% END %] [% BLOCK my_foo %] Foo: [% item.this %], [% item.that %] [% END %] =item method Name of a method which objects passed to print() may provide for presenting themselves to the view. If a specific map entry can't be found for an object reference and it supports the method (default: 'present') then the method will be called, passing the view as an argument. The object can then make callbacks against the view to present itself. package Foo; sub present { my ($self, $view) = @_; return "a regular view of a Foo\n"; } sub debug { my ($self, $view) = @_; return "a debug view of a Foo\n"; } In a template: [% USE view %] [% view.print(my_foo_object) %] # a regular view of a Foo [% USE view(method => 'debug') %] [% view.print(my_foo_object) %] # a debug view of a Foo =item default Default template to use if no specific map entry is found for an item. [% USE view(default => 'my_object') %] [% view.print(objref) %] # => my_object If no map entry or default is provided then the view will attempt to construct a template name from the object class, substituting any sequence of non-word characters to single underscores, e.g. # 'fubar' is an object of class Foo::Bar [% view.print(fubar) %] # => Foo_Bar Any current prefix and suffix will be added to both the default template name and any name constructed from the object class. =item notfound Fallback template to use if any other isn't found. =item item Name of the template variable to which the print() method assigns the current item. Defaults to 'item'. [% USE view %] [% BLOCK list %] [% item.join(', ') %] [% END %] [% view.print(a_list) %] [% USE view(item => 'thing') %] [% BLOCK list %] [% thing.join(', ') %] [% END %] [% view.print(a_list) %] =item view_prefix Prefix of methods which should be mapped to view() by AUTOLOAD. Defaults to 'view_'. [% USE view %] [% view.view_header() %] # => view('header') [% USE view(view_prefix => 'show_me_the_' %] [% view.show_me_the_header() %] # => view('header') =item view_naked Flag to indicate if any attempt should be made to map method names to template names where they don't match the view_prefix. Defaults to 0. [% USE view(view_naked => 1) %] [% view.header() %] # => view('header') =back =head2 print( $obj1, $obj2, ... \%config) TODO =head2 view( $template, \%vars, \%config ); TODO =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut PK � �[�N�Ctp tp lib/Template/Stash.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Stash # # DESCRIPTION # Definition of an object class which stores and manages access to # variables for the Template Toolkit. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Stash; use strict; use warnings; use Template::VMethods; use Template::Exception; use Scalar::Util qw( blessed reftype ); our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $PRIVATE = qr/^[_.]/; our $UNDEF_TYPE = 'var.undef'; our $UNDEF_INFO = 'undefined variable: %s'; # alias _dotop() to dotop() so that we have a consistent method name # between the Perl and XS stash implementations *dotop = \&_dotop; #------------------------------------------------------------------------ # Virtual Methods # # If any of $ROOT_OPS, $SCALAR_OPS, $HASH_OPS or $LIST_OPS are already # defined then we merge their contents with the default virtual methods # define by Template::VMethods. Otherwise we can directly alias the # corresponding Template::VMethod package vars. #------------------------------------------------------------------------ our $ROOT_OPS = defined $ROOT_OPS ? { %{$Template::VMethods::ROOT_VMETHODS}, %$ROOT_OPS } : $Template::VMethods::ROOT_VMETHODS; our $SCALAR_OPS = defined $SCALAR_OPS ? { %{$Template::VMethods::TEXT_VMETHODS}, %$SCALAR_OPS } : $Template::VMethods::TEXT_VMETHODS; our $HASH_OPS = defined $HASH_OPS ? { %{$Template::VMethods::HASH_VMETHODS}, %$HASH_OPS } : $Template::VMethods::HASH_VMETHODS; our $LIST_OPS = defined $LIST_OPS ? { %{$Template::VMethods::LIST_VMETHODS}, %$LIST_OPS } : $Template::VMethods::LIST_VMETHODS; #------------------------------------------------------------------------ # define_vmethod($type, $name, \&sub) # # Defines a virtual method of type $type (SCALAR, HASH, or LIST), with # name $name, that invokes &sub when called. It is expected that &sub # be able to handle the type that it will be called upon. #------------------------------------------------------------------------ sub define_vmethod { my ($class, $type, $name, $sub) = @_; my $op; $type = lc $type; if ($type eq 'scalar' || $type eq 'item') { $op = $SCALAR_OPS; } elsif ($type eq 'hash') { $op = $HASH_OPS; } elsif ($type eq 'list' || $type eq 'array') { $op = $LIST_OPS; } else { die "invalid vmethod type: $type\n"; } $op->{ $name } = $sub; return 1; } #======================================================================== # ----- CLASS METHODS ----- #======================================================================== #------------------------------------------------------------------------ # new(\%params) # # Constructor method which creates a new Template::Stash object. # An optional hash reference may be passed containing variable # definitions that will be used to initialise the stash. # # Returns a reference to a newly created Template::Stash. #------------------------------------------------------------------------ sub new { my $class = shift; my $params = ref $_[0] eq 'HASH' ? shift(@_) : { @_ }; my $self = { global => { }, %$params, %$ROOT_OPS, '_PARENT' => undef, }; bless $self, $class; } #======================================================================== # ----- PUBLIC OBJECT METHODS ----- #======================================================================== #------------------------------------------------------------------------ # clone(\%params) # # Creates a copy of the current stash object to effect localisation # of variables. The new stash is blessed into the same class as the # parent (which may be a derived class) and has a '_PARENT' member added # which contains a reference to the parent stash that created it # ($self). This member is used in a successive declone() method call to # return the reference to the parent. # # A parameter may be provided which should reference a hash of # variable/values which should be defined in the new stash. The # update() method is called to define these new variables in the cloned # stash. # # Returns a reference to a cloned Template::Stash. #------------------------------------------------------------------------ sub clone { my ($self, $params) = @_; $params ||= { }; # look out for magical 'import' argument which imports another hash my $import = $params->{ import }; if (ref $import eq 'HASH') { delete $params->{ import }; } else { undef $import; } my $clone = bless { %$self, # copy all parent members %$params, # copy all new data '_PARENT' => $self, # link to parent }, ref $self; # perform hash import if defined &{ $HASH_OPS->{ import } }($clone, $import) if defined $import; return $clone; } #------------------------------------------------------------------------ # declone($export) # # Returns a reference to the PARENT stash. When called in the following # manner: # $stash = $stash->declone(); # the reference count on the current stash will drop to 0 and be "freed" # and the caller will be left with a reference to the parent. This # contains the state of the stash before it was cloned. #------------------------------------------------------------------------ sub declone { my $self = shift; $self->{ _PARENT } || $self; } #------------------------------------------------------------------------ # get($ident) # # Returns the value for an variable stored in the stash. The variable # may be specified as a simple string, e.g. 'foo', or as an array # reference representing compound variables. In the latter case, each # pair of successive elements in the list represent a node in the # compound variable. The first is the variable name, the second a # list reference of arguments or 0 if undefined. So, the compound # variable [% foo.bar('foo').baz %] would be represented as the list # [ 'foo', 0, 'bar', ['foo'], 'baz', 0 ]. Returns the value of the # identifier or an empty string if undefined. Errors are thrown via # die(). #------------------------------------------------------------------------ sub get { my ($self, $ident, $args) = @_; my ($root, $result); $root = $self; if (ref $ident eq 'ARRAY' || (index($ident,'.') > -1) && ($ident = [ map { s/\(.*$//; ($_, 0) } split(/\./, $ident) ])) { my $size = $#$ident; # if $ident is a list reference, then we evaluate each item in the # identifier against the previous result, using the root stash # ($self) as the first implicit 'result'... foreach (my $i = 0; $i <= $size; $i += 2) { $result = $self->_dotop($root, @$ident[$i, $i+1]); last unless defined $result; $root = $result; } } else { $result = $self->_dotop($root, $ident, $args); } return defined $result ? $result : $self->undefined($ident, $args); } #------------------------------------------------------------------------ # set($ident, $value, $default) # # Updates the value for a variable in the stash. The first parameter # should be the variable name or array, as per get(). The second # parameter should be the intended value for the variable. The third, # optional parameter is a flag which may be set to indicate 'default' # mode. When set true, the variable will only be updated if it is # currently undefined or has a false value. The magical 'IMPORT' # variable identifier may be used to indicate that $value is a hash # reference whose values should be imported. Returns the value set, # or an empty string if not set (e.g. default mode). In the case of # IMPORT, returns the number of items imported from the hash. #------------------------------------------------------------------------ sub set { my ($self, $ident, $value, $default) = @_; my ($root, $result, $error); $root = $self; ELEMENT: { if (ref $ident eq 'ARRAY' || (index($ident,'.') != -1) # has a '.' in it somewhere && ($ident = [ map { s/\(.*$//; ($_, 0) } split(/\./, $ident) ])) { # a compound identifier may contain multiple elements (e.g. # foo.bar.baz) and we must first resolve all but the last, # using _dotop() with the $lvalue flag set which will create # intermediate hashes if necessary... my $size = $#$ident; foreach (my $i = 0; $i < $size - 2; $i += 2) { $result = $self->_dotop($root, @$ident[$i, $i+1], 1); last ELEMENT unless defined $result; $root = $result; } # then we call _assign() to assign the value to the last element $result = $self->_assign( $root, @$ident[$size-1, $size], $value, $default ); } else { $result = $self->_assign($root, $ident, 0, $value, $default); } } return defined $result ? $result : ''; } #------------------------------------------------------------------------ # getref($ident) # # Returns a "reference" to a particular item. This is represented as a # closure which will return the actual stash item when called. #------------------------------------------------------------------------ sub getref { my ($self, $ident, $args) = @_; my ($root, $item, $result); $root = $self; if (ref $ident eq 'ARRAY') { my $size = $#$ident; foreach (my $i = 0; $i <= $size; $i += 2) { ($item, $args) = @$ident[$i, $i + 1]; last if $i >= $size - 2; # don't evaluate last node last unless defined ($root = $self->_dotop($root, $item, $args)); } } else { $item = $ident; } if (defined $root) { return sub { my @args = (@{$args||[]}, @_); $self->_dotop($root, $item, \@args); } } else { return sub { '' }; } } #------------------------------------------------------------------------ # update(\%params) # # Update multiple variables en masse. No magic is performed. Simple # variable names only. #------------------------------------------------------------------------ sub update { my ($self, $params) = @_; # look out for magical 'import' argument to import another hash my $import = $params->{ import }; if (ref $import eq 'HASH') { @$self{ keys %$import } = values %$import; delete $params->{ import }; } @$self{ keys %$params } = values %$params; } #------------------------------------------------------------------------ # undefined($ident, $args) # # Method called when a get() returns an undefined value. Can be redefined # in a subclass to implement alternate handling. #------------------------------------------------------------------------ sub undefined { my ($self, $ident, $args) = @_; if ($self->{ _STRICT }) { # Sorry, but we can't provide a sensible source file and line without # re-designing the whole architecture of TT (see TT3) die Template::Exception->new( $UNDEF_TYPE, sprintf( $UNDEF_INFO, $self->_reconstruct_ident($ident) ) ) if $self->{ _STRICT }; } else { # There was a time when I thought this was a good idea. But it's not. return ''; } } sub _reconstruct_ident { my ($self, $ident) = @_; my ($name, $args, @output); my @input = ref $ident eq 'ARRAY' ? @$ident : ($ident); while (@input) { $name = shift @input; $args = shift @input || 0; $name .= '(' . join(', ', map { /^\d+$/ ? $_ : "'$_'" } @$args) . ')' if $args && ref $args eq 'ARRAY'; push(@output, $name); } return join('.', @output); } #======================================================================== # ----- PRIVATE OBJECT METHODS ----- #======================================================================== #------------------------------------------------------------------------ # _dotop($root, $item, \@args, $lvalue) # # This is the core 'dot' operation method which evaluates elements of # variables against their root. All variables have an implicit root # which is the stash object itself (a hash). Thus, a non-compound # variable 'foo' is actually '(stash.)foo', the compound 'foo.bar' is # '(stash.)foo.bar'. The first parameter is a reference to the current # root, initially the stash itself. The second parameter contains the # name of the variable element, e.g. 'foo'. The third optional # parameter is a reference to a list of any parenthesised arguments # specified for the variable, which are passed to sub-routines, object # methods, etc. The final parameter is an optional flag to indicate # if this variable is being evaluated on the left side of an assignment # (e.g. foo.bar.baz = 10). When set true, intermediated hashes will # be created (e.g. bar) if necessary. # # Returns the result of evaluating the item against the root, having # performed any variable "magic". The value returned can then be used # as the root of the next _dotop() in a compound sequence. Returns # undef if the variable is undefined. #------------------------------------------------------------------------ sub _dotop { my ($self, $root, $item, $args, $lvalue) = @_; my $rootref = ref $root; my $atroot = (blessed $root && $root->isa(ref $self)); my ($value, @result); $args ||= [ ]; $lvalue ||= 0; # print STDERR "_dotop(root=$root, item=$item, args=[@$args])\n" # if $DEBUG; # return undef without an error if either side of the dot is unviable return undef unless defined($root) and defined($item); # or if an attempt is made to access a private member, starting _ or . return undef if $PRIVATE && $item =~ /$PRIVATE/; if ($atroot || $rootref eq 'HASH') { # if $root is a regular HASH or a Template::Stash kinda HASH (the # *real* root of everything). We first lookup the named key # in the hash, or create an empty hash in its place if undefined # and the $lvalue flag is set. Otherwise, we check the HASH_OPS # pseudo-methods table, calling the code if found, or return undef. if (defined($value = $root->{ $item })) { return $value unless ref $value eq 'CODE'; ## RETURN @result = &$value(@$args); ## @result } elsif ($lvalue) { # we create an intermediate hash if this is an lvalue return $root->{ $item } = { }; ## RETURN } # ugly hack: only allow import vmeth to be called on root stash elsif (($value = $HASH_OPS->{ $item }) && ! $atroot || $item eq 'import') { @result = &$value($root, @$args); ## @result } elsif ( ref $item eq 'ARRAY' ) { # hash slice return [@$root{@$item}]; ## RETURN } } elsif ($rootref eq 'ARRAY') { # if root is an ARRAY then we check for a LIST_OPS pseudo-method # or return the numerical index into the array, or undef if ($value = $LIST_OPS->{ $item }) { @result = &$value($root, @$args); ## @result } elsif ($item =~ /^-?\d+$/) { $value = $root->[$item]; return $value unless ref $value eq 'CODE'; ## RETURN @result = &$value(@$args); ## @result } elsif ( ref $item eq 'ARRAY' ) { # array slice return [@$root[@$item]]; ## RETURN } } # NOTE: we do the can-can because UNIVSERAL::isa($something, 'UNIVERSAL') # doesn't appear to work with CGI, returning true for the first call # and false for all subsequent calls. # UPDATE: that doesn't appear to be the case any more elsif (blessed($root) && $root->can('can')) { # if $root is a blessed reference (i.e. inherits from the # UNIVERSAL object base class) then we call the item as a method. # If that fails then we try to fallback on HASH behaviour if # possible. eval { @result = $root->$item(@$args); }; if ($@) { # temporary hack - required to propagate errors thrown # by views; if $@ is a ref (e.g. Template::Exception # object then we assume it's a real error that needs # real throwing my $class = ref($root) || $root; # Fail only if the function exists die $@ if ( ref($@) || $root->can($item) ); # failed to call object method, so try some fallbacks if (reftype $root eq 'HASH') { if( defined($value = $root->{ $item })) { return $value unless ref $value eq 'CODE'; ## RETURN @result = &$value(@$args); } elsif ($value = $HASH_OPS->{ $item }) { @result = &$value($root, @$args); } elsif ($value = $LIST_OPS->{ $item }) { @result = &$value([$root], @$args); } } elsif (reftype $root eq 'ARRAY') { if( $value = $LIST_OPS->{ $item }) { @result = &$value($root, @$args); } elsif( $item =~ /^-?\d+$/ ) { $value = $root->[$item]; return $value unless ref $value eq 'CODE'; ## RETURN @result = &$value(@$args); ## @result } elsif ( ref $item eq 'ARRAY' ) { # array slice return [@$root[@$item]]; ## RETURN } } elsif ($value = $SCALAR_OPS->{ $item }) { @result = &$value($root, @$args); } elsif ($value = $LIST_OPS->{ $item }) { @result = &$value([$root], @$args); } elsif ($self->{ _DEBUG }) { @result = (undef, $@); } } } elsif (($value = $SCALAR_OPS->{ $item }) && ! $lvalue) { # at this point, it doesn't look like we've got a reference to # anything we know about, so we try the SCALAR_OPS pseudo-methods # table (but not for l-values) @result = &$value($root, @$args); ## @result } elsif (($value = $LIST_OPS->{ $item }) && ! $lvalue) { # last-ditch: can we promote a scalar to a one-element # list and apply a LIST_OPS virtual method? @result = &$value([$root], @$args); } elsif ($self->{ _DEBUG }) { die "don't know how to access [ $root ].$item\n"; ## DIE } else { @result = (); } # fold multiple return items into a list unless first item is undef if (defined $result[0]) { return ## RETURN scalar @result > 1 ? [ @result ] : $result[0]; } elsif (defined $result[1]) { die $result[1]; ## DIE } elsif ($self->{ _DEBUG }) { die "$item is undefined\n"; ## DIE } return undef; } #------------------------------------------------------------------------ # _assign($root, $item, \@args, $value, $default) # # Similar to _dotop() above, but assigns a value to the given variable # instead of simply returning it. The first three parameters are the # root item, the item and arguments, as per _dotop(), followed by the # value to which the variable should be set and an optional $default # flag. If set true, the variable will only be set if currently false # (undefined/zero) #------------------------------------------------------------------------ sub _assign { my ($self, $root, $item, $args, $value, $default) = @_; my $rootref = ref $root; my $atroot = ($root eq $self); my $result; $args ||= [ ]; $default ||= 0; # return undef without an error if either side of the dot is unviable return undef unless $root and defined $item; # or if an attempt is made to update a private member, starting _ or . return undef if $PRIVATE && $item =~ /$PRIVATE/; if ($rootref eq 'HASH' || $atroot) { # if the root is a hash we set the named key return ($root->{ $item } = $value) ## RETURN unless $default && $root->{ $item }; } elsif ($rootref eq 'ARRAY' && $item =~ /^-?\d+$/) { # or set a list item by index number return ($root->[$item] = $value) ## RETURN unless $default && $root->{ $item }; } elsif (blessed($root)) { # try to call the item as a method of an object return $root->$item(@$args, $value) ## RETURN unless $default && $root->$item(); # 2 issues: # - method call should be wrapped in eval { } # - fallback on hash methods if object method not found # # eval { $result = $root->$item(@$args, $value); }; # # if ($@) { # die $@ if ref($@) || ($@ !~ /Can't locate object method/); # # # failed to call object method, so try some fallbacks # if (UNIVERSAL::isa($root, 'HASH') && exists $root->{ $item }) { # $result = ($root->{ $item } = $value) # unless $default && $root->{ $item }; # } # } # return $result; ## RETURN } else { die "don't know how to assign to [$root].[$item]\n"; ## DIE } return undef; } 1; __END__ =head1 NAME Template::Stash - Magical storage for template variables =head1 SYNOPSIS use Template::Stash; my $stash = Template::Stash->new(\%vars); # get variable values $value = $stash->get($variable); $value = $stash->get(\@compound); # set variable value $stash->set($variable, $value); $stash->set(\@compound, $value); # default variable value $stash->set($variable, $value, 1); $stash->set(\@compound, $value, 1); # set variable values en masse $stash->update(\%new_vars) # methods for (de-)localising variables $stash = $stash->clone(\%new_vars); $stash = $stash->declone(); =head1 DESCRIPTION The C<Template::Stash> module defines an object class which is used to store variable values for the runtime use of the template processor. Variable values are stored internally in a hash reference (which itself is blessed to create the object) and are accessible via the L<get()> and L<set()> methods. Variables may reference hash arrays, lists, subroutines and objects as well as simple values. The stash automatically performs the right magic when dealing with variables, calling code or object methods, indexing into lists, hashes, etc. The stash has L<clone()> and L<declone()> methods which are used by the template processor to make temporary copies of the stash for localising changes made to variables. =head1 PUBLIC METHODS =head2 new(\%params) The C<new()> constructor method creates and returns a reference to a new C<Template::Stash> object. my $stash = Template::Stash->new(); A hash reference may be passed to provide variables and values which should be used to initialise the stash. my $stash = Template::Stash->new({ var1 => 'value1', var2 => 'value2' }); =head2 get($variable) The C<get()> method retrieves the variable named by the first parameter. $value = $stash->get('var1'); Dotted compound variables can be retrieved by specifying the variable elements by reference to a list. Each node in the variable occupies two entries in the list. The first gives the name of the variable element, the second is a reference to a list of arguments for that element, or C<0> if none. [% foo.bar(10).baz(20) %] $stash->get([ 'foo', 0, 'bar', [ 10 ], 'baz', [ 20 ] ]); =head2 set($variable, $value, $default) The C<set()> method sets the variable name in the first parameter to the value specified in the second. $stash->set('var1', 'value1'); If the third parameter evaluates to a true value, the variable is set only if it did not have a true value before. $stash->set('var2', 'default_value', 1); Dotted compound variables may be specified as per L<get()> above. [% foo.bar = 30 %] $stash->set([ 'foo', 0, 'bar', 0 ], 30); The magical variable 'C<IMPORT>' can be specified whose corresponding value should be a hash reference. The contents of the hash array are copied (i.e. imported) into the current namespace. # foo.bar = baz, foo.wiz = waz $stash->set('foo', { 'bar' => 'baz', 'wiz' => 'waz' }); # import 'foo' into main namespace: bar = baz, wiz = waz $stash->set('IMPORT', $stash->get('foo')); =head2 update($variables) This method can be used to set or update several variables in one go. $stash->update({ foo => 10, bar => 20, }); =head2 getref($variable) This undocumented feature returns a closure which can be called to get the value of a variable. It is used to implement variable references which are evaluated lazily. [% x = \foo.bar.baz %] # x is a reference to foo.bar.baz [% x %] # evalautes foo.bar.baz =head2 clone(\%params) The C<clone()> method creates and returns a new C<Template::Stash> object which represents a localised copy of the parent stash. Variables can be freely updated in the cloned stash and when L<declone()> is called, the original stash is returned with all its members intact and in the same state as they were before C<clone()> was called. For convenience, a hash of parameters may be passed into C<clone()> which is used to update any simple variable (i.e. those that don't contain any namespace elements like C<foo> and C<bar> but not C<foo.bar>) variables while cloning the stash. For adding and updating complex variables, the L<set()> method should be used after calling C<clone().> This will correctly resolve and/or create any necessary namespace hashes. A cloned stash maintains a reference to the stash that it was copied from in its C<_PARENT> member. =head2 declone() The C<declone()> method returns the C<_PARENT> reference and can be used to restore the state of a stash as described above. =head2 define_vmethod($type, $name, $code) This method can be used to define new virtual methods. The first argument should be either C<scalar> or C<item> to define scalar virtual method, C<hash> to define hash virtual methods, or either C<array> or C<list> for list virtual methods. The second argument should be the name of the new method. The third argument should be a reference to a subroutine implementing the method. The data item on which the virtual method is called is passed to the subroutine as the first argument. $stash->define_vmethod( item => ucfirst => sub { my $text = shift; return ucfirst $text } ); =head1 INTERNAL METHODS =head2 dotop($root, $item, \@args, $lvalue) This is the core C<dot> operation method which evaluates elements of variables against their root. =head2 undefined($ident, $args) This method is called when L<get()> encounters an undefined value. If the L<STRICT|Template::Manual::Config#STRICT> option is in effect then it will throw an exception indicating the use of an undefined value. Otherwise it will silently return an empty string. The method can be redefined in a subclass to implement alternate handling of undefined values. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Context> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[� ҄�� �� lib/Template/Parser.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Parser # # DESCRIPTION # This module implements a LALR(1) parser and associated support # methods to parse template documents into the appropriate "compiled" # format. Much of the parser DFA code (see _parse() method) is based # on Francois Desarmenien's Parse::Yapp module. Kudos to him. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # The following copyright notice appears in the Parse::Yapp # documentation. # # The Parse::Yapp module and its related modules and shell # scripts are copyright (c) 1998 Francois Desarmenien, # France. All rights reserved. # # You may use and distribute them under the terms of either # the GNU General Public License or the Artistic License, as # specified in the Perl README file. # #============================================================================ package Template::Parser; use strict; use warnings; use base 'Template::Base'; use Template::Constants qw( :status :chomp ); use Template::Directive; use Template::Grammar; # parser state constants use constant CONTINUE => 0; use constant ACCEPT => 1; use constant ERROR => 2; use constant ABORT => 3; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $ERROR = ''; # The ANYCASE option can cause conflicts when reserved words are used as # variable names, hash keys, template names, plugin names, etc. The # # $ANYCASE_BEFORE regex identifies where such a word precedes an assignment, # either as a variable (C<wrapper = 'html'>) or hash key (C<{ wrapper => 'html' }). # In that case it is treated as a simple words rather than being the lower case # equivalent of the upper case keyword (e.g. WRAPPER). # # $ANYCASE_AFTER is used to identify when such a word follows a symbols that # suggests it can't be a keyword, e.g. after BLOCK INCLUDE WRAPPER, USE, etc. our $ANYCASE_BEFORE = qr/\G((?=\s*[=\.]))/; our $ANYCASE_AFTER = { map { $_ => 1 } qw( GET SET CALL DEFAULT INSERT INCLUDE PROCESS WRAPPER BLOCK USE PLUGIN FILTER MACRO IN TO STEP AND OR NOT DIV MOD DOT IF UNLESS ELSIF FOR WHILE SWITCH CASE META THROW CATCH VIEW CMPOP BINOP COMMA ), '(', '[', '{' # not sure about ASSIGN as it breaks C<header_html = include header> }; #======================================================================== # -- COMMON TAG STYLES -- #======================================================================== our $TAG_STYLE = { 'outline' => [ '\[%', '%\]', '%%' ], # NEW! Outline tag 'default' => [ '\[%', '%\]' ], 'template1' => [ '[\[%]%', '%[\]%]' ], 'metatext' => [ '%%', '%%' ], 'html' => [ '<!--', '-->' ], 'mason' => [ '<%', '>' ], 'asp' => [ '<%', '%>' ], 'php' => [ '<\?', '\?>' ], 'star' => [ '\[\*', '\*\]' ], }; $TAG_STYLE->{ template } = $TAG_STYLE->{ tt2 } = $TAG_STYLE->{ default }; our $DEFAULT_STYLE = { START_TAG => $TAG_STYLE->{ default }->[0], END_TAG => $TAG_STYLE->{ default }->[1], OUTLINE_TAG => $TAG_STYLE->{ default }->[2], # TAG_STYLE => 'default', ANYCASE => 0, INTERPOLATE => 0, PRE_CHOMP => 0, POST_CHOMP => 0, V1DOLLAR => 0, EVAL_PERL => 0, }; our $QUOTED_ESCAPES = { n => "\n", r => "\r", t => "\t", }; # note that '-' must come first so Perl doesn't think it denotes a range our $CHOMP_FLAGS = qr/[-=~+]/; #======================================================================== # ----- PUBLIC METHODS ----- #======================================================================== #------------------------------------------------------------------------ # new(\%config) # # Constructor method. #------------------------------------------------------------------------ sub new { my $class = shift; my $config = $_[0] && ref($_[0]) eq 'HASH' ? shift(@_) : { @_ }; my ($tagstyle, $debug, $start, $end, $defaults, $grammar, $hash, $key, $udef); my $self = bless { START_TAG => undef, END_TAG => undef, OUTLINE_TAG => undef, TAG_STYLE => 'default', ANYCASE => 0, INTERPOLATE => 0, PRE_CHOMP => 0, POST_CHOMP => 0, V1DOLLAR => 0, EVAL_PERL => 0, FILE_INFO => 1, GRAMMAR => undef, _ERROR => '', IN_BLOCK => [ ], TRACE_VARS => $config->{ TRACE_VARS }, FACTORY => $config->{ FACTORY } || 'Template::Directive', }, $class; # update self with any relevant keys in config foreach $key (keys %$self) { $self->{ $key } = $config->{ $key } if defined $config->{ $key }; } $self->{ FILEINFO } = [ ]; # DEBUG config item can be a bitmask if (defined ($debug = $config->{ DEBUG })) { $self->{ DEBUG } = $debug & ( Template::Constants::DEBUG_PARSER | Template::Constants::DEBUG_FLAGS ); $self->{ DEBUG_DIRS } = $debug & Template::Constants::DEBUG_DIRS; } # package variable can be set to 1 to support previous behaviour elsif ($DEBUG == 1) { $self->{ DEBUG } = Template::Constants::DEBUG_PARSER; $self->{ DEBUG_DIRS } = 0; } # otherwise let $DEBUG be a bitmask else { $self->{ DEBUG } = $DEBUG & ( Template::Constants::DEBUG_PARSER | Template::Constants::DEBUG_FLAGS ); $self->{ DEBUG_DIRS } = $DEBUG & Template::Constants::DEBUG_DIRS; } $grammar = $self->{ GRAMMAR } ||= do { require Template::Grammar; Template::Grammar->new(); }; # instantiate a FACTORY object unless (ref $self->{ FACTORY }) { my $fclass = $self->{ FACTORY }; $self->{ FACTORY } = $self->{ FACTORY }->new( NAMESPACE => $config->{ NAMESPACE } ) || return $class->error($self->{ FACTORY }->error()); } # load grammar rules, states and lex table @$self{ qw( LEXTABLE STATES RULES ) } = @$grammar{ qw( LEXTABLE STATES RULES ) }; $self->new_style($config) || return $class->error($self->error()); return $self; } #----------------------------------------------------------------------- # These methods are used to track nested IF and WHILE blocks. Each # generated if/while block is given a label indicating the directive # type and nesting depth, e.g. FOR0, WHILE1, FOR2, WHILE3, etc. The # NEXT and LAST directives use the innermost label, e.g. last WHILE3; #----------------------------------------------------------------------- sub enter_block { my ($self, $name) = @_; my $blocks = $self->{ IN_BLOCK }; push(@{ $self->{ IN_BLOCK } }, $name); } sub leave_block { my $self = shift; my $label = $self->block_label; pop(@{ $self->{ IN_BLOCK } }); return $label; } sub in_block { my ($self, $name) = @_; my $blocks = $self->{ IN_BLOCK }; return @$blocks && $blocks->[-1] eq $name; } sub block_label { my ($self, $prefix, $suffix) = @_; my $blocks = $self->{ IN_BLOCK }; my $name = @$blocks ? $blocks->[-1] . scalar @$blocks : undef; return join('', grep { defined $_ } $prefix, $name, $suffix); } #------------------------------------------------------------------------ # new_style(\%config) # # Install a new (stacked) parser style. This feature is currently # experimental but should mimic the previous behaviour with regard to # TAG_STYLE, START_TAG, END_TAG, etc. #------------------------------------------------------------------------ sub new_style { my ($self, $config) = @_; my $styles = $self->{ STYLE } ||= [ ]; my ($tagstyle, $tags, $start, $end, $out, $key); # clone new style from previous or default style my $style = { %{ $styles->[-1] || $DEFAULT_STYLE } }; # expand START_TAG and END_TAG from specified TAG_STYLE if ($tagstyle = $config->{ TAG_STYLE }) { return $self->error("Invalid tag style: $tagstyle") unless defined ($tags = $TAG_STYLE->{ $tagstyle }); ($start, $end, $out) = @$tags; $config->{ START_TAG } ||= $start; $config->{ END_TAG } ||= $end; $config->{ OUTLINE_TAG } ||= $out; } foreach $key (keys %$DEFAULT_STYLE) { $style->{ $key } = $config->{ $key } if defined $config->{ $key }; } $start = $style->{ START_TAG }; $end = $style->{ END_TAG }; $out = $style->{ OUTLINE_TAG }; $style->{ TEXT_SPLIT } = $self->text_splitter($start, $end, $out); push(@$styles, $style); return $style; } sub text_splitter { my ($self, $start, $end, $out) = @_; if (defined $out) { return qr/ \A(.*?) # $1 - start of line up to directive (?: (?: ^$out # outline tag at start of line (.*? # $2 - content of that line (?:\n|$) # end of that line or file ) ) | (?: $start # start of tag (.*?) # $3 - tag contents $end # end of tag ) ) /msx; } else { return qr/ ^(.*?) # $1 - start of line up to directive (?: $start # start of tag (.*?) # $2 - tag contents $end # end of tag ) /sx; } } #------------------------------------------------------------------------ # old_style() # # Pop the current parser style and revert to the previous one. See # new_style(). ** experimental ** #------------------------------------------------------------------------ sub old_style { my $self = shift; my $styles = $self->{ STYLE }; return $self->error('only 1 parser style remaining') unless (@$styles > 1); pop @$styles; return $styles->[-1]; } #------------------------------------------------------------------------ # parse($text, $data) # # Parses the text string, $text and returns a hash array representing # the compiled template block(s) as Perl code, in the format expected # by Template::Document. #------------------------------------------------------------------------ sub parse { my ($self, $text, $info) = @_; my ($tokens, $block); $info->{ DEBUG } = $self->{ DEBUG_DIRS } unless defined $info->{ DEBUG }; # print "info: { ", join(', ', map { "$_ => $info->{ $_ }" } keys %$info), " }\n"; # store for blocks defined in the template (see define_block()) my $defblock = $self->{ DEFBLOCK } = { }; my $metadata = $self->{ METADATA } = [ ]; my $variables = $self->{ VARIABLES } = { }; $self->{ DEFBLOCKS } = [ ]; $self->{ _ERROR } = ''; # split file into TEXT/DIRECTIVE chunks $tokens = $self->split_text($text) || return undef; ## RETURN ## push(@{ $self->{ FILEINFO } }, $info); # parse chunks $block = $self->_parse($tokens, $info); pop(@{ $self->{ FILEINFO } }); return undef unless $block; ## RETURN ## $self->debug("compiled main template document block:\n$block") if $self->{ DEBUG } & Template::Constants::DEBUG_PARSER; return { BLOCK => $block, DEFBLOCKS => $defblock, VARIABLES => $variables, METADATA => { @$metadata }, }; } #------------------------------------------------------------------------ # split_text($text) # # Split input template text into directives and raw text chunks. #------------------------------------------------------------------------ sub split_text { my ($self, $text) = @_; my ($pre, $dir, $prelines, $dirlines, $postlines, $chomp, $tags, @tags); my $style = $self->{ STYLE }->[-1]; my ($start, $end, $out, $prechomp, $postchomp, $interp ) = @$style{ qw( START_TAG END_TAG OUTLINE_TAG PRE_CHOMP POST_CHOMP INTERPOLATE ) }; my $tags_dir = $self->{ANYCASE} ? qr<TAGS>i : qr<TAGS>; my $split = $style->{ TEXT_SPLIT }; my $has_out = defined $out; my @tokens = (); my $line = 1; return \@tokens ## RETURN ## unless defined $text && length $text; # extract all directives from the text while ($text =~ s/$split//) { $pre = $1; $dir = defined($2) ? $2 : $3; $pre = '' unless defined $pre; $dir = '' unless defined $dir; $prelines = ($pre =~ tr/\n//); # newlines in preceding text $dirlines = ($dir =~ tr/\n//); # newlines in directive tag $postlines = 0; # newlines chomped after tag for ($dir) { if (/^\#/) { # comment out entire directive except for any end chomp flag $dir = ($dir =~ /($CHOMP_FLAGS)$/o) ? $1 : ''; } else { if(s/^($CHOMP_FLAGS)?(\s*)//so && $2) { my $chomped = $2; my $linecount = ($chomped =~ tr/\n//); # newlines in chomped whitespace $linecount ||= 0; $prelines += $linecount; $dirlines -= $linecount; } # PRE_CHOMP: process whitespace before tag $chomp = $1 ? $1 : $prechomp; $chomp =~ tr/-=~+/1230/; if ($chomp && $pre) { # chomp off whitespace and newline preceding directive if ($chomp == CHOMP_ALL) { $pre =~ s{ (\r?\n|^) [^\S\n]* \z }{}mx; } elsif ($chomp == CHOMP_COLLAPSE) { $pre =~ s{ (\s+) \z }{ }x; } elsif ($chomp == CHOMP_GREEDY) { $pre =~ s{ (\s+) \z }{}x; } } } # POST_CHOMP: process whitespace after tag s/\s*($CHOMP_FLAGS)?\s*$//so; $chomp = $1 ? $1 : $postchomp; $chomp =~ tr/-=~+/1230/; if ($chomp) { if ($chomp == CHOMP_ALL) { $text =~ s{ ^ ([^\S\n]* \n) }{}x && $postlines++; } elsif ($chomp == CHOMP_COLLAPSE) { $text =~ s{ ^ (\s+) }{ }x && ($postlines += $1=~y/\n//); } # any trailing whitespace elsif ($chomp == CHOMP_GREEDY) { $text =~ s{ ^ (\s+) }{}x && ($postlines += $1=~y/\n//); } } } # any text preceding the directive can now be added if (length $pre) { push(@tokens, $interp ? [ $pre, $line, 'ITEXT' ] : ('TEXT', $pre) ); } $line += $prelines; # and now the directive, along with line number information if (length $dir) { # the TAGS directive is a compile-time switch if ($dir =~ /^$tags_dir\s+(.*)/) { my @tags = split(/\s+/, $1); if (scalar @tags > 1) { ($start, $end, $out) = map { quotemeta($_) } @tags; $split = $self->text_splitter($start, $end, $out); } elsif ($tags = $TAG_STYLE->{ $tags[0] }) { ($start, $end, $out) = @$tags; $split = $self->text_splitter($start, $end, $out); } else { warn "invalid TAGS style: $tags[0]\n"; } } else { # DIRECTIVE is pushed as: # [ $dirtext, $line_no(s), \@tokens ] push(@tokens, [ $dir, ($dirlines ? sprintf("%d-%d", $line, $line + $dirlines) : $line), $self->tokenise_directive($dir) ]); } } # update line counter to include directive lines and any extra # newline chomped off the start of the following text $line += $dirlines + $postlines; } # anything remaining in the string is plain text push(@tokens, $interp ? [ $text, $line, 'ITEXT' ] : ( 'TEXT', $text) ) if length $text; return \@tokens; ## RETURN ## } #------------------------------------------------------------------------ # interpolate_text($text, $line) # # Examines $text looking for any variable references embedded like # $this or like ${ this }. #------------------------------------------------------------------------ sub interpolate_text { my ($self, $text, $line) = @_; my @tokens = (); my ($pre, $var, $dir); while ($text =~ / ( (?: \\. | [^\$] ){1,3000} ) # escaped or non-'$' character [$1] | ( \$ (?: # embedded variable [$2] (?: \{ ([^\}]*) \} ) # ${ ... } [$3] | ([\w\.]+) # $word [$4] ) ) /gx) { ($pre, $var, $dir) = ($1, $3 || $4, $2); # preceding text if (defined($pre) && length($pre)) { $line += $pre =~ tr/\n//; $pre =~ s/\\\$/\$/g; push(@tokens, 'TEXT', $pre); } # $variable reference if ($var) { $line += $dir =~ tr/\n/ /; push(@tokens, [ $dir, $line, $self->tokenise_directive($var) ]); } # other '$' reference - treated as text elsif ($dir) { $line += $dir =~ tr/\n//; push(@tokens, 'TEXT', $dir); } } return \@tokens; } #------------------------------------------------------------------------ # tokenise_directive($text) # # Called by the private _parse() method when it encounters a DIRECTIVE # token in the list provided by the split_text() or interpolate_text() # methods. The directive text is passed by parameter. # # The method splits the directive into individual tokens as recognised # by the parser grammar (see Template::Grammar for details). It # constructs a list of tokens each represented by 2 elements, as per # split_text() et al. The first element contains the token type, the # second the token itself. # # The method tokenises the string using a complex (but fast) regex. # For a deeper understanding of the regex magic at work here, see # Jeffrey Friedl's excellent book "Mastering Regular Expressions", # from O'Reilly, ISBN 1-56592-257-3 # # Returns a reference to the list of chunks (each one being 2 elements) # identified in the directive text. On error, the internal _ERROR string # is set and undef is returned. #------------------------------------------------------------------------ sub tokenise_directive { my ($self, $text, $line) = @_; my ($token, $uctoken, $type, $lookup); my $lextable = $self->{ LEXTABLE }; my $style = $self->{ STYLE }->[-1]; my ($anycase, $start, $end) = @$style{ qw( ANYCASE START_TAG END_TAG ) }; my @tokens = ( ); while ($text =~ / # strip out any comments (\#[^\n]*) | # a quoted phrase matches in $3 (["']) # $2 - opening quote, ' or " ( # $3 - quoted text buffer (?: # repeat group (no backreference) \\\\ # an escaped backslash \\ | # ...or... \\\2 # an escaped quote \" or \' (match $1) | # ...or... . # any other character | \n )*? # non-greedy repeat ) # end of $3 \2 # match opening quote | # an unquoted number matches in $4 (-?\d+(?:\.\d+)?) # numbers | # filename matches in $5 ( \/?\w+(?:(?:\/|::?)\w*)+ | \/\w+) | # an identifier matches in $6 (\w+) # variable identifier | # an unquoted word or symbol matches in $7 ( [(){}\[\]:;,\/\\] # misc parenthesis and symbols # | \-> # arrow operator (for future?) | [+\-*] # math operations | \$\{? # dollar with option left brace | => # like '=' | [=!<>]?= | [!<>] # eqality tests | &&? | \|\|? # boolean ops | \.\.? # n..n sequence | \S+ # something unquoted ) # end of $7 /gmxo) { # ignore comments to EOL next if $1; # quoted string if (defined ($token = $3)) { # double-quoted string may include $variable references if ($2 eq '"') { if ($token =~ /[\$\\]/) { $type = 'QUOTED'; # unescape " and \ but leave \$ escaped so that # interpolate_text() doesn't incorrectly treat it # as a variable reference # $token =~ s/\\([\\"])/$1/g; for ($token) { s/\\([^\$nrt])/$1/g; s/\\([nrt])/$QUOTED_ESCAPES->{ $1 }/ge; } push(@tokens, ('"') x 2, @{ $self->interpolate_text($token) }, ('"') x 2); next; } else { $type = 'LITERAL'; $token =~ s['][\\']g; $token = "'$token'"; } } else { $type = 'LITERAL'; $token = "'$token'"; } } # number elsif (defined ($token = $4)) { $type = 'NUMBER'; } elsif (defined($token = $5)) { $type = 'FILENAME'; } elsif (defined($token = $6)) { # Fold potential keywords to UPPER CASE if the ANYCASE option is # set, unless (we've got some preceding tokens and) the previous # token is a DOT op. This prevents the 'last' in 'data.last' # from being interpreted as the LAST keyword. if ($anycase) { # if the token follows a dot or precedes an assignment then # it's not for folding, e.g. the 'wrapper' in this: # [% page = { wrapper='html' }; page.wrapper %] if ((@tokens && $ANYCASE_AFTER->{ $tokens[-2] }) || ($text =~ /$ANYCASE_BEFORE/gc)) { # keep the token unmodified $uctoken = $token; } else { $uctoken = uc $token; } } else { $uctoken = $token; } if (defined ($type = $lextable->{ $uctoken })) { $token = $uctoken; } else { $type = 'IDENT'; } } elsif (defined ($token = $7)) { # reserved words may be in lower case unless case sensitive $uctoken = $anycase ? uc $token : $token; unless (defined ($type = $lextable->{ $uctoken })) { $type = 'UNQUOTED'; } } push(@tokens, $type, $token); # print(STDERR " +[ $type, $token ]\n") # if $DEBUG; } # print STDERR "tokenise directive() returning:\n [ @tokens ]\n" # if $DEBUG; return \@tokens; ## RETURN ## } #------------------------------------------------------------------------ # define_block($name, $block) # # Called by the parser 'defblock' rule when a BLOCK definition is # encountered in the template. The name of the block is passed in the # first parameter and a reference to the compiled block is passed in # the second. This method stores the block in the $self->{ DEFBLOCK } # hash which has been initialised by parse() and will later be used # by the same method to call the store() method on the calling cache # to define the block "externally". #------------------------------------------------------------------------ sub define_block { my ($self, $name, $block) = @_; my $defblock = $self->{ DEFBLOCK } || return undef; $self->debug("compiled block '$name':\n$block") if $self->{ DEBUG } & Template::Constants::DEBUG_PARSER; warn "Block redefined: $name\n" if exists $defblock->{ $name }; $defblock->{ $name } = $block; return undef; } sub push_defblock { my $self = shift; my $stack = $self->{ DEFBLOCK_STACK } ||= []; push(@$stack, $self->{ DEFBLOCK } ); $self->{ DEFBLOCK } = { }; } sub pop_defblock { my $self = shift; my $defs = $self->{ DEFBLOCK }; my $stack = $self->{ DEFBLOCK_STACK } || return $defs; return $defs unless @$stack; $self->{ DEFBLOCK } = pop @$stack; return $defs; } #------------------------------------------------------------------------ # add_metadata(\@setlist) #------------------------------------------------------------------------ sub add_metadata { my ($self, $setlist) = @_; my $metadata = $self->{ METADATA } || return undef; push(@$metadata, @$setlist); return undef; } #------------------------------------------------------------------------ # location() # # Return Perl comment indicating current parser file and line #------------------------------------------------------------------------ sub location { my $self = shift; return "\n" unless $self->{ FILE_INFO }; my $line = ${ $self->{ LINE } }; my $info = $self->{ FILEINFO }->[-1]; my $file = $info->{ path } || $info->{ name } || '(unknown template)'; $line =~ s/\-.*$//; # might be 'n-n' $line ||= 1; return "#line $line \"$file\"\n"; } #======================================================================== # ----- PRIVATE METHODS ----- #======================================================================== #------------------------------------------------------------------------ # _parse(\@tokens, \@info) # # Parses the list of input tokens passed by reference and returns a # Template::Directive::Block object which contains the compiled # representation of the template. # # This is the main parser DFA loop. See embedded comments for # further details. # # On error, undef is returned and the internal _ERROR field is set to # indicate the error. This can be retrieved by calling the error() # method. #------------------------------------------------------------------------ sub _parse { my ($self, $tokens, $info) = @_; my ($token, $value, $text, $line, $inperl); my ($state, $stateno, $status, $action, $lookup, $coderet, @codevars); my ($lhs, $len, $code); # rule contents my $stack = [ [ 0, undef ] ]; # DFA stack # DEBUG # local $" = ', '; # retrieve internal rule and state tables my ($states, $rules) = @$self{ qw( STATES RULES ) }; # If we're tracing variable usage then we need to give the factory a # reference to our $self->{ VARIABLES } for it to fill in. This is a # bit of a hack to back-patch this functionality into TT2. $self->{ FACTORY }->trace_vars($self->{ VARIABLES }) if $self->{ TRACE_VARS }; # call the grammar set_factory method to install emitter factory $self->{ GRAMMAR }->install_factory($self->{ FACTORY }); $line = $inperl = 0; $self->{ LINE } = \$line; $self->{ FILE } = $info->{ name }; $self->{ INPERL } = \$inperl; $status = CONTINUE; my $in_string = 0; while(1) { # get state number and state $stateno = $stack->[-1]->[0]; $state = $states->[$stateno]; # see if any lookaheads exist for the current state if (exists $state->{'ACTIONS'}) { # get next token and expand any directives (i.e. token is an # array ref) onto the front of the token list while (! defined $token && @$tokens) { $token = shift(@$tokens); if (ref $token) { ($text, $line, $token) = @$token; if (ref $token) { if ($info->{ DEBUG } && ! $in_string) { # - - - - - - - - - - - - - - - - - - - - - - - - - # This is gnarly. Look away now if you're easily # frightened. We're pushing parse tokens onto the # pending list to simulate a DEBUG directive like so: # [% DEBUG msg line='20' text='INCLUDE foo' %] # - - - - - - - - - - - - - - - - - - - - - - - - - my $dtext = $text; $dtext =~ s[(['\\])][\\$1]g; unshift(@$tokens, DEBUG => 'DEBUG', IDENT => 'msg', IDENT => 'line', ASSIGN => '=', LITERAL => "'$line'", IDENT => 'text', ASSIGN => '=', LITERAL => "'$dtext'", IDENT => 'file', ASSIGN => '=', LITERAL => "'$info->{ name }'", (';') x 2, @$token, (';') x 2); } else { unshift(@$tokens, @$token, (';') x 2); } $token = undef; # force redo } elsif ($token eq 'ITEXT') { if ($inperl) { # don't perform interpolation in PERL blocks $token = 'TEXT'; $value = $text; } else { unshift(@$tokens, @{ $self->interpolate_text($text, $line) }); $token = undef; # force redo } } } else { # toggle string flag to indicate if we're crossing # a string boundary $in_string = ! $in_string if $token eq '"'; $value = shift(@$tokens); } }; # clear undefined token to avoid 'undefined variable blah blah' # warnings and let the parser logic pick it up in a minute $token = '' unless defined $token; # get the next state for the current lookahead token $action = defined ($lookup = $state->{'ACTIONS'}->{ $token }) ? $lookup : defined ($lookup = $state->{'DEFAULT'}) ? $lookup : undef; } else { # no lookahead actions $action = $state->{'DEFAULT'}; } # ERROR: no ACTION last unless defined $action; # - - - - - - - - - - - - - - - - - - - - - - - - - - - - # shift (+ive ACTION) # - - - - - - - - - - - - - - - - - - - - - - - - - - - - if ($action > 0) { push(@$stack, [ $action, $value ]); $token = $value = undef; redo; }; # - - - - - - - - - - - - - - - - - - - - - - - - - - - - # reduce (-ive ACTION) # - - - - - - - - - - - - - - - - - - - - - - - - - - - - ($lhs, $len, $code) = @{ $rules->[ -$action ] }; # no action imples ACCEPTance $action or $status = ACCEPT; # use dummy sub if code ref doesn't exist if ( !$code ) { $coderet = $len ? $stack->[ -$len ]->[1] : undef; } else { # $code = sub { $_[1] } # unless $code; @codevars = $len ? map { $_->[1] } @$stack[ -$len .. -1 ] : (); eval { $coderet = &$code( $self, @codevars ); }; if ($@) { my $err = $@; chomp $err; return $self->_parse_error($err); } } # reduce stack by $len splice(@$stack, -$len, $len); # ACCEPT return $coderet ## RETURN ## if $status == ACCEPT; # ABORT return undef ## RETURN ## if $status == ABORT; # ERROR last if $status == ERROR; } continue { push(@$stack, [ $states->[ $stack->[-1][0] ]->{'GOTOS'}->{ $lhs }, $coderet ]), } # ERROR ## RETURN ## return $self->_parse_error('unexpected end of input') unless defined $value; # munge text of last directive to make it readable # $text =~ s/\n/\\n/g; return $self->_parse_error("unexpected end of directive", $text) if $value eq ';'; # end of directive SEPARATOR return $self->_parse_error("unexpected token ($value)", $text); } #------------------------------------------------------------------------ # _parse_error($msg, $dirtext) # # Method used to handle errors encountered during the parse process # in the _parse() method. #------------------------------------------------------------------------ sub _parse_error { my ($self, $msg, $text) = @_; my $line = $self->{ LINE }; $line = ref($line) ? $$line : $line; $line = 'unknown' unless $line; $msg .= "\n [% $text %]" if defined $text; return $self->error("line $line: $msg"); } 1; __END__ =head1 NAME Template::Parser - LALR(1) parser for compiling template documents =head1 SYNOPSIS use Template::Parser; $parser = Template::Parser->new(\%config); $template = $parser->parse($text) || die $parser->error(), "\n"; =head1 DESCRIPTION The C<Template::Parser> module implements a LALR(1) parser and associated methods for parsing template documents into Perl code. =head1 PUBLIC METHODS =head2 new(\%params) The C<new()> constructor creates and returns a reference to a new C<Template::Parser> object. A reference to a hash may be supplied as a parameter to provide configuration values. See L<CONFIGURATION OPTIONS> below for a summary of these options and L<Template::Manual::Config> for full details. my $parser = Template::Parser->new({ START_TAG => quotemeta('<+'), END_TAG => quotemeta('+>'), }); =head2 parse($text) The C<parse()> method parses the text passed in the first parameter and returns a reference to a hash array of data defining the compiled representation of the template text, suitable for passing to the L<Template::Document> L<new()|Template::Document#new()> constructor method. On error, undef is returned. $data = $parser->parse($text) || die $parser->error(); The C<$data> hash reference returned contains a C<BLOCK> item containing the compiled Perl code for the template, a C<DEFBLOCKS> item containing a reference to a hash array of sub-template C<BLOCK>s defined within in the template, and a C<METADATA> item containing a reference to a hash array of metadata values defined in C<META> tags. =head1 CONFIGURATION OPTIONS The C<Template::Parser> module accepts the following configuration options. Please see L<Template::Manual::Config> for further details on each option. =head2 START_TAG, END_TAG The L<START_TAG|Template::Manual::Config#START_TAG_END_TAG> and L<END_TAG|Template::Manual::Config#START_TAG_END_TAG> options are used to specify character sequences or regular expressions that mark the start and end of a template directive. my $parser = Template::Parser->new({ START_TAG => quotemeta('<+'), END_TAG => quotemeta('+>'), }); =head2 TAG_STYLE The L<TAG_STYLE|Template::Manual::Config#TAG_STYLE> option can be used to set both L<START_TAG> and L<END_TAG> according to pre-defined tag styles. my $parser = Template::Parser->new({ TAG_STYLE => 'star', # [* ... *] }); =head2 PRE_CHOMP, POST_CHOMP The L<PRE_CHOMP|Template::Manual::Config#PRE_CHOMP_POST_CHOMP> and L<POST_CHOMP|Template::Manual::Config#PRE_CHOMP_POST_CHOMP> can be set to remove any whitespace before or after a directive tag, respectively. my $parser = Template::Parser-E<gt>new({ PRE_CHOMP => 1, POST_CHOMP => 1, }); =head2 INTERPOLATE The L<INTERPOLATE|Template::Manual::Config#INTERPOLATE> flag can be set to allow variables to be embedded in plain text blocks. my $parser = Template::Parser->new({ INTERPOLATE => 1, }); Variables should be prefixed by a C<$> to identify them, using curly braces to explicitly scope the variable name where necessary. Hello ${name}, The day today is ${day.today}. =head2 ANYCASE The L<ANYCASE|Template::Manual::Config#ANYCASE> option can be set to allow directive keywords to be specified in any case. # with ANYCASE set to 1 [% INCLUDE foobar %] # OK [% include foobar %] # OK [% include = 10 %] # ERROR, 'include' is a reserved word =head2 GRAMMAR The L<GRAMMAR|Template::Manual::Config#GRAMMAR> configuration item can be used to specify an alternate grammar for the parser. This allows a modified or entirely new template language to be constructed and used by the Template Toolkit. use MyOrg::Template::Grammar; my $parser = Template::Parser->new({ GRAMMAR = MyOrg::Template::Grammar->new(); }); By default, an instance of the default L<Template::Grammar> will be created and used automatically if a C<GRAMMAR> item isn't specified. =head2 DEBUG The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable various debugging features of the C<Template::Parser> module. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_PARSER | DEBUG_DIRS, }); =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The main parsing loop of the C<Template::Parser> module was derived from a standalone parser generated by version 0.16 of the C<Parse::Yapp> module. The following copyright notice appears in the C<Parse::Yapp> documentation. The Parse::Yapp module and its related modules and shell scripts are copyright (c) 1998 Francois Desarmenien, France. All rights reserved. You may use and distribute them under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. =head1 SEE ALSO L<Template>, L<Template::Grammar>, L<Template::Directive> PK � �[�Xn�7 7 lib/Template/Plugins.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugins # # DESCRIPTION # Plugin provider which handles the loading of plugin modules and # instantiation of plugin objects. # # AUTHORS # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # Copyright (C) 1998-2000 Canon Research Centre Europe Ltd. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugins; use strict; use warnings; use base 'Template::Base'; use Template::Constants; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $PLUGIN_BASE = 'Template::Plugin'; our $STD_PLUGINS = { 'assert' => 'Template::Plugin::Assert', 'cgi' => 'Template::Plugin::CGI', 'datafile' => 'Template::Plugin::Datafile', 'date' => 'Template::Plugin::Date', 'debug' => 'Template::Plugin::Debug', 'directory' => 'Template::Plugin::Directory', 'dbi' => 'Template::Plugin::DBI', 'dumper' => 'Template::Plugin::Dumper', 'file' => 'Template::Plugin::File', 'format' => 'Template::Plugin::Format', 'html' => 'Template::Plugin::HTML', 'image' => 'Template::Plugin::Image', 'iterator' => 'Template::Plugin::Iterator', 'latex' => 'Template::Plugin::Latex', 'pod' => 'Template::Plugin::Pod', 'scalar' => 'Template::Plugin::Scalar', 'table' => 'Template::Plugin::Table', 'url' => 'Template::Plugin::URL', 'view' => 'Template::Plugin::View', 'wrap' => 'Template::Plugin::Wrap', 'xml' => 'Template::Plugin::XML', 'xmlstyle' => 'Template::Plugin::XML::Style', }; #======================================================================== # -- PUBLIC METHODS -- #======================================================================== #------------------------------------------------------------------------ # fetch($name, \@args, $context) # # General purpose method for requesting instantiation of a plugin # object. The name of the plugin is passed as the first parameter. # The internal FACTORY lookup table is consulted to retrieve the # appropriate factory object or class name. If undefined, the _load() # method is called to attempt to load the module and return a factory # class/object which is then cached for subsequent use. A reference # to the calling context should be passed as the third parameter. # This is passed to the _load() class method. The new() method is # then called against the factory class name or prototype object to # instantiate a new plugin object, passing any arguments specified by # list reference as the second parameter. e.g. where $factory is the # class name 'MyClass', the new() method is called as a class method, # $factory->new(...), equivalent to MyClass->new(...) . Where # $factory is a prototype object, the new() method is called as an # object method, $myobject->new(...). This latter approach allows # plugins to act as Singletons, cache shared data, etc. # # Returns a reference to a plugin, (undef, STATUS_DECLINE) to decline # the request or ($error, STATUS_ERROR) on error. #------------------------------------------------------------------------ sub fetch { my ($self, $name, $args, $context) = @_; my ($factory, $plugin, $error); $self->debug("fetch($name, ", defined $args ? ('[ ', join(', ', @$args), ' ]') : '<no args>', ', ', defined $context ? $context : '<no context>', ')') if $self->{ DEBUG }; # NOTE: # the $context ref gets passed as the first parameter to all regular # plugins, but not to those loaded via LOAD_PERL; to hack around # this until we have a better implementation, we pass the $args # reference to _load() and let it unshift the first args in the # LOAD_PERL case $args ||= [ ]; unshift @$args, $context; $factory = $self->{ FACTORY }->{ $name } ||= do { ($factory, $error) = $self->_load($name, $context); return ($factory, $error) if $error; ## RETURN $factory; }; # call the new() method on the factory object or class name eval { if (ref $factory eq 'CODE') { defined( $plugin = &$factory(@$args) ) || die "$name plugin failed\n"; } else { defined( $plugin = $factory->new(@$args) ) || die "$name plugin failed: ", $factory->error(), "\n"; } }; if ($error = $@) { # chomp $error; return $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ($error, Template::Constants::STATUS_ERROR); } return $plugin; } #======================================================================== # -- PRIVATE METHODS -- #======================================================================== #------------------------------------------------------------------------ # _init(\%config) # # Private initialisation method. #------------------------------------------------------------------------ sub _init { my ($self, $params) = @_; my ($pbase, $plugins, $factory) = @$params{ qw( PLUGIN_BASE PLUGINS PLUGIN_FACTORY ) }; $plugins ||= { }; # update PLUGIN_BASE to an array ref if necessary $pbase = [ ] unless defined $pbase; $pbase = [ $pbase ] unless ref($pbase) eq 'ARRAY'; # add default plugin base (Template::Plugin) if set push(@$pbase, $PLUGIN_BASE) if $PLUGIN_BASE; $self->{ PLUGIN_BASE } = $pbase; $self->{ PLUGINS } = { %$STD_PLUGINS, %$plugins }; $self->{ TOLERANT } = $params->{ TOLERANT } || 0; $self->{ LOAD_PERL } = $params->{ LOAD_PERL } || 0; $self->{ FACTORY } = $factory || { }; $self->{ DEBUG } = ( $params->{ DEBUG } || 0 ) & Template::Constants::DEBUG_PLUGINS; return $self; } #------------------------------------------------------------------------ # _load($name, $context) # # Private method which attempts to load a plugin module and determine the # correct factory name or object by calling the load() class method in # the loaded module. #------------------------------------------------------------------------ sub _load { my ($self, $name, $context) = @_; my ($factory, $module, $base, $pkg, $file, $ok, $error); if ($module = $self->{ PLUGINS }->{ $name } || $self->{ PLUGINS }->{ lc $name }) { # plugin module name is explicitly stated in PLUGIN_NAME $pkg = $module; ($file = $module) =~ s|::|/|g; $file =~ s|::|/|g; $self->debug("loading $module.pm (PLUGIN_NAME)") if $self->{ DEBUG }; $ok = eval { require "$file.pm" }; $error = $@; } else { # try each of the PLUGIN_BASE values to build module name ($module = $name) =~ s/\./::/g; foreach $base (@{ $self->{ PLUGIN_BASE } }) { $pkg = $base . '::' . $module; ($file = $pkg) =~ s|::|/|g; $self->debug("loading $file.pm (PLUGIN_BASE)") if $self->{ DEBUG }; $ok = eval { require "$file.pm" }; last unless $@; $error .= "$@\n" unless ($@ =~ /^Can\'t locate $file\.pm/); } } if ($ok) { $self->debug("calling $pkg->load()") if $self->{ DEBUG }; $factory = eval { $pkg->load($context) }; $error = ''; if ($@ || ! $factory) { $error = $@ || 'load() returned a false value'; } } elsif ($self->{ LOAD_PERL }) { # fallback - is it a regular Perl module? ($file = $module) =~ s|::|/|g; eval { require "$file.pm" }; if ($@) { $error = $@; } else { # this is a regular Perl module so the new() constructor # isn't expecting a $context reference as the first argument; # so we construct a closure which removes it before calling # $module->new(@_); $factory = sub { shift; $module->new(@_); }; $error = ''; } } if ($factory) { $self->debug("$name => $factory") if $self->{ DEBUG }; return $factory; } elsif ($error) { return $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ($error, Template::Constants::STATUS_ERROR); } else { return (undef, Template::Constants::STATUS_DECLINED); } } 1; __END__ =head1 NAME Template::Plugins - Plugin provider module =head1 SYNOPSIS use Template::Plugins; $plugin_provider = Template::Plugins->new(\%options); ($plugin, $error) = $plugin_provider->fetch($name, @args); =head1 DESCRIPTION The C<Template::Plugins> module defines a provider class which can be used to load and instantiate Template Toolkit plugin modules. =head1 METHODS =head2 new(\%params) Constructor method which instantiates and returns a reference to a C<Template::Plugins> object. A reference to a hash array of configuration items may be passed as a parameter. These are described below. Note that the L<Template> front-end module creates a C<Template::Plugins> provider, passing all configuration items. Thus, the examples shown below in the form: $plugprov = Template::Plugins->new({ PLUGIN_BASE => 'MyTemplate::Plugin', LOAD_PERL => 1, ... }); can also be used via the L<Template> module as: $ttengine = Template->new({ PLUGIN_BASE => 'MyTemplate::Plugin', LOAD_PERL => 1, ... }); as well as the more explicit form of: $plugprov = Template::Plugins->new({ PLUGIN_BASE => 'MyTemplate::Plugin', LOAD_PERL => 1, ... }); $ttengine = Template->new({ LOAD_PLUGINS => [ $plugprov ], }); =head2 fetch($name, @args) Called to request that a plugin of a given name be provided. The relevant module is first loaded (if necessary) and the L<load()|Template::Plugin#load()> class method called to return the factory class name (usually the same package name) or a factory object (a prototype). The L<new()|Template::Plugin#new()> method is then called as a class or object method against the factory, passing all remaining parameters. Returns a reference to a new plugin object or C<($error, STATUS_ERROR)> on error. May also return C<(undef, STATUS_DECLINED)> to decline to serve the request. If C<TOLERANT> is set then all errors will be returned as declines. =head1 CONFIGURATION OPTIONS The following list summarises the configuration options that can be provided to the C<Template::Plugins> L<new()> constructor. Please consult L<Template::Manual::Config> for further details and examples of each configuration option in use. =head2 PLUGINS The L<PLUGINS|Template::Manual::Config#PLUGINS> option can be used to provide a reference to a hash array that maps plugin names to Perl module names. my $plugins = Template::Plugins->new({ PLUGINS => { cgi => 'MyOrg::Template::Plugin::CGI', foo => 'MyOrg::Template::Plugin::Foo', bar => 'MyOrg::Template::Plugin::Bar', }, }); =head2 PLUGIN_BASE If a plugin is not defined in the L<PLUGINS|Template::Manual::Config#PLUGINS> hash then the L<PLUGIN_BASE|Template::Manual::Config#PLUGIN_BASE> is used to attempt to construct a correct Perl module name which can be successfully loaded. # single value PLUGIN_BASE my $plugins = Template::Plugins->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin', }); # multiple value PLUGIN_BASE my $plugins = Template::Plugins->new({ PLUGIN_BASE => [ 'MyOrg::Template::Plugin', 'YourOrg::Template::Plugin' ], }); =head2 LOAD_PERL The L<LOAD_PERL|Template::Manual::Config#LOAD_PERL> option can be set to allow you to load regular Perl modules (i.e. those that don't reside in the C<Template::Plugin> or another user-defined namespace) as plugins. If a plugin cannot be loaded using the L<PLUGINS|Template::Manual::Config#PLUGINS> or L<PLUGIN_BASE|Template::Manual::Config#PLUGIN_BASE> approaches then, if the L<LOAD_PERL|Template::Manual::Config#LOAD_PERL> is set, the provider will make a final attempt to load the module without prepending any prefix to the module path. Unlike regular plugins, modules loaded using L<LOAD_PERL|Template::Manual::Config#LOAD_PERL> do not receive a L<Template::Context> reference as the first argument to the C<new()> constructor method. =head2 TOLERANT The L<TOLERANT|Template::Manual::Config#TOLERANT> flag can be set to indicate that the C<Template::Plugins> module should ignore any errors encountered while loading a plugin and instead return C<STATUS_DECLINED>. =head2 DEBUG The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable debugging messages for the C<Template::Plugins> module by setting it to include the C<DEBUG_PLUGINS> value. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS, }); =head1 TEMPLATE TOOLKIT PLUGINS Please see L<Template::Manual::Plugins> For a complete list of all the plugin modules distributed with the Template Toolkit. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Manual::Plugins>, L<Template::Plugin>, L<Template::Context>, L<Template>. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[ny��� � lib/Template/Exception.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Exception # # DESCRIPTION # Module implementing a generic exception class used for error handling # in the Template Toolkit. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== package Template::Exception; use strict; use warnings; use constant TYPE => 0; use constant INFO => 1; use constant TEXT => 2; use overload q|""| => "as_string", fallback => 1; our $VERSION = '3.100'; #------------------------------------------------------------------------ # new($type, $info, \$text) # # Constructor method used to instantiate a new Template::Exception # object. The first parameter should contain the exception type. This # can be any arbitrary string of the caller's choice to represent a # specific exception. The second parameter should contain any # information (i.e. error message or data reference) relevant to the # specific exception event. The third optional parameter may be a # reference to a scalar containing output text from the template # block up to the point where the exception was thrown. #------------------------------------------------------------------------ sub new { my ($class, $type, $info, $textref) = @_; bless [ $type, $info, $textref ], $class; } #------------------------------------------------------------------------ # type() # info() # type_info() # # Accessor methods to return the internal TYPE and INFO fields. #------------------------------------------------------------------------ sub type { $_[0]->[ TYPE ]; } sub info { $_[0]->[ INFO ]; } sub type_info { my $self = shift; @$self[ TYPE, INFO ]; } #------------------------------------------------------------------------ # text() # text(\$pretext) # # Method to return the text referenced by the TEXT member. A text # reference may be passed as a parameter to supercede the existing # member. The existing text is added to the *end* of the new text # before being stored. This facility is provided for template blocks # to gracefully de-nest when an exception occurs and allows them to # reconstruct their output in the correct order. #------------------------------------------------------------------------ sub text { my ($self, $newtextref) = @_; my $textref = $self->[ TEXT ]; if ($newtextref) { $$newtextref .= $$textref if $textref && $textref ne $newtextref; $self->[ TEXT ] = $newtextref; return ''; } elsif ($textref) { return $$textref; } else { return ''; } } #------------------------------------------------------------------------ # as_string() # # Accessor method to return a string indicating the exception type and # information. #------------------------------------------------------------------------ sub as_string { my $self = shift; return $self->[ TYPE ] . ' error - ' . $self->[ INFO ]; } #------------------------------------------------------------------------ # select_handler(@types) # # Selects the most appropriate handler for the exception TYPE, from # the list of types passed in as parameters. The method returns the # item which is an exact match for TYPE or the closest, more # generic handler (e.g. foo being more generic than foo.bar, etc.) #------------------------------------------------------------------------ sub select_handler { my ($self, @options) = @_; my $type = $self->[ TYPE ]; my %hlut; @hlut{ @options } = (1) x @options; while ($type) { return $type if $hlut{ $type }; # strip .element from the end of the exception type to find a # more generic handler $type =~ s/\.?[^\.]*$//; } return undef; } 1; __END__ =head1 NAME Template::Exception - Exception handling class module =head1 SYNOPSIS use Template::Exception; my $exception = Template::Exception->new($type, $info); $type = $exception->type; $info = $exception->info; ($type, $info) = $exception->type_info; print $exception->as_string(); $handler = $exception->select_handler(\@candidates); =head1 DESCRIPTION The C<Template::Exception> module defines an object class for representing exceptions within the template processing life cycle. Exceptions can be raised by modules within the Template Toolkit, or can be generated and returned by user code bound to template variables. Exceptions can be raised in a template using the C<THROW> directive, [% THROW user.login 'no user id: please login' %] or by calling the L<throw()|Template::Context#throw()> method on the current L<Template::Context> object, $context->throw('user.passwd', 'Incorrect Password'); $context->throw('Incorrect Password'); # type 'undef' or from Perl code by calling C<die()> with a C<Template::Exception> object, die (Template::Exception->new('user.denied', 'Invalid User ID')); or by simply calling C<die()> with an error string. This is automagically caught and converted to an exception of 'C<undef>' type (that's the literal string 'C<undef>' rather than Perl's undefined value) which can then be handled in the usual way. die "I'm sorry Dave, I can't do that"; Each exception is defined by its type and a information component (e.g. error message). The type can be any identifying string and may contain dotted components (e.g. 'C<foo>', 'C<foo.bar>', 'C<foo.bar.baz>'). Exception types are considered to be hierarchical such that 'C<foo.bar>' would be a specific type of the more general 'C<foo>' type. =head1 METHODS =head2 type() Returns the exception type. =head2 info() Returns the exception information. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Context> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�>K�0s 0s lib/Template/Directive.pmnu ��6�$ #================================================================= -*-Perl-*- # # Template::Directive # # DESCRIPTION # Factory module for constructing templates from Perl code. # # AUTHOR # Andy Wardley <abw@wardley.org> # # WARNING # Much of this module is hairy, even furry in places. It needs # a lot of tidying up and may even be moved into a different place # altogether. The generator code is often inefficient, particularly in # being very anal about pretty-printing the Perl code all neatly, but # at the moment, that's still high priority for the sake of easier # debugging. # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Directive; use strict; use warnings; use base 'Template::Base'; use Template::Constants; use Template::Exception; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $WHILE_MAX = 1000 unless defined $WHILE_MAX; our $PRETTY = 0 unless defined $PRETTY; our $OUTPUT = '$output .= '; sub _init { my ($self, $config) = @_; $self->{ NAMESPACE } = $config->{ NAMESPACE }; return $self; } sub trace_vars { my $self = shift; return @_ ? ($self->{ TRACE_VARS } = shift) : $self->{ TRACE_VARS }; } sub pad { my ($text, $pad) = @_; $pad = ' ' x ($pad * 4); $text =~ s/^(?!#line)/$pad/gm; $text; } #======================================================================== # FACTORY METHODS # # These methods are called by the parser to construct directive instances. #======================================================================== #------------------------------------------------------------------------ # template($block) #------------------------------------------------------------------------ sub template { my ($self, $block) = @_; $block = pad($block, 2) if $PRETTY; return "sub { return '' }" unless $block =~ /\S/; return <<EOF; sub { my \$context = shift || die "template sub called without context\\n"; my \$stash = \$context->stash; my \$output = ''; my \$_tt_error; eval { BLOCK: { $block } }; if (\$@) { \$_tt_error = \$context->catch(\$@, \\\$output); die \$_tt_error unless \$_tt_error->type eq 'return'; } return \$output; } EOF } #------------------------------------------------------------------------ # anon_block($block) [% BLOCK %] ... [% END %] #------------------------------------------------------------------------ sub anon_block { my ($self, $block) = @_; $block = pad($block, 2) if $PRETTY; return <<EOF; # BLOCK $OUTPUT do { my \$output = ''; my \$_tt_error; eval { BLOCK: { $block } }; if (\$@) { \$_tt_error = \$context->catch(\$@, \\\$output); die \$_tt_error unless \$_tt_error->type eq 'return'; } \$output; }; EOF } #------------------------------------------------------------------------ # block($blocktext) #------------------------------------------------------------------------ sub block { my ($self, $block) = @_; return join("\n", @{ $block || [] }); } #------------------------------------------------------------------------ # textblock($text) #------------------------------------------------------------------------ sub textblock { my ($self, $text) = @_; return "$OUTPUT " . &text($self, $text) . ';'; } #------------------------------------------------------------------------ # text($text) #------------------------------------------------------------------------ sub text { my ( $self, $text ) = @_; return '' if !length $text; if ( $text =~ tr{$@\\}{} ) { $text =~ s/(["\$\@\\])/\\$1/g; $text =~ s/\n/\\n/g; return '"' . $text . '"'; } $text =~ s{'}{\\'}g if index( $text, q{'} ) != -1; return q{'} . $text . q{'}; } #------------------------------------------------------------------------ # quoted(\@items) "foo$bar" #------------------------------------------------------------------------ sub quoted { my ($self, $items) = @_; return '' unless @$items; return ("('' . " . $items->[0] . ')') if scalar @$items == 1; return '(' . join(' . ', @$items) . ')'; # my $r = '(' . join(' . ', @$items) . ' . "")'; # print STDERR "[$r]\n"; # return $r; } #------------------------------------------------------------------------ # ident(\@ident) foo.bar(baz) #------------------------------------------------------------------------ sub ident { my ($self, $ident) = @_; return "''" unless @$ident; my $ns; # Careful! Template::Parser always creates a Template::Directive object # (as of v2.22_1) so $self is usually an object. However, we used to # allow Template::Directive methods to be called as class methods and # Template::Namespace::Constants module takes advantage of this fact # by calling Template::Directive->ident() when it needs to generate an # identifier. This hack guards against Mr Fuckup from coming to town # when that happens. if (ref $self) { # trace variable usage if ($self->{ TRACE_VARS }) { my $root = $self->{ TRACE_VARS }; my $n = 0; my $v; while ($n < @$ident) { $v = $ident->[$n]; for ($v) { s/^'//; s/'$// }; $root = $root->{ $v } ||= { }; $n += 2; } } # does the first element of the identifier have a NAMESPACE # handler defined? if (@$ident > 2 && ($ns = $self->{ NAMESPACE })) { my $key = $ident->[0]; # a faster alternate to $key =~ s/^'(.+)'$/$1/s if ( index( $key, q[']) == 0 ) { substr( $key, 0, 1, '' ); substr( $key, -1, 1, '' ); # remove the last char blindly } if ($ns = $ns->{ $key }) { return $ns->ident($ident); } } } if (scalar @$ident <= 2 && ! $ident->[1]) { $ident = $ident->[0]; } else { $ident = '[' . join(', ', @$ident) . ']'; } return "\$stash->get($ident)"; } #------------------------------------------------------------------------ # identref(\@ident) \foo.bar(baz) #------------------------------------------------------------------------ sub identref { my ($self, $ident) = @_; return "''" unless @$ident; if (scalar @$ident <= 2 && ! $ident->[1]) { $ident = $ident->[0]; } else { $ident = '[' . join(', ', @$ident) . ']'; } return "\$stash->getref($ident)"; } #------------------------------------------------------------------------ # assign(\@ident, $value, $default) foo = bar #------------------------------------------------------------------------ sub assign { my ($self, $var, $val, $default) = @_; if (ref $var) { if (scalar @$var == 2 && ! $var->[1]) { $var = $var->[0]; } else { $var = '[' . join(', ', @$var) . ']'; } } $val .= ', 1' if $default; return "\$stash->set($var, $val)"; } #------------------------------------------------------------------------ # args(\@args) foo, bar, baz = qux #------------------------------------------------------------------------ sub args { my ($self, $args) = @_; my $hash = shift @$args; push(@$args, '{ ' . join(', ', @$hash) . ' }') if @$hash; return '0' unless @$args; return '[ ' . join(', ', @$args) . ' ]'; } #------------------------------------------------------------------------ # filenames(\@names) #------------------------------------------------------------------------ sub filenames { my ($self, $names) = @_; if (@$names > 1) { $names = '[ ' . join(', ', @$names) . ' ]'; } else { $names = shift @$names; } return $names; } #------------------------------------------------------------------------ # get($expr) [% foo %] #------------------------------------------------------------------------ sub get { my ($self, $expr) = @_; return "$OUTPUT $expr;"; } #------------------------------------------------------------------------ # call($expr) [% CALL bar %] #------------------------------------------------------------------------ sub call { my ($self, $expr) = @_; $expr .= ';'; return $expr; } #------------------------------------------------------------------------ # set(\@setlist) [% foo = bar, baz = qux %] #------------------------------------------------------------------------ sub set { my ($self, $setlist) = @_; my $output; while (my ($var, $val) = splice(@$setlist, 0, 2)) { $output .= &assign($self, $var, $val) . ";\n"; } chomp $output; return $output; } #------------------------------------------------------------------------ # default(\@setlist) [% DEFAULT foo = bar, baz = qux %] #------------------------------------------------------------------------ sub default { my ($self, $setlist) = @_; my $output; while (my ($var, $val) = splice(@$setlist, 0, 2)) { $output .= &assign($self, $var, $val, 1) . ";\n"; } chomp $output; return $output; } #------------------------------------------------------------------------ # insert(\@nameargs) [% INSERT file %] # # => [ [ $file, ... ], \@args ] #------------------------------------------------------------------------ sub insert { my ($self, $nameargs) = @_; my ($file, $args) = @$nameargs; $file = $self->filenames($file); return "$OUTPUT \$context->insert($file);"; } #------------------------------------------------------------------------ # include(\@nameargs) [% INCLUDE template foo = bar %] # # => [ [ $file, ... ], \@args ] #------------------------------------------------------------------------ sub include { my ($self, $nameargs) = @_; my ($file, $args) = @$nameargs; my $hash = shift @$args; $file = $self->filenames($file); $file .= @$hash ? ', { ' . join(', ', @$hash) . ' }' : ''; return "$OUTPUT \$context->include($file);"; } #------------------------------------------------------------------------ # process(\@nameargs) [% PROCESS template foo = bar %] # # => [ [ $file, ... ], \@args ] #------------------------------------------------------------------------ sub process { my ($self, $nameargs) = @_; my ($file, $args) = @$nameargs; my $hash = shift @$args; $file = $self->filenames($file); $file .= @$hash ? ', { ' . join(', ', @$hash) . ' }' : ''; return "$OUTPUT \$context->process($file);"; } #------------------------------------------------------------------------ # if($expr, $block, $else) [% IF foo < bar %] # ... # [% ELSE %] # ... # [% END %] #------------------------------------------------------------------------ sub if { my ($self, $expr, $block, $else) = @_; my @else = $else ? @$else : (); $else = pop @else; $block = pad($block, 1) if $PRETTY; my $output = "if ($expr) {\n$block\n}\n"; foreach my $elsif (@else) { ($expr, $block) = @$elsif; $block = pad($block, 1) if $PRETTY; $output .= "elsif ($expr) {\n$block\n}\n"; } if (defined $else) { $else = pad($else, 1) if $PRETTY; $output .= "else {\n$else\n}\n"; } return $output; } #------------------------------------------------------------------------ # foreach($target, $list, $args, $block) [% FOREACH x = [ foo bar ] %] # ... # [% END %] #------------------------------------------------------------------------ sub foreach { my ($self, $target, $list, $args, $block, $label) = @_; $args = shift @$args; $args = @$args ? ', { ' . join(', ', @$args) . ' }' : ''; $label ||= 'LOOP'; my ($loop_save, $loop_set, $loop_restore, $setiter); if ($target) { $loop_save = 'eval { $_tt_oldloop = ' . &ident($self, ["'loop'"]) . ' }'; $loop_set = "\$stash->{'$target'} = \$_tt_value"; $loop_restore = "\$stash->set('loop', \$_tt_oldloop)"; } else { $loop_save = '$stash = $context->localise()'; # $loop_set = "\$stash->set('import', \$_tt_value) " # . "if ref \$value eq 'HASH'"; $loop_set = "\$stash->get(['import', [\$_tt_value]]) " . "if ref \$_tt_value eq 'HASH'"; $loop_restore = '$stash = $context->delocalise()'; } $block = pad($block, 3) if $PRETTY; return <<EOF; # FOREACH do { my (\$_tt_value, \$_tt_error, \$_tt_oldloop); my \$_tt_list = $list; unless (UNIVERSAL::isa(\$_tt_list, 'Template::Iterator')) { \$_tt_list = Template::Config->iterator(\$_tt_list) || die \$Template::Config::ERROR, "\\n"; } (\$_tt_value, \$_tt_error) = \$_tt_list->get_first(); $loop_save; \$stash->set('loop', \$_tt_list); eval { $label: while (! \$_tt_error) { $loop_set; $block; (\$_tt_value, \$_tt_error) = \$_tt_list->get_next(); } }; $loop_restore; die \$@ if \$@; \$_tt_error = 0 if \$_tt_error && \$_tt_error eq Template::Constants::STATUS_DONE; die \$_tt_error if \$_tt_error; }; EOF } #------------------------------------------------------------------------ # next() [% NEXT %] # # Next iteration of a FOREACH loop (experimental) #------------------------------------------------------------------------ sub next { my ($self, $label) = @_; $label ||= 'LOOP'; return <<EOF; (\$_tt_value, \$_tt_error) = \$_tt_list->get_next(); next $label; EOF } #------------------------------------------------------------------------ # wrapper(\@nameargs, $block) [% WRAPPER template foo = bar %] # # => [ [$file,...], \@args ] #------------------------------------------------------------------------ sub wrapper { my ($self, $nameargs, $block) = @_; my ($file, $args) = @$nameargs; my $hash = shift @$args; local $" = ', '; # print STDERR "wrapper([@$file], { @$hash })\n"; return $self->multi_wrapper($file, $hash, $block) if @$file > 1; $file = shift @$file; $block = pad($block, 1) if $PRETTY; push(@$hash, "'content'", '$output'); $file .= @$hash ? ', { ' . join(', ', @$hash) . ' }' : ''; return <<EOF; # WRAPPER $OUTPUT do { my \$output = ''; $block \$context->include($file); }; EOF } sub multi_wrapper { my ($self, $file, $hash, $block) = @_; $block = pad($block, 1) if $PRETTY; push(@$hash, "'content'", '$output'); $hash = @$hash ? ', { ' . join(', ', @$hash) . ' }' : ''; $file = join(', ', reverse @$file); # print STDERR "multi wrapper: $file\n"; return <<EOF; # WRAPPER $OUTPUT do { my \$output = ''; $block foreach ($file) { \$output = \$context->include(\$_$hash); } \$output; }; EOF } #------------------------------------------------------------------------ # while($expr, $block) [% WHILE x < 10 %] # ... # [% END %] #------------------------------------------------------------------------ sub while { my ($self, $expr, $block, $label) = @_; $block = pad($block, 2) if $PRETTY; $label ||= 'LOOP'; return <<EOF; # WHILE do { my \$_tt_failsafe = $WHILE_MAX; $label: while (($expr) && --\$_tt_failsafe >= 0) { $block } die "WHILE loop terminated (> $WHILE_MAX iterations)\\n" if \$_tt_failsafe < 0; }; EOF } #------------------------------------------------------------------------ # switch($expr, \@case) [% SWITCH %] # [% CASE foo %] # ... # [% END %] #------------------------------------------------------------------------ sub switch { my ($self, $expr, $case) = @_; my @case = @$case; my ($match, $block, $default); my $caseblock = ''; $default = pop @case; foreach $case (@case) { $match = $case->[0]; $block = $case->[1]; $block = pad($block, 1) if $PRETTY; $caseblock .= <<EOF; \$_tt_match = $match; \$_tt_match = [ \$_tt_match ] unless ref \$_tt_match eq 'ARRAY'; if (grep(/^\\Q\$_tt_result\\E\$/, \@\$_tt_match)) { $block last SWITCH; } EOF } $caseblock .= $default if defined $default; $caseblock = pad($caseblock, 2) if $PRETTY; return <<EOF; # SWITCH do { my \$_tt_result = $expr; my \$_tt_match; SWITCH: { $caseblock } }; EOF } #------------------------------------------------------------------------ # try($block, \@catch) [% TRY %] # ... # [% CATCH %] # ... # [% END %] #------------------------------------------------------------------------ sub try { my ($self, $block, $catch) = @_; my @catch = @$catch; my ($match, $mblock, $default, $final, $n); my $catchblock = ''; my $handlers = []; $block = pad($block, 2) if $PRETTY; $final = pop @catch; $final = "# FINAL\n" . ($final ? "$final\n" : '') . 'die $_tt_error if $_tt_error;' . "\n" . '$output;'; $final = pad($final, 1) if $PRETTY; $n = 0; foreach $catch (@catch) { $match = $catch->[0] || do { $default ||= $catch->[1]; next; }; $mblock = $catch->[1]; $mblock = pad($mblock, 1) if $PRETTY; push(@$handlers, "'$match'"); $catchblock .= $n++ ? "elsif (\$_tt_handler eq '$match') {\n$mblock\n}\n" : "if (\$_tt_handler eq '$match') {\n$mblock\n}\n"; } $catchblock .= "\$_tt_error = 0;"; $catchblock = pad($catchblock, 3) if $PRETTY; if ($default) { $default = pad($default, 1) if $PRETTY; $default = "else {\n # DEFAULT\n$default\n \$_tt_error = '';\n}"; } else { $default = '# NO DEFAULT'; } $default = pad($default, 2) if $PRETTY; $handlers = join(', ', @$handlers); return <<EOF; # TRY $OUTPUT do { my \$output = ''; my (\$_tt_error, \$_tt_handler); eval { $block }; if (\$@) { \$_tt_error = \$context->catch(\$@, \\\$output); die \$_tt_error if \$_tt_error->type =~ /^(return|stop)\$/; \$stash->set('error', \$_tt_error); \$stash->set('e', \$_tt_error); if (defined (\$_tt_handler = \$_tt_error->select_handler($handlers))) { $catchblock } $default } $final }; EOF } #------------------------------------------------------------------------ # throw(\@nameargs) [% THROW foo "bar error" %] # # => [ [$type], \@args ] #------------------------------------------------------------------------ sub throw { my ($self, $nameargs) = @_; my ($type, $args) = @$nameargs; my $hash = shift(@$args); my $info = shift(@$args); $type = shift @$type; # uses same parser production as INCLUDE # etc., which allow multiple names # e.g. INCLUDE foo+bar+baz if (! $info) { $args = "$type, undef"; } elsif (@$hash || @$args) { local $" = ', '; my $i = 0; $args = "$type, { args => [ " . join(', ', $info, @$args) . ' ], ' . join(', ', (map { "'" . $i++ . "' => $_" } ($info, @$args)), @$hash) . ' }'; } else { $args = "$type, $info"; } return "\$context->throw($args, \\\$output);"; } #------------------------------------------------------------------------ # clear() [% CLEAR %] # # NOTE: this is redundant, being hard-coded (for now) into Parser.yp #------------------------------------------------------------------------ sub clear { return "\$output = '';"; } #------------------------------------------------------------------------ # break() [% BREAK %] # # NOTE: this is redundant, being hard-coded (for now) into Parser.yp #------------------------------------------------------------------------ sub OLD_break { return 'last LOOP;'; } #------------------------------------------------------------------------ # return() [% RETURN %] #------------------------------------------------------------------------ sub return { return "\$context->throw('return', '', \\\$output);"; } #------------------------------------------------------------------------ # stop() [% STOP %] #------------------------------------------------------------------------ sub stop { return "\$context->throw('stop', '', \\\$output);"; } #------------------------------------------------------------------------ # use(\@lnameargs) [% USE alias = plugin(args) %] # # => [ [$file, ...], \@args, $alias ] #------------------------------------------------------------------------ sub use { my ($self, $lnameargs) = @_; my ($file, $args, $alias) = @$lnameargs; $file = shift @$file; # same production rule as INCLUDE $alias ||= $file; $args = &args($self, $args); $file .= ", $args" if $args; # my $set = &assign($self, $alias, '$plugin'); return "# USE\n" . "\$stash->set($alias,\n" . " \$context->plugin($file));"; } #------------------------------------------------------------------------ # view(\@nameargs, $block) [% VIEW name args %] # # => [ [$file, ... ], \@args ] #------------------------------------------------------------------------ sub view { my ($self, $nameargs, $block, $defblocks) = @_; my ($name, $args) = @$nameargs; my $hash = shift @$args; $name = shift @$name; # same production rule as INCLUDE $block = pad($block, 1) if $PRETTY; if (%$defblocks) { $defblocks = join(",\n", map { "'$_' => $defblocks->{ $_ }" } keys %$defblocks); $defblocks = pad($defblocks, 1) if $PRETTY; $defblocks = "{\n$defblocks\n}"; push(@$hash, "'blocks'", $defblocks); } $hash = @$hash ? '{ ' . join(', ', @$hash) . ' }' : ''; return <<EOF; # VIEW do { my \$output = ''; my \$_tt_oldv = \$stash->get('view'); my \$_tt_view = \$context->view($hash); \$stash->set($name, \$_tt_view); \$stash->set('view', \$_tt_view); $block \$stash->set('view', \$_tt_oldv); \$_tt_view->seal(); # \$output; # not used - commented out to avoid warning }; EOF } #------------------------------------------------------------------------ # perl($block) #------------------------------------------------------------------------ sub perl { my ($self, $block) = @_; $block = pad($block, 1) if $PRETTY; return <<EOF; # PERL \$context->throw('perl', 'EVAL_PERL not set') unless \$context->eval_perl(); $OUTPUT do { my \$output = "package Template::Perl;\\n"; $block local(\$Template::Perl::context) = \$context; local(\$Template::Perl::stash) = \$stash; my \$_tt_result = ''; tie *Template::Perl::PERLOUT, 'Template::TieString', \\\$_tt_result; my \$_tt_save_stdout = select *Template::Perl::PERLOUT; eval \$output; select \$_tt_save_stdout; \$context->throw(\$@) if \$@; \$_tt_result; }; EOF } #------------------------------------------------------------------------ # no_perl() #------------------------------------------------------------------------ sub no_perl { my $self = shift; return "\$context->throw('perl', 'EVAL_PERL not set');"; } #------------------------------------------------------------------------ # rawperl($block) # # NOTE: perhaps test context EVAL_PERL switch at compile time rather than # runtime? #------------------------------------------------------------------------ sub rawperl { my ($self, $block, $line) = @_; for ($block) { s/^\n+//; s/\n+$//; } $block = pad($block, 1) if $PRETTY; $line = $line ? " (starting line $line)" : ''; return <<EOF; # RAWPERL #line 1 "RAWPERL block$line" $block EOF } #------------------------------------------------------------------------ # filter() #------------------------------------------------------------------------ sub filter { my ($self, $lnameargs, $block) = @_; my ($name, $args, $alias) = @$lnameargs; $name = shift @$name; $args = &args($self, $args); $args = $args ? "$args, $alias" : ", undef, $alias" if $alias; $name .= ", $args" if $args; $block = pad($block, 1) if $PRETTY; return <<EOF; # FILTER $OUTPUT do { my \$output = ''; my \$_tt_filter = \$context->filter($name) || \$context->throw(\$context->error); $block &\$_tt_filter(\$output); }; EOF } #------------------------------------------------------------------------ # capture($name, $block) #------------------------------------------------------------------------ sub capture { my ($self, $name, $block) = @_; if (ref $name) { if (scalar @$name == 2 && ! $name->[1]) { $name = $name->[0]; } else { $name = '[' . join(', ', @$name) . ']'; } } $block = pad($block, 1) if $PRETTY; return <<EOF; # CAPTURE \$stash->set($name, do { my \$output = ''; $block \$output; }); EOF } #------------------------------------------------------------------------ # macro($name, $block, \@args) #------------------------------------------------------------------------ sub macro { my ($self, $ident, $block, $args) = @_; $block = pad($block, 2) if $PRETTY; if ($args) { my $nargs = scalar @$args; $args = join(', ', map { "'$_'" } @$args); $args = $nargs > 1 ? "\@_tt_args{ $args } = splice(\@_, 0, $nargs)" : "\$_tt_args{ $args } = shift"; return <<EOF; # MACRO \$stash->set('$ident', sub { my \$output = ''; my (%_tt_args, \$_tt_params); $args; \$_tt_params = shift; \$_tt_params = { } unless ref(\$_tt_params) eq 'HASH'; \$_tt_params = { \%_tt_args, %\$_tt_params }; my \$stash = \$context->localise(\$_tt_params); eval { $block }; \$stash = \$context->delocalise(); die \$@ if \$@; return \$output; }); EOF } else { return <<EOF; # MACRO \$stash->set('$ident', sub { my \$_tt_params = \$_[0] if ref(\$_[0]) eq 'HASH'; my \$output = ''; my \$stash = \$context->localise(\$_tt_params); eval { $block }; \$stash = \$context->delocalise(); die \$@ if \$@; return \$output; }); EOF } } sub debug { my ($self, $nameargs) = @_; my ($file, $args) = @$nameargs; my $hash = shift @$args; $args = join(', ', @$file, @$args); $args .= @$hash ? ', { ' . join(', ', @$hash) . ' }' : ''; return "$OUTPUT \$context->debugging($args); ## DEBUG ##"; } 1; __END__ =head1 NAME Template::Directive - Perl code generator for template directives =head1 SYNOPSIS # no user serviceable parts inside =head1 DESCRIPTION The C<Template::Directive> module defines a number of methods that generate Perl code for the runtime representation of the various Template Toolkit directives. It is used internally by the L<Template::Parser> module. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Parser> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[<ni i lib/Template/Tutorial/Web.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Tutorial::Web # # DESCRIPTION # Tutorial on generating web content with the Template Toolkit # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2008 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Tutorial::Web - Generating Web Content Using the Template Toolkit =head1 Overview This tutorial document provides a introduction to the Template Toolkit and demonstrates some of the typical ways it may be used for generating web content. It covers the generation of static pages from templates using the L<tpage|Template::Tools::tpage> and L<ttree|Template::Tools::ttree> scripts and then goes on to show dynamic content generation using CGI scripts and Apache/mod_perl handlers. Various features of the Template Toolkit are introduced and described briefly and explained by use of example. For further information, see L<Template>, L<Template::Manual> and the various sections within it. e.g perldoc Template # Template.pm module usage perldoc Template::Manual # index to manual perldoc Template::Manual::Config # e.g. configuration options The documentation is also available in HTML format to read online, or download from the Template Toolkit web site: http://template-toolkit.org/docs/ =head1 Introduction The Template Toolkit is a set of Perl modules which collectively implement a template processing system. A template is a text document with special markup tags embedded in it. By default, the Template Toolkit uses 'C<[%>' and 'C<%]>' to denote the start and end of a tag. Here's an example: [% INCLUDE header %] People of [% planet %], your attention please. This is [% captain %] of the Galactic Hyperspace Planning Council. As you will no doubt be aware, the plans for development of the outlying regions of the Galaxy require the building of a hyperspatial express route through your star system, and regrettably your planet is one of those scheduled for destruction. The process will take slightly less than [% time %]. Thank you. [% INCLUDE footer %] Tags can contain simple I<variables> (like C<planet> and C<captain>) and more complex I<directives> that start with an upper case keyword (like C<INCLUDE>). A directive is an instruction that tells the template processor to perform some action, like processing another template (C<header> and C<footer> in this example) and inserting the output into the current template. In fact, the simple variables we mentioned are actually C<GET> directives, but the C<GET> keyword is optional. People of [% planet %], your attention please. # short form People of [% GET planet %], your attention please. # long form Other directives include C<SET> to set a variable value (the C<SET> keyword is also optional), C<FOREACH> to iterate through a list of values, and C<IF>, C<UNLESS>, C<ELSIF> and C<ELSE> to declare conditional blocks. The Template Toolkit processes all I<text> files equally, regardless of what kind of content they contain. So you can use TT to generate HTML, XML, CSS, Javascript, Perl, RTF, LaTeX, or any other text-based format. In this tutorial, however, we'll be concentrating on generating HTML for web pages. =head1 Generating Static Web Content Here's an example of a template used to generate an HTML document. [% INCLUDE header title = 'This is an HTML example'; pages = [ { url = 'http://foo.org' title = 'The Foo Organisation' } { url = 'http://bar.org' title = 'The Bar Organisation' } ] %] <h1>Some Interesting Links</h1> <ul> [% FOREACH page IN pages %] <li><a href="[% page.url %]">[% page.title %]</a> [% END %] </ul> [% INCLUDE footer %] This example shows how the C<INCLUDE> directive is used to load and process separate 'C<header>' and 'C<footer>' template files, including the output in the current document. These files might look something like this: header: <html> <head> <title>[% title %]</title> </head> <body> footer: <div class="copyright"> © Copyright 2007 Arthur Dent </div> </body> </html> The example also uses the C<FOREACH> directive to iterate through the 'C<pages>' list to build a table of links. In this example, we have defined this list within the template to contain a number of hash references, each containing a 'C<url>' and 'C<title>' member. The C<FOREACH> directive iterates through the list, aliasing 'C<page>' to each item (in this case, hash array references). The C<[% page.url %]> and C<[% page.title %]> directives then access the individual values in the hash arrays and insert them into the document. =head2 Using tpage Having created a template file we can now process it to generate some real output. The quickest and easiest way to do this is to use the L<tpage|Template::Tools::tpage> script. This is provided as part of the Template Toolkit and should be installed in your usual Perl bin directory. Assuming you saved your template file as F<example.html>, you would run the command: $ tpage example.html This will process the template file, sending the output to C<STDOUT> (i.e. whizzing past you on the screen). You may want to redirect the output to a file but be careful not to specify the same name as the template file, or you'll overwrite it. You may want to use one prefix for your templates (e.g. 'C<.tt>') and another (e.g. 'C<.html>') for the output files. $ tpage example.tt > example.html Or you can redirect the output to another directory. e.g. $ tpage templates/example.tt > html/example.html The output generated would look like this: <html> <head> <title>This is an HTML example</title> </head> <body> <h1>Some Interesting Links</h1> <ul> <li><a href="http://foo.org">The Foo Organsiation</a> <li><a href="http://bar.org">The Bar Organsiation</a> </ul> <div class="copyright"> © Copyright 2007 Arthur Dent </div> </body> </html> The F<header> and F<footer> template files have been included (assuming you created them and they're in the current directory) and the link data has been built into an HTML list. =head2 Using ttree The L<tpage|Template::Tools::tpage> script gives you a simple and easy way to process a single template without having to write any Perl code. The L<ttree:Template::Tools::ttree> script, also distributed as part of the Template Toolkit, provides a more flexible way to process a number of template documents in one go. The first time you run the script, it will ask you if it should create a configuration file (F<.ttreerc>) in your home directory. Answer C<y> to have it create the file. The L<ttree:Template::Tools::ttree> documentation describes how you can change the location of this file and also explains the syntax and meaning of the various options in the file. Comments are written to the sample configuration file which should also help. In brief, the configuration file describes the directories in which template files are to be found (C<src>), where the corresponding output should be written to (C<dest>), and any other directories (C<lib>) that may contain template files that you plan to C<INCLUDE> into your source documents. You can also specify processing options (such as C<verbose> and C<recurse>) and provide regular expression to match files that you don't want to process (C<ignore>, C<accept>)> or should be copied instead of being processed as templates (C<copy>). An example F<.ttreerc> file is shown here: $HOME/.ttreerc: verbose recurse # this is where I keep other ttree config files cfg = ~/.ttree src = ~/websrc/src lib = ~/websrc/lib dest = ~/public_html/test ignore = \b(CVS|RCS)\b ignore = ^# You can create many different configuration files and store them in the directory specified in the C<cfg> option, shown above. You then add the C<-f filename> option to C<ttree> to have it read that file. When you run the script, it compares all the files in the C<src> directory (including those in sub-directories if the C<recurse> option is set), with those in the C<dest> directory. If the destination file doesn't exist or has an earlier modification time than the corresponding source file, then the source will be processed with the output written to the destination file. The C<-a> option forces all files to be processed, regardless of modification times. The script I<doesn't> process any of the files in the C<lib> directory, but it does add it to the C<INCLUDE_PATH> for the template processor so that it can locate these files via an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive. Thus, the C<lib> directory is an excellent place to keep template elements such as header, footers, etc., that aren't complete documents in their own right. You can also specify various Template Toolkit options from the configuration file. Consult the L<ttree|Template::Tools::ttree> documentation and help summary (C<ttree -h>) for full details. e.g. $HOME/.ttreerc: pre_process = config interpolate post_chomp The C<pre_process> option allows you to specify a template file which should be processed before each file. Unsurprisingly, there's also a C<post_process> option to add a template after each file. In the fragment above, we have specified that the C<config> template should be used as a prefix template. We can create this file in the C<lib> directory and use it to define some common variables, including those web page links we defined earlier and might want to re-use in other templates. We could also include an HTML header, title, or menu bar in this file which would then be prepended to each and every template file, but for now we'll keep all that in a separate C<header> file. $lib/config: [% root = '~/abw' home = "$root/index.html" images = "$root/images" email = 'abw@wardley.org' graphics = 1 webpages = [ { url => 'http://foo.org', title => 'The Foo Organsiation' } { url => 'http://bar.org', title => 'The Bar Organsiation' } ] %] Assuming you've created or copied the C<header> and C<footer> files from the earlier example into your C<lib> directory, you can now start to create web pages like the following in your C<src> directory and process them with C<ttree>. $src/newpage.html: [% INCLUDE header title = 'Another Template Toolkit Test Page' %] <a href="[% home %]">Home</a> <a href="mailto:[% email %]">Email</a> [% IF graphics %] <img src="[% images %]/logo.gif" align=right width=60 height=40> [% END %] [% INCLUDE footer %] Here we've shown how pre-defined variables can be used as flags to enable certain feature (e.g. C<graphics>) and to specify common items such as an email address and URL's for the home page, images directory and so on. This approach allows you to define these values once so that they're consistent across all pages and can easily be changed to new values. When you run F<ttree>, you should see output similar to the following (assuming you have the verbose flag set). ttree 2.9 (Template Toolkit version 2.20) Source: /home/abw/websrc/src Destination: /home/abw/public_html/test Include Path: [ /home/abw/websrc/lib ] Ignore: [ \b(CVS|RCS)\b, ^# ] Copy: [ ] Accept: [ * ] + newpage.html The C<+> in front of the C<newpage.html> filename shows that the file was processed, with the output being written to the destination directory. If you run the same command again, you'll see the following line displayed instead showing a C<-> and giving a reason why the file wasn't processed. - newpage.html (not modified) It has detected a C<newpage.html> in the destination directory which is more recent than that in the source directory and so hasn't bothered to waste time re-processing it. To force all files to be processed, use the C<-a> option. You can also specify one or more filenames as command line arguments to C<ttree>: tpage newpage.html This is what the destination page looks like. $dest/newpage.html: <html> <head> <title>Another Template Toolkit Test Page</title> </head> <body> <a href="~/abw/index.html">Home</a> <a href="mailto:abw@wardley.org">Email me</a> <img src="~/abw/images/logo.gif" align=right width=60 height=40> <div class="copyright"> © Copyright 2007 Arthur Dent </div> </body> </html> You can add as many documents as you like to the C<src> directory and C<ttree> will apply the same process to them all. In this way, it is possible to build an entire tree of static content for a web site with a single command. The added benefit is that you can be assured of consistency in links, header style, or whatever else you choose to implement in terms of common templates elements or variables. =head1 Dynamic Content Generation Via CGI Script The L<Template> module provides a simple front-end to the Template Toolkit for use in CGI scripts and Apache/mod_perl handlers. Simply C<use> the L<Template> module, create an object instance with the L<new()> method and then call the L<process()> method on the object, passing the name of the template file as a parameter. The second parameter passed is a reference to a hash array of variables that we want made available to the template: #!/usr/bin/perl use strict; use warnings; use Template; my $file = 'src/greeting.html'; my $vars = { message => "Hello World\n" }; my $template = Template->new(); $template->process($file, $vars) || die "Template process failed: ", $template->error(), "\n"; So that our scripts will work with the same template files as our earlier examples, we'll can add some configuration options to the constructor to tell it about our environment: my $template->new({ # where to find template files INCLUDE_PATH => ['/home/abw/websrc/src', '/home/abw/websrc/lib'], # pre-process lib/config to define any extra values PRE_PROCESS => 'config', }); Note that here we specify the C<config> file as a C<PRE_PROCESS> option. This means that the templates we process can use the same global variables defined earlier for our static pages. We don't have to replicate their definitions in this script. However, we can supply additional data and functionality specific to this script via the hash of variables that we pass to the C<process()> method. These entries in this hash may contain simple text or other values, references to lists, others hashes, sub-routines or objects. The Template Toolkit will automatically apply the correct procedure to access these different types when you use the variables in a template. Here's a more detailed example to look over. Amongst the different template variables we define in C<$vars>, we create a reference to a L<CGI> object and a C<get_user_projects()> sub-routine. #!/usr/bin/perl use strict; use warnings; use Template; use CGI; $| = 1; print "Content-type: text/html\n\n"; my $file = 'userinfo.html'; my $vars = { 'version' => 3.14, 'days' => [ qw( mon tue wed thu fri sat sun ) ], 'worklist' => \&get_user_projects, 'cgi' => CGI->new(), 'me' => { 'id' => 'abw', 'name' => 'Andy Wardley', }, }; sub get_user_projects { my $user = shift; my @projects = ... # do something to retrieve data return \@projects; } my $template = Template->new({ INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib', PRE_PROCESS => 'config', }); $template->process($file, $vars) || die $template->error(); Here's a sample template file that we might create to build the output for this script. $src/userinfo.html: [% INCLUDE header title = 'Template Toolkit CGI Test' %] <a href="mailto:[% email %]">Email [% me.name %]</a> <p>This is version [% version %]</p> <h3>Projects</h3> <ul> [% FOREACH project IN worklist(me.id) %] <li> <a href="[% project.url %]">[% project.name %]</a> [% END %] </ul> [% INCLUDE footer %] This example shows how we've separated the Perl implementation (code) from the presentation (HTML). This not only makes them easier to maintain in isolation, but also allows the re-use of existing template elements such as headers and footers, etc. By using template to create the output of your CGI scripts, you can give them the same consistency as your static pages built via L<ttree|Template::Tools::ttree> or other means. Furthermore, we can modify our script so that it processes any one of a number of different templates based on some condition. A CGI script to maintain a user database, for example, might process one template to provide an empty form for new users, the same form with some default values set for updating an existing user record, a third template for listing all users in the system, and so on. You can use any Perl functionality you care to write to implement the logic of your application and then choose one or other template to generate the desired output for the application state. =head1 Dynamic Content Generation Via Apache/Mod_Perl Handler B<NOTE:> the L<Apache::Template> module is available from CPAN and provides a simple and easy to use Apache/mod_perl interface to the Template Toolkit. Although basic, it implements most, if not all of what is described below, and it avoids the need to write your own handler. However, in many cases, you'll want to write your own handler to customise processing for your own need, and this section will show you how to get started. The L<Template> module can be used from an Apache/mod_perl handler. Here's an example of a typical Apache F<httpd.conf> file: PerlModule CGI; PerlModule Template PerlModule MyOrg::Apache::User PerlSetVar websrc_root /home/abw/websrc <Location /user/bin> SetHandler perl-script PerlHandler MyOrg::Apache::User </Location> This defines a location called C</user/bin> to which all requests will be forwarded to the C<handler()> method of the C<MyOrg::Apache::User> module. That module might look something like this: package MyOrg::Apache::User; use strict; use Apache::Constants qw( :common ); use Template; use CGI; our $VERSION = 1.59; sub handler { my $r = shift; my $websrc = $r->dir_config('websrc_root') or return fail($r, SERVER_ERROR, "'websrc_root' not specified"); my $template = Template->new({ INCLUDE_PATH => "$websrc/src/user:$websrc/lib", PRE_PROCESS => 'config', OUTPUT => $r, # direct output to Apache request }); my $params = { uri => $r->uri, cgi => CGI->new, }; # use the path_info to determine which template file to process my $file = $r->path_info; $file =~ s[^/][]; $r->content_type('text/html'); $r->send_http_header; $template->process($file, $params) || return fail($r, SERVER_ERROR, $template->error()); return OK; } sub fail { my ($r, $status, $message) = @_; $r->log_reason($message, $r->filename); return $status; } The handler accepts the request and uses it to determine the C<websrc_root> value from the config file. This is then used to define an C<INCLUDE_PATH> for a new L<Template> object. The URI is extracted from the request and a L<CGI> object is created. These are both defined as template variables. The name of the template file itself is taken from the C<PATH_INFO> element of the request. In this case, it would comprise the part of the URL coming after C</user/bin>, e.g for C</user/bin/edit>, the template file would be C<edit> located in C<$websrc/src/user>. The headers are sent and the template file is processed. All output is sent directly to the C<print()> method of the Apache request object. =head1 Using Plugins to Extend Functionality As we've already shown, it is possible to bind Perl data and functions to template variables when creating dynamic content via a CGI script or Apache/mod_perl process. The Template Toolkit also supports a plugin interface which allows you define such additional data and/or functionality in a separate module and then load and use it as required with the C<USE> directive. The main benefit to this approach is that you can load the extension into any template document, even those that are processed "statically" by C<tpage> or C<ttree>. You I<don't> need to write a Perl wrapper to explicitly load the module and make it available via the stash. Let's demonstrate this principle using the C<DBI> plugin written by Simon Matthews (available from CPAN). You can create this template in your C<src> directory and process it using C<ttree> to see the results. Of course, this example relies on the existence of the appropriate SQL database but you should be able to adapt it to your own resources, or at least use it as a demonstrative example of what's possible. [% INCLUDE header title = 'User Info' %] [% USE DBI('dbi:mSQL:mydbname') %] <table border=0 width="100%"> <tr> <th>User ID</th> <th>Name</th> <th>Email</th> </tr> [% FOREACH user IN DBI.query('SELECT * FROM user ORDER BY id') %] <tr> <td>[% user.id %]</td> <td>[% user.name %]</td> <td>[% user.email %]</td> </tr> [% END %] </table> [% INCLUDE footer %] A plugin is simply a Perl module in a known location and conforming to a known standard such that the Template Toolkit can find and load it automatically. You can create your own plugin by inheriting from the L<Template::Plugin> module. Here's an example which defines some data items (C<foo> and C<people>) and also an object method (C<bar>). We'll call the plugin C<FooBar> for want of a better name and create it in the C<MyOrg::Template::Plugin::FooBar> package. We've added a C<MyOrg> to the regular C<Template::Plugin::*> package to avoid any conflict with existing plugins. package MyOrg::Template::Plugin::FooBar; use base 'Template::Plugin' our $VERSION = 1.23; sub new { my ($class, $context, @params) = @_; bless { _CONTEXT => $context, foo => 25, people => [ 'tom', 'dick', 'harry' ], }, $class; } sub bar { my ($self, @params) = @_; # ...do something... return $some_value; } The plugin constructor C<new()> receives the class name as the first parameter, as is usual in Perl, followed by a reference to something called a L<Template::Context> object. You don't need to worry too much about this at the moment, other than to know that it's the main processing object for the Template Toolkit. It provides access to the functionality of the processor and some plugins may need to communicate with it. We don't at this stage, but we'll save the reference anyway in the C<_CONTEXT> member. The leading underscore is a convention which indicates that this item is private and the Template Toolkit won't attempt to access this member. The other members defined, C<foo> and C<people> are regular data items which will be made available to templates using this plugin. Following the context reference are passed any additional parameters specified with the USE directive, such as the data source parameter, C<dbi:mSQL:mydbname>, that we used in the earlier DBI example. If you don't or can't install it to the regular place for your Perl modules (perhaps because you don't have the required privileges) then you can set the PERL5LIB environment variable to specify another location. If you're using C<ttree> then you can add the following line to your configuration file instead. $HOME/.ttreerc: perl5lib = /path/to/modules One further configuration item must be added to inform the toolkit of the new package name we have adopted for our plugins: $HOME/.ttreerc: plugin_base = 'MyOrg::Template::Plugin' If you're writing Perl code to control the L<Template> modules directly, then this value can be passed as a configuration parameter when you create the module. use Template; my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin' }); Now we can create a template which uses this plugin: [% INCLUDE header title = 'FooBar Plugin Test' %] [% USE FooBar %] Some values available from this plugin: [% FooBar.foo %] [% FooBar.bar %] The users defined in the 'people' list: [% FOREACH uid = FooBar.people %] * [% uid %] [% END %] [% INCLUDE footer %] The C<foo>, C<bar>, and C<people> items of the FooBar plugin are automatically resolved to the appropriate data items or method calls on the underlying object. Using this approach, it is possible to create application functionality in a single module which can then be loaded and used on demand in any template. The simple interface between template directives and plugin objects allows complex, dynamic content to be built from a few simple template documents without knowing anything about the underlying implementation. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[���>48 48 " lib/Template/Tutorial/Datafile.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Tutorial::Datafile # # DESCRIPTION # # AUTHOR # Dave Cross <dave@dave.org.uk> # # COPYRIGHT # Copyright (C) 1996-2008 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Tutorial::Datafile - Creating Data Output Files Using the Template Toolkit =head1 DESCRIPTION =head1 Introducing the Template Toolkit There are a number of Perl modules that are universally recognised as The Right Thing To Use for certain tasks. If you accessed a database without using DBI, pulled data from the WWW without using one of the LWP modules or parsed XML without using XML::Parser or one of its subclasses then you'd run the risk of being shunned by polite Perl society. I believe that the year 2000 saw the emergence of another 'must have' Perl module - the Template Toolkit. I don't think I'm alone in this belief as the Template Toolkit won the 'Best New Module' award at the Perl Conference last summer. Version 2.0 of the Template Toolkit (known as TT2 to its friends) was recently released to the CPAN. TT2 was designed and written by Andy Wardley E<lt>abw@wardley.orgE<gt>. It was born out of Andy's previous templating module, Text::Metatext, in best Fred Brooks 'plan to throw one away' manner; and aims to be the most useful (or, at least, the most I<used>) Perl templating system. TT2 provides a way to take a file of fixed boilerplate text (the template) and embed variable data within it. One obvious use of this is in the creation of dynamic web pages and this is where a lot of the attention that TT2 has received has been focussed. In this article, I hope to demonstrate that TT2 is just as useful in non-web applications. =head1 Using the Template Toolkit Let's look at how we'd use TT2 to process a simple data file. TT2 is an object oriented Perl module. Having downloaded it from CPAN and installed it in the usual manner, using it in your program is as easy as putting the lines use Template; my $tt = Template->new; in your code. The constructor function, C<new>, takes a number of optional parameters which are documented in the copious manual pages that come with the module, but for the purposes of this article we'll keep things as simple as possible. To process the template, you would call the C<process> method like this $tt->process('my_template', \%data) || die $tt->error; We pass two parameters to C<process>, the first is the name of the file containing the template to process (in this case, my_template) and the second is a reference to a hash which contains the data items that you want to use in the template. If processing the template gives any kind of error, the program will die with a (hopefully) useful error message. So what kinds of things can go in C<%data>? The answer is just about anything. Here's an example showing data about English Premier League football teams. my @teams = ({ name => 'Man Utd', played => 16, won => 12, drawn => 3, lost => 1 }, { name => 'Bradford', played => 16, won => 2, drawn => 5, lost => 9 }); my %data = ( name => 'English Premier League', season => '2000/01', teams => \@teams ); This creates three data items which can be accessed within the template, called C<name>, C<season> and C<teams>. Notice that C<teams> is a complex data structure. Here is a template that we might use to process this data. League Standings League Name: [% name %] Season : [% season %] Teams: [% FOREACH team = teams -%] [% team.name %] [% team.played -%] [% team.won %] [% team.drawn %] [% team.lost %] [% END %] Running this template with this data gives us the following output League Standings League Name: English Premier League Season : 2000/01 Teams: Man Utd 16 12 3 1 Bradford 16 2 5 9 Hopefully the syntax of the template is simple enough to follow. There are a few points to note. =over 4 =item * Template processing directives are written using a simple language which is not Perl. =item * The keys of the C<%data> have become the names of the data variables within the template. =item * Template processing directives are surrounded by C<[%> and C<%]> sequences. =item * If these tags are replaced with C<[%-> C<-%]> then the preceding or following linefeed is suppressed. =item * In the C<FOREACH> loop, each element of the C<teams> list was assigned, in turn, to the temporary variable C<team>. =item * Each item assigned to the C<team> variable is a Perl hash. Individual values within the hash are accessed using a dot notation. =back It's probably the first and last of these points which are the most important. The first point emphasises the separation of the data acquisition logic from the presentation logic. The person creating the presentation template doesn't need to know Perl, they only need to know the data items which will be passed into the template. The last point demonstrates the way that TT2 protects the template designer from the implementation of the data structures. The data objects passed to the template processor can be scalars, arrays, hashes, objects or even subroutines. The template processor will just interpret your data correctly and Do The Right Thing to return the correct value to you. In this example each team was a hash, but in a larger system each team might be an object, in which case C<name>, C<played>, etc. would be accessor methods to the underlying object attributes. No changes would be required to the template as the template processor would realise that it needed to call methods rather than access hash values. =head2 A more complex example Stats about the English Football League are usually presented in a slightly more complex format than the one we used above. A full set of stats will show the number of games that a team has won, lost or drawn, the number of goals scored for and against the team and the number of points that the team therefore has. Teams gain three points for a win and one point for a draw. When teams have the same number of points they are separated by the goal difference, that is the number of goals the team has scored minus the number of team scored against them. To complicate things even further, the games won, drawn and lost and the goals for and against are often split between home and away games. Therefore if you have a data source which lists the team name together with the games won, drawn and lost and the goals for and against split into home and away (a total of eleven data items) you can calculate all of the other items (goal difference, points awarded and even position in the league). Let's take such a file, but we'll only look at the top three teams. It will look something like this: Man Utd,7,1,0,26,4,5,2,1,15,6 Arsenal,7,1,0,17,4,2,3,3,7,9 Leicester,4,3,1,10,8,4,2,2,7,4 A simple script to read this data into an array of hashes will look something like this (I've simplified the names of the data columns - w, d, and l are games won, drawn and lost and f and a are goals scored for and against; h and a at the front of a data item name indicates whether it's a home or away statistic): my @cols = qw(name hw hd hl hf ha aw ad al af aa); my @teams; while (<>) { chomp; my %team; @team{@cols} = split /,/; push @teams, \%team; } We can then go thru the teams again and calculate all of the derived data items: foreach (@teams) { $_->{w} = $_->{hw} + $_->{aw}; $_->{d} = $_->{hd} + $_->{ad}; $_->{l} = $_->{hl} + $_->{al}; $_->{pl} = $_->{w} + $_->{d} + $_->{l}; $_->{f} = $_->{hf} + $_->{af}; $_->{a} = $_->{ha} + $_->{aa}; $_->{gd} = $_->{f} - $_->{a}; $_->{pt} = (3 * $_->{w}) + $_->{d}; } And then produce a list sorted in descending order: @teams = sort { $b->{pt} <=> $b->{pt} || $b->{gd} <=> $a->{gd} } @teams; And finally add the league position data item: $teams[$_]->{pos} = $_ + 1 foreach 0 .. $#teams; Having pulled all of our data into an internal data structure we can start to produce output using out templates. A template to create a CSV file containing the data split between home and away stats would look like this: [% FOREACH team = teams -%] [% team.pos %],[% team.name %],[% team.pl %],[% team.hw %], [%- team.hd %],[% team.hl %],[% team.hf %],[% team.ha %], [%- team.aw %],[% team.ad %],[% team.al %],[% team.af %], [%- team.aa %],[% team.gd %],[% team.pt %] [%- END %] And processing it like this: $tt->process('split.tt', { teams => \@teams }, 'split.csv') || die $tt->error; produces the following output: 1,Man Utd,16,7,1,0,26,4,5,2,1,15,6,31,39 2,Arsenal,16,7,1,0,17,4,2,3,3,7,9,11,31 3,Leicester,16,4,3,1,10,8,4,2,2,7,4,5,29 Notice that we've introduced the third parameter to C<process>. If this parameter is missing then the TT2 sends its output to C<STDOUT>. If this parameter is a scalar then it is taken as the name of a file to write the output to. This parameter can also be (amongst other things) a filehandle or a reference to an object which is assumed to implement a C<print> method. If we weren't interested in the split between home and away games, then we could use a simpler template like this: [% FOREACH team = teams -%] [% team.pos %],[% team.name %],[% team.pl %],[% team.w %], [%- team.d %],[% team.l %],[% team.f %],[% team.a %], [%- team.aa %],[% team.gd %],[% team.pt %] [% END -%] Which would produce output like this: 1,Man Utd,16,12,3,1,41,10,6,31,39 2,Arsenal,16,9,4,3,24,13,9,11,31 3,Leicester,16,8,5,3,17,12,4,5,29 =head1 Producing XML This is starting to show some of the power and flexibility of TT2, but you may be thinking that you could just as easily produce this output with a C<foreach> loop and a couple of C<print> statements in your code. This is, of course, true; but that's because I've chosen a deliberately simple example to explain the concepts. What if we wanted to produce an XML file containing the data? And what if (as I mentioned earlier) the league data was held in an object? The code would then look even easier as most of the code we've written earlier would be hidden away in C<FootballLeague.pm>. use FootballLeague; use Template; my $league = FootballLeague->new(name => 'English Premier'); my $tt = Template->new; $tt->process('league_xml.tt', { league => $league }) || die $tt->error; And the template in C<league_xml.tt> would look something like this: <?xml version="1.0"?> <!DOCTYPE LEAGUE SYSTEM "league.dtd"> <league name="[% league.name %]" season="[% league.season %]"> [% FOREACH team = league.teams -%] <team name="[% team.name %]" pos="[% team.pos %]" played="[% team.pl %]" goal_diff="[% team.gd %]" points="[% team.pt %]"> <stats type="home"> win="[% team.hw %]" draw="[%- team.hd %]" lose="[% team.hl %]" for="[% team.hf %]" against="[% team.ha %]" /> <stats type="away"> win="[% team.aw %]" draw="[%- team.ad %]" lose="[% team.al %]" for="[% team.af %]" against="[% team.aa %]" /> </team> [% END -%] &/league> Notice that as we've passed the whole object into C<process> then we need to put an extra level of indirection on our template variables - everything is now a component of the C<league> variable. Other than that, everything in the template is very similar to what we've used before. Presumably now C<team.name> calls an accessor function rather than carrying out a hash lookup, but all of this is transparent to our template designer. =head1 Multiple Formats As a final example, let's suppose that we need to create output football league tables in a number of formats. Perhaps we are passing this data on to other people and they can't all use the same format. Some of our users need CSV files and others need XML. Some require data split between home and away matches and other just want the totals. In total, then, we'll need four different templates, but the good news is that they can use the same data object. All the script needs to do is to establish which template is required and process it. use FootballLeague; use Template; my ($name, $type, $stats) = @_; my $league = FootballLeague->new(name => $name); my $tt = Template->new; $tt->process("league_${type}_$stats.tt", { league => $league } "league_$stats.$type") || die $tt->error; For example, you can call this script as league.pl 'English Premier' xml split This will process a template called C<league_xml_split.tt> and put the results in a file called C<league_split.xml>. This starts to show the true strength of the Template Toolkit. If we later wanted to add another file format - perhaps we wanted to create a league table HTML page or even a LaTeX document - then we would just need to create the appropriate template and name it according to our existing naming convention. We would need to make no changes to the code. I hope you can now see why the Template Toolkit is fast becoming an essential part of many people's Perl installation. =head1 AUTHOR Dave Cross E<lt>dave@dave.org.ukE<gt> =head1 VERSION Template Toolkit version 2.19, released on 27 April 2007. =head1 COPYRIGHT Copyright (C) 2001 Dave Cross E<lt>dave@dave.org.ukE<gt> This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�{�� � lib/Template/Plugin/Math.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Math # # DESCRIPTION # Plugin implementing numerous mathematical functions. # # AUTHORS # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2002-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Math; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; our $AUTOLOAD; #------------------------------------------------------------------------ # new($context, \%config) # # This constructor method creates a simple, empty object to act as a # receiver for future object calls. No doubt there are many interesting # configuration options that might be passed, but I'll leave that for # someone more knowledgable in these areas to contribute... #------------------------------------------------------------------------ sub new { my ($class, $context, $config) = @_; $config ||= { }; bless { %$config, }, $class; } sub abs { shift; CORE::abs($_[0]); } sub atan2 { shift; CORE::atan2($_[0], $_[1]); } # prototyped (ugg) sub cos { shift; CORE::cos($_[0]); } sub exp { shift; CORE::exp($_[0]); } sub hex { shift; CORE::hex($_[0]); } sub int { shift; CORE::int($_[0]); } sub log { shift; CORE::log($_[0]); } sub oct { shift; CORE::oct($_[0]); } sub rand { shift; @_ ? CORE::rand($_[0]) : CORE::rand(); } sub sin { shift; CORE::sin($_[0]); } sub sqrt { shift; CORE::sqrt($_[0]); } sub srand { shift; @_ ? CORE::srand($_[0]) : CORE::srand(); } # Use the Math::TrulyRandom module # XXX This is *sloooooooowwwwwwww* sub truly_random { eval { require Math::TrulyRandom; } or die(Template::Exception->new("plugin", "Can't load Math::TrulyRandom")); return Math::TrulyRandom::truly_random_value(); } eval { require Math::Trig; no strict qw(refs); for my $trig_func (@Math::Trig::EXPORT) { my $sub = Math::Trig->can($trig_func); *{$trig_func} = sub { shift; &$sub(@_) }; } }; # To catch errors from a missing Math::Trig sub AUTOLOAD { return; } 1; __END__ =head1 NAME Template::Plugin::Math - Plugin providing mathematical functions =head1 SYNOPSIS [% USE Math %] [% Math.sqrt(9) %] =head1 DESCRIPTION The Math plugin provides numerous mathematical functions for use within templates. =head1 METHODS C<Template::Plugin::Math> makes available the following functions from the Perl core: =over 4 =item abs =item atan2 =item cos =item exp =item hex =item int =item log =item oct =item rand =item sin =item sqrt =item srand =back In addition, if the L<Math::Trig> module can be loaded, the following functions are also available: =over 4 =item pi =item tan =item csc =item cosec =item sec =item cot =item cotan =item asin =item acos =item atan =item acsc =item acosec =item asec =item acot =item acotan =item sinh =item cosh =item tanh =item csch =item cosech =item sech =item coth =item cotanh =item asinh =item acosh =item atanh =item acsch =item acosech =item asech =item acoth =item acotanh =item rad2deg =item rad2grad =item deg2rad =item deg2grad =item grad2rad =item grad2deg =back If the L<Math::TrulyRandom> module is available, and you've got the time to wait, the C<truly_random_number> method is available: [% Math.truly_random_number %] =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[���� � lib/Template/Plugin/Datafile.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Datafile # # DESCRIPTION # Template Toolkit Plugin which reads a datafile and constructs a # list object containing hashes representing records in the file. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Datafile; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; sub new { my ($class, $context, $filename, $params) = @_; my ($delim, $encoding, $line, @fields, @data, @results); my $self = [ ]; local *FD; local $/ = "\n"; $params ||= { }; $delim = $params->{'delim'} || ':'; $delim = quotemeta($delim); $encoding = defined $params->{'encoding'} ? ':encoding('.$params->{'encoding'}.')' : ''; return $class->error("No filename specified") unless $filename; open(FD, '<'.$encoding, $filename) || return $class->error("$filename: $!"); # first line of file should contain field definitions while (! $line || $line =~ /^#/) { $line = <FD>; chomp $line; $line =~ s/\r$//; } (@fields = split(/\s*$delim\s*/, $line)) || return $class->error("first line of file must contain field names"); # read each line of the file while (<FD>) { chomp; s/\r$//; # ignore comments and blank lines next if /^#/ || /^\s*$/; # split line into fields @data = split(/\s*$delim\s*/); # create hash record to represent data my %record; @record{ @fields } = @data; push(@$self, \%record); } # return $self; bless $self, $class; } sub as_list { return $_[0]; } 1; __END__ =head1 NAME Template::Plugin::Datafile - Plugin to construct records from a simple data file =head1 SYNOPSIS [% USE mydata = datafile('/path/to/datafile') %] [% USE mydata = datafile('/path/to/datafile', delim = '|') %] [% USE mydata = datafile('/path/to/datafile', encoding = 'UTF-8') %] [% FOREACH record = mydata %] [% record.this %] [% record.that %] [% END %] =head1 DESCRIPTION This plugin provides a simple facility to construct a list of hash references, each of which represents a data record of known structure, from a data file. [% USE datafile(filename) %] A absolute filename must be specified (for this initial implementation at least - in a future version it might also use the C<INCLUDE_PATH>). An optional C<delim> parameter may also be provided to specify an alternate delimiter character. The optional C<encoding> parameter may be used to specify the input file encoding. [% USE userlist = datafile('/path/to/file/users') %] [% USE things = datafile('items', delim = '|') %] The format of the file is intentionally simple. The first line defines the field names, delimited by colons with optional surrounding whitespace. Subsequent lines then defines records containing data items, also delimited by colons. e.g. id : name : email : tel abw : Andy Wardley : abw@tt2.org : 555-1234 sam : Simon Matthews : sam@tt2.org : 555-9876 Each line is read, split into composite fields, and then used to initialise a hash array containing the field names as relevant keys. The plugin returns a blessed list reference containing the hash references in the order as defined in the file. [% FOREACH user = userlist %] [% user.id %]: [% user.name %] [% END %] The first line of the file B<must> contain the field definitions. After the first line, blank lines will be ignored, along with comment line which start with a 'C<#>'. =head1 BUGS Should handle file names relative to C<INCLUDE_PATH>. Doesn't permit use of 'C<:>' in a field. Some escaping mechanism is required. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�6@� � lib/Template/Plugin/View.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::View # # DESCRIPTION # A user-definable view based on templates. Similar to the concept of # a "Skin". # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::View; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; use Template::View; #------------------------------------------------------------------------ # new($context, \%config) #------------------------------------------------------------------------ sub new { my $class = shift; my $context = shift; my $view = Template::View->new($context, @_) || return $class->error($Template::View::ERROR); $view->seal(); return $view; } 1; __END__ =head1 NAME Template::Plugin::View - Plugin to create views (Template::View) =head1 SYNOPSIS [% USE view( prefix = 'splash/' # template prefix/suffix suffix = '.tt2' bgcol = '#ffffff' # and any other variables you style = 'Fancy HTML' # care to define as view metadata, items = [ foo, bar.baz ] # including complex data and foo = bar ? baz : x.y.z # expressions %] [% view.title %] # access view metadata [% view.header(title = 'Foo!') %] # view "methods" process blocks or [% view.footer %] # templates with prefix/suffix added =head1 DESCRIPTION This plugin module creates L<Template::View> objects. Views are an experimental feature and are subject to change in the near future. In the mean time, please consult L<Template::View> for further info. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Template::View>, L<Template::Manual::Views> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[���& �& lib/Template/Plugin/Filter.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Filter # # DESCRIPTION # Template Toolkit module implementing a base class plugin # object which acts like a filter and can be used with the # FILTER directive. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2001-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Filter; use strict; use warnings; use base 'Template::Plugin'; use Scalar::Util 'weaken', 'isweak'; our $VERSION = '3.100'; our $DYNAMIC = 0 unless defined $DYNAMIC; sub new { my ($class, $context, @args) = @_; my $config = @args && ref $args[-1] eq 'HASH' ? pop(@args) : { }; # look for $DYNAMIC my $dynamic; { no strict 'refs'; $dynamic = ${"$class\::DYNAMIC"}; } $dynamic = $DYNAMIC unless defined $dynamic; my $self = bless { _CONTEXT => $context, _DYNAMIC => $dynamic, _ARGS => \@args, _CONFIG => $config, }, $class; return $self->init($config) || $class->error($self->error()); } sub init { my ($self, $config) = @_; return $self; } sub factory { my $self = shift; my $this = $self; # avoid a memory leak weaken( $this->{_CONTEXT} ) if ref $this->{_CONTEXT} && !isweak $this->{_CONTEXT}; if ($self->{ _DYNAMIC }) { return [ sub { my ($context, @args) = @_; my $config = ref $args[-1] eq 'HASH' ? pop(@args) : { }; return sub { $this->filter(shift, \@args, $config); }; }, 1 ]; } else { return sub { $this->filter(shift); }; } } sub filter { my ($self, $text, $args, $config) = @_; return $text; } sub merge_config { my ($self, $newcfg) = @_; my $owncfg = $self->{ _CONFIG }; return $owncfg unless $newcfg; return { %$owncfg, %$newcfg }; } sub merge_args { my ($self, $newargs) = @_; my $ownargs = $self->{ _ARGS }; return $ownargs unless $newargs; return [ @$ownargs, @$newargs ]; } sub install_filter { my ($self, $name) = @_; $self->{ _CONTEXT }->define_filter( $name => $self->factory ); return $self; } 1; __END__ =head1 NAME Template::Plugin::Filter - Base class for plugin filters =head1 SYNOPSIS package MyOrg::Template::Plugin::MyFilter; use Template::Plugin::Filter; use base qw( Template::Plugin::Filter ); sub filter { my ($self, $text) = @_; # ...mungify $text... return $text; } # now load it... [% USE MyFilter %] # ...and use the returned object as a filter [% FILTER $MyFilter %] ... [% END %] =head1 DESCRIPTION This module implements a base class for plugin filters. It hides the underlying complexity involved in creating and using filters that get defined and made available by loading a plugin. To use the module, simply create your own plugin module that is inherited from the C<Template::Plugin::Filter> class. package MyOrg::Template::Plugin::MyFilter; use Template::Plugin::Filter; use base qw( Template::Plugin::Filter ); Then simply define your C<filter()> method. When called, you get passed a reference to your plugin object (C<$self>) and the text to be filtered. sub filter { my ($self, $text) = @_; # ...mungify $text... return $text; } To use your custom plugin, you have to make sure that the Template Toolkit knows about your plugin namespace. my $tt2 = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin', }); Or for individual plugins you can do it like this: my $tt2 = Template->new({ PLUGINS => { MyFilter => 'MyOrg::Template::Plugin::MyFilter', }, }); Then you C<USE> your plugin in the normal way. [% USE MyFilter %] The object returned is stored in the variable of the same name, 'C<MyFilter>'. When you come to use it as a C<FILTER>, you should add a dollar prefix. This indicates that you want to use the filter stored in the variable 'C<MyFilter>' rather than the filter named 'C<MyFilter>', which is an entirely different thing (see later for information on defining filters by name). [% FILTER $MyFilter %] ...text to be filtered... [% END %] You can, of course, assign it to a different variable. [% USE blat = MyFilter %] [% FILTER $blat %] ...text to be filtered... [% END %] Any configuration parameters passed to the plugin constructor from the C<USE> directive are stored internally in the object for inspection by the C<filter()> method (or indeed any other method). Positional arguments are stored as a reference to a list in the C<_ARGS> item while named configuration parameters are stored as a reference to a hash array in the C<_CONFIG> item. For example, loading a plugin as shown here: [% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %] would allow the C<filter()> method to do something like this: sub filter { my ($self, $text) = @_; my $args = $self->{ _ARGS }; # [ 'foo', 'bar' ] my $conf = $self->{ _CONFIG }; # { baz => 'blam' } # ...munge $text... return $text; } By default, plugins derived from this module will create static filters. A static filter is created once when the plugin gets loaded via the C<USE> directive and re-used for all subsequent C<FILTER> operations. That means that any argument specified with the C<FILTER> directive are ignored. Dynamic filters, on the other hand, are re-created each time they are used by a C<FILTER> directive. This allows them to act on any parameters passed from the C<FILTER> directive and modify their behaviour accordingly. There are two ways to create a dynamic filter. The first is to define a C<$DYNAMIC> class variable set to a true value. package MyOrg::Template::Plugin::MyFilter; use base 'Template::Plugin::Filter'; our $DYNAMIC = 1; The other way is to set the internal C<_DYNAMIC> value within the C<init()> method which gets called by the C<new()> constructor. sub init { my $self = shift; $self->{ _DYNAMIC } = 1; return $self; } When this is set to a true value, the plugin will automatically create a dynamic filter. The outcome is that the C<filter()> method will now also get passed a reference to an array of positional arguments and a reference to a hash array of named parameters. So, using a plugin filter like this: [% FILTER $blat 'foo' 'bar' baz = 'blam' %] would allow the C<filter()> method to work like this: sub filter { my ($self, $text, $args, $conf) = @_; # $args = [ 'foo', 'bar' ] # $conf = { baz => 'blam' } } In this case can pass parameters to both the USE and FILTER directives, so your filter() method should probably take that into account. [% USE MyFilter 'foo' wiz => 'waz' %] [% FILTER $MyFilter 'bar' biz => 'baz' %] ... [% END %] You can use the C<merge_args()> and C<merge_config()> methods to do a quick and easy job of merging the local (e.g. C<FILTER>) parameters with the internal (e.g. C<USE>) values and returning new sets of conglomerated data. sub filter { my ($self, $text, $args, $conf) = @_; $args = $self->merge_args($args); $conf = $self->merge_config($conf); # $args = [ 'foo', 'bar' ] # $conf = { wiz => 'waz', biz => 'baz' } ... } You can also have your plugin install itself as a named filter by calling the C<install_filter()> method from the C<init()> method. You should provide a name for the filter, something that you might like to make a configuration option. sub init { my $self = shift; my $name = $self->{ _CONFIG }->{ name } || 'myfilter'; $self->install_filter($name); return $self; } This allows the plugin filter to be used as follows: [% USE MyFilter %] [% FILTER myfilter %] ... [% END %] or [% USE MyFilter name = 'swipe' %] [% FILTER swipe %] ... [% END %] Alternately, you can allow a filter name to be specified as the first positional argument. sub init { my $self = shift; my $name = $self->{ _ARGS }->[0] || 'myfilter'; $self->install_filter($name); return $self; } [% USE MyFilter 'swipe' %] [% FILTER swipe %] ... [% END %] =head1 EXAMPLE Here's a complete example of a plugin filter module. package My::Template::Plugin::Change; use Template::Plugin::Filter; use base qw( Template::Plugin::Filter ); sub init { my $self = shift; $self->{ _DYNAMIC } = 1; # first arg can specify filter name $self->install_filter($self->{ _ARGS }->[0] || 'change'); return $self; } sub filter { my ($self, $text, $args, $config) = @_; $config = $self->merge_config($config); my $regex = join('|', keys %$config); $text =~ s/($regex)/$config->{ $1 }/ge; return $text; } 1; =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Template::Filters>, L<Template::Manual::Filters> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[ng��r r lib/Template/Plugin/Pod.pmnu ��6�$ #============================================================================== # # Template::Plugin::Pod # # DESCRIPTION # Pod parser and object model. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Pod; use strict; use warnings; use base 'Template::Plugin'; use Pod::POM; our $VERSION = '3.100'; #------------------------------------------------------------------------ # new($context, \%config) #------------------------------------------------------------------------ sub new { my $class = shift; my $context = shift; Pod::POM->new(@_); } 1; __END__ =head1 NAME Template::Plugin::Pod - Plugin interface to Pod::POM (Pod Object Model) =head1 SYNOPSIS [% USE Pod(podfile) %] [% FOREACH head1 = Pod.head1; FOREACH head2 = head1/head2; ... END; END %] =head1 DESCRIPTION This plugin is an interface to the L<Pod::POM> module. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Pod::POM> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[]>&��+ �+ lib/Template/Plugin/File.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::File # # DESCRIPTION # Plugin for encapsulating information about a system file. # # AUTHOR # Originally written by Michael Stevens <michael@etla.org> as the # Directory plugin, then mutilated by Andy Wardley <abw@kfs.org> # into separate File and Directory plugins, with some additional # code for working with views, etc. # # COPYRIGHT # Copyright 2000-2022 Michael Stevens, Andy Wardley. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::File; use strict; use warnings; use Cwd; use File::Spec; use File::Basename; use base 'Template::Plugin'; our $VERSION = '3.100'; our @STAT_KEYS = qw( dev ino mode nlink uid gid rdev size atime mtime ctime blksize blocks ); #------------------------------------------------------------------------ # new($context, $file, \%config) # # Create a new File object. Takes the pathname of the file as # the argument following the context and an optional # hash reference of configuration parameters. #------------------------------------------------------------------------ sub new { my $config = ref($_[-1]) eq 'HASH' ? pop(@_) : { }; my ($class, $context, $path) = @_; my ($root, $home, @stat, $abs); return $class->throw('no file specified') unless defined $path and length $path; # path, dir, name, root, home if (File::Spec->file_name_is_absolute($path)) { $root = ''; } elsif (($root = $config->{ root })) { # strip any trailing '/' from root $root =~ s[/$][]; } else { $root = ''; } my ($name, $dir, $ext) = fileparse($path, '\.\w+'); # fixup various items $dir =~ s[/$][]; $dir = '' if $dir eq '.'; $name = $name . $ext; $ext =~ s/^\.//g; my @fields = File::Spec->splitdir($dir); shift @fields if @fields && ! length $fields[0]; $home = join('/', ('..') x @fields); $abs = File::Spec->catfile($root ? $root : (), $path); my $self = { path => $path, name => $name, root => $root, home => $home, dir => $dir, ext => $ext, abs => $abs, user => '', group => '', isdir => '', stat => defined $config->{ stat } ? $config->{ stat } : ! $config->{ nostat }, map { ($_ => '') } @STAT_KEYS, }; if ($self->{ stat }) { (@stat = stat( $abs )) || return $class->throw("$abs: $!"); @$self{ @STAT_KEYS } = @stat; unless ($config->{ noid }) { $self->{ user } = eval { getpwuid( $self->{ uid }) || $self->{ uid } }; $self->{ group } = eval { getgrgid( $self->{ gid }) || $self->{ gid } }; } $self->{ isdir } = -d $abs; } bless $self, $class; } #------------------------------------------------------------------------- # rel($file) # # Generate a relative filename for some other file relative to this one. #------------------------------------------------------------------------ sub rel { my ($self, $path) = @_; $path = $path->{ path } if ref $path eq ref $self; # assumes same root return $path if $path =~ m[^/]; return $path unless $self->{ home }; return $self->{ home } . '/' . $path; } #------------------------------------------------------------------------ # present($view) # # Present self to a Template::View. #------------------------------------------------------------------------ sub present { my ($self, $view) = @_; $view->view_file($self); } sub throw { my ($self, $error) = @_; die (Template::Exception->new('File', $error)); } 1; __END__ =head1 NAME Template::Plugin::File - Plugin providing information about files =head1 SYNOPSIS [% USE File(filepath) %] [% File.path %] # full path [% File.name %] # filename [% File.dir %] # directory =head1 DESCRIPTION This plugin provides an abstraction of a file. It can be used to fetch details about files from the file system, or to represent abstract files (e.g. when creating an index page) that may or may not exist on a file system. A file name or path should be specified as a constructor argument. e.g. [% USE File('foo.html') %] [% USE File('foo/bar/baz.html') %] [% USE File('/foo/bar/baz.html') %] The file should exist on the current file system (unless C<nostat> option set, see below) as an absolute file when specified with as leading 'C</>' as per 'C</foo/bar/baz.html>', or otherwise as one relative to the current working directory. The constructor performs a C<stat()> on the file and makes the 13 elements returned available as the plugin items: dev ino mode nlink uid gid rdev size atime mtime ctime blksize blocks e.g. [% USE File('/foo/bar/baz.html') %] [% File.mtime %] [% File.mode %] ... In addition, the C<user> and C<group> items are set to contain the user and group names as returned by calls to C<getpwuid()> and C<getgrgid()> for the file C<uid> and C<gid> elements, respectively. On Win32 platforms on which C<getpwuid()> and C<getgrid()> are not available, these values are undefined. [% USE File('/tmp/foo.html') %] [% File.uid %] # e.g. 500 [% File.user %] # e.g. abw This user/group lookup can be disabled by setting the C<noid> option. [% USE File('/tmp/foo.html', noid=1) %] [% File.uid %] # e.g. 500 [% File.user %] # nothing The C<isdir> flag will be set if the file is a directory. [% USE File('/tmp') %] [% File.isdir %] # 1 If the C<stat()> on the file fails (e.g. file doesn't exists, bad permission, etc) then the constructor will throw a C<File> exception. This can be caught within a C<TRY...CATCH> block. [% TRY %] [% USE File('/tmp/myfile') %] File exists! [% CATCH File %] File error: [% error.info %] [% END %] Note the capitalisation of the exception type, 'C<File>', to indicate an error thrown by the C<File> plugin, to distinguish it from a regular C<file> exception thrown by the Template Toolkit. Note that the C<File> plugin can also be referenced by the lower case name 'C<file>'. However, exceptions are always thrown of the C<File> type, regardless of the capitalisation of the plugin named used. [% USE file('foo.html') %] [% file.mtime %] As with any other Template Toolkit plugin, an alternate name can be specified for the object created. [% USE foo = file('foo.html') %] [% foo.mtime %] The C<nostat> option can be specified to prevent the plugin constructor from performing a C<stat()> on the file specified. In this case, the file does not have to exist in the file system, no attempt will be made to verify that it does, and no error will be thrown if it doesn't. The entries for the items usually returned by C<stat()> will be set empty. [% USE file('/some/where/over/the/rainbow.html', nostat=1) [% file.mtime %] # nothing =head1 METHODS All C<File> plugins, regardless of the C<nostat> option, have set a number of items relating to the original path specified. =head2 path The full, original file path specified to the constructor. [% USE file('/foo/bar.html') %] [% file.path %] # /foo/bar.html =head2 name The name of the file without any leading directories. [% USE file('/foo/bar.html') %] [% file.name %] # bar.html =head2 dir The directory element of the path with the filename removed. [% USE file('/foo/bar.html') %] [% file.name %] # /foo =head2 ext The file extension, if any, appearing at the end of the path following a 'C<.>' (not included in the extension). [% USE file('/foo/bar.html') %] [% file.ext %] # html =head2 home This contains a string of the form 'C<../..>' to represent the upward path from a file to its root directory. [% USE file('bar.html') %] [% file.home %] # nothing [% USE file('foo/bar.html') %] [% file.home %] # .. [% USE file('foo/bar/baz.html') %] [% file.home %] # ../.. =head2 root The C<root> item can be specified as a constructor argument, indicating a root directory in which the named file resides. This is otherwise set empty. [% USE file('foo/bar.html', root='/tmp') %] [% file.root %] # /tmp =head2 abs This returns the absolute file path by constructing a path from the C<root> and C<path> options. [% USE file('foo/bar.html', root='/tmp') %] [% file.path %] # foo/bar.html [% file.root %] # /tmp [% file.abs %] # /tmp/foo/bar.html =head2 rel(path) This returns a relative path from the current file to another path specified as an argument. It is constructed by appending the path to the 'C<home>' item. [% USE file('foo/bar/baz.html') %] [% file.rel('wiz/waz.html') %] # ../../wiz/waz.html =head1 EXAMPLES [% USE file('/foo/bar/baz.html') %] [% file.path %] # /foo/bar/baz.html [% file.dir %] # /foo/bar [% file.name %] # baz.html [% file.home %] # ../.. [% file.root %] # '' [% file.abs %] # /foo/bar/baz.html [% file.ext %] # html [% file.mtime %] # 987654321 [% file.atime %] # 987654321 [% file.uid %] # 500 [% file.user %] # abw [% USE file('foo.html') %] [% file.path %] # foo.html [% file.dir %] # '' [% file.name %] # foo.html [% file.root %] # '' [% file.home %] # '' [% file.abs %] # foo.html [% USE file('foo/bar/baz.html') %] [% file.path %] # foo/bar/baz.html [% file.dir %] # foo/bar [% file.name %] # baz.html [% file.root %] # '' [% file.home %] # ../.. [% file.abs %] # foo/bar/baz.html [% USE file('foo/bar/baz.html', root='/tmp') %] [% file.path %] # foo/bar/baz.html [% file.dir %] # foo/bar [% file.name %] # baz.html [% file.root %] # /tmp [% file.home %] # ../.. [% file.abs %] # /tmp/foo/bar/baz.html # calculate other file paths relative to this file and its root [% USE file('foo/bar/baz.html', root => '/tmp/tt2') %] [% file.path('baz/qux.html') %] # ../../baz/qux.html [% file.dir('wiz/woz.html') %] # ../../wiz/woz.html =head1 AUTHORS Michael Stevens wrote the original C<Directory> plugin on which this is based. Andy Wardley split it into separate C<File> and C<Directory> plugins, added some extra code and documentation for C<VIEW> support, and made a few other minor tweaks. =head1 COPYRIGHT Copyright 2000-2022 Michael Stevens, Andy Wardley. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Template::Plugin::Directory>, L<Template::View> PK � �[���1 �1 lib/Template/Plugin/Table.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Table # # DESCRIPTION # Plugin to order a linear data set into a virtual 2-dimensional table # from which row and column permutations can be fetched. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Table; use strict; use warnings; use base 'Template::Plugin'; use Scalar::Util 'blessed'; our $VERSION = '3.100'; our $AUTOLOAD; #------------------------------------------------------------------------ # new($context, \@data, \%args) # # This constructor method initialises the object to iterate through # the data set passed by reference to a list as the first parameter. # It calculates the shape of the permutation table based on the ROWS # or COLS parameters specified in the $args hash reference. The # OVERLAP parameter may be provided to specify the number of common # items that should be shared between subsequent columns. #------------------------------------------------------------------------ sub new { my ($class, $context, $data, $params) = @_; my ($size, $rows, $cols, $coloff, $overlap, $error); # if the data item is a reference to a Template::Iterator object, # or subclass thereof, we call its get_all() method to extract all # the data it contains if (blessed($data) && $data->isa('Template::Iterator')) { ($data, $error) = $data->get_all(); return $class->error( "iterator failed to provide data for table: ", $error ) if $error; } return $class->error('invalid table data, expecting a list') unless ref $data eq 'ARRAY'; $params ||= { }; return $class->error('invalid table parameters, expecting a hash') unless ref $params eq 'HASH'; # ensure keys are folded to upper case @$params{ map { uc } keys %$params } = values %$params; $size = scalar @$data; $overlap = $params->{ OVERLAP } || 0; # calculate number of columns based on a specified number of rows if ($rows = $params->{ ROWS }) { if ($size < $rows) { $rows = $size; # pad? $cols = 1; $coloff = 0; } else { $coloff = $rows - $overlap; $cols = int ($size / $coloff) + ($size % $coloff > $overlap ? 1 : 0) } } # calculate number of rows based on a specified number of columns elsif ($cols = $params->{ COLS }) { if ($size < $cols) { $cols = $size; $rows = 1; $coloff = 1; } else { $coloff = int ($size / $cols) + ($size % $cols > $overlap ? 1 : 0); $rows = $coloff + $overlap; } } else { $rows = $size; $cols = 1; $coloff = 0; } bless { _DATA => $data, _SIZE => $size, _NROWS => $rows, _NCOLS => $cols, _COLOFF => $coloff, _OVERLAP => $overlap, _PAD => defined $params->{ PAD } ? $params->{ PAD } : 1, }, $class; } #------------------------------------------------------------------------ # row($n) # # Returns a reference to a list containing the items in the row whose # number is specified by parameter. If the row number is undefined, # it calls rows() to return a list of all rows. #------------------------------------------------------------------------ sub row { my ($self, $row) = @_; my ($data, $cols, $offset, $size, $pad) = @$self{ qw( _DATA _NCOLS _COLOFF _SIZE _PAD) }; my @set; # return all rows if row number not specified return $self->rows() unless defined $row; return () if $row >= $self->{ _NROWS } || $row < 0; my $index = $row; for (my $c = 0; $c < $cols; $c++) { push( @set, $index < $size ? $data->[$index] : ($pad ? undef : ()) ); $index += $offset; } return \@set; } #------------------------------------------------------------------------ # col($n) # # Returns a reference to a list containing the items in the column whose # number is specified by parameter. If the column number is undefined, # it calls cols() to return a list of all columns. #------------------------------------------------------------------------ sub col { my ($self, $col) = @_; my ($data, $size) = @$self{ qw( _DATA _SIZE ) }; my ($start, $end); my $blanks = 0; # return all cols if row number not specified return $self->cols() unless defined $col; return () if $col >= $self->{ _NCOLS } || $col < 0; $start = $self->{ _COLOFF } * $col; $end = $start + $self->{ _NROWS } - 1; $end = $start if $end < $start; if ($end >= $size) { $blanks = ($end - $size) + 1; $end = $size - 1; } return () if $start >= $size; return [ @$data[$start..$end], $self->{ _PAD } ? ((undef) x $blanks) : () ]; } #------------------------------------------------------------------------ # rows() # # Returns all rows as a reference to a list of rows. #------------------------------------------------------------------------ sub rows { my $self = shift; return [ map { $self->row($_) } (0..$self->{ _NROWS }-1) ]; } #------------------------------------------------------------------------ # cols() # # Returns all rows as a reference to a list of rows. #------------------------------------------------------------------------ sub cols { my $self = shift; return [ map { $self->col($_) } (0..$self->{ _NCOLS }-1) ]; } #------------------------------------------------------------------------ # AUTOLOAD # # Provides read access to various internal data members. #------------------------------------------------------------------------ sub AUTOLOAD { my $self = shift; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; if ($item =~ /^(?:data|size|nrows|ncols|overlap|pad)$/) { return $self->{ $item }; } else { return (undef, "no such table method: $item"); } } 1; __END__ =head1 NAME Template::Plugin::Table - Plugin to present data in a table =head1 SYNOPSIS [% USE table(list, rows=n, cols=n, overlap=n, pad=0) %] [% FOREACH item IN table.row(n) %] [% item %] [% END %] [% FOREACH item IN table.col(n) %] [% item %] [% END %] [% FOREACH row IN table.rows %] [% FOREACH item IN row %] [% item %] [% END %] [% END %] [% FOREACH col IN table.cols %] [% col.first %] - [% col.last %] ([% col.size %] entries) [% END %] =head1 DESCRIPTION The C<Table> plugin allows you to format a list of data items into a virtual table. When you create a C<Table> plugin via the C<USE> directive, simply pass a list reference as the first parameter and then specify a fixed number of rows or columns. [% USE Table(list, rows=5) %] [% USE table(list, cols=5) %] The C<Table> plugin name can also be specified in lower case as shown in the second example above. You can also specify an alternative variable name for the plugin as per regular Template Toolkit syntax. [% USE mydata = table(list, rows=5) %] The plugin then presents a table based view on the data set. The data isn't actually reorganised in any way but is available via the C<row()>, C<col()>, C<rows()> and C<cols()> as if formatted into a simple two dimensional table of C<n> rows x C<n> columns. So if we had a sample C<alphabet> list contained the letters 'C<a>' to 'C<z>', the above C<USE> directives would create plugins that represented the following views of the alphabet. [% USE table(alphabet, ... %] rows=5 cols=5 a f k p u z a g m s y b g l q v b h n t z c h m r w c i o u d i n s x d j p v e j o t y e k q w f l r x We can request a particular row or column using the C<row()> and C<col()> methods. [% USE table(alphabet, rows=5) %] [% FOREACH item = table.row(0) %] # [% item %] set to each of [ a f k p u z ] in turn [% END %] [% FOREACH item = table.col(2) %] # [% item %] set to each of [ m n o p q r ] in turn [% END %] Data in rows is returned from left to right, columns from top to bottom. The first row/column is 0. By default, rows or columns that contain empty values will be padded with the undefined value to fill it to the same size as all other rows or columns. For example, the last row (row 4) in the first example would contain the values C<[ e j o t y undef ]>. The Template Toolkit will safely accept these undefined values and print a empty string. You can also use the IF directive to test if the value is set. [% FOREACH item = table.row(4) %] [% IF item %] Item: [% item %] [% END %] [% END %] You can explicitly disable the C<pad> option when creating the plugin to returned shortened rows/columns where the data is empty. [% USE table(alphabet, cols=5, pad=0) %] [% FOREACH item = table.col(4) %] # [% item %] set to each of 'y z' [% END %] The C<rows()> method returns all rows/columns in the table as a reference to a list of rows (themselves list references). The C<row()> methods when called without any arguments calls C<rows()> to return all rows in the table. Ditto for C<cols()> and C<col()>. [% USE table(alphabet, cols=5) %] [% FOREACH row = table.rows %] [% FOREACH item = row %] [% item %] [% END %] [% END %] The Template Toolkit provides the C<first>, C<last> and C<size> virtual methods that can be called on list references to return the first/last entry or the number of entries in a list. The following example shows how we might use this to provide an alphabetical index split into 3 even parts. [% USE table(alphabet, cols=3, pad=0) %] [% FOREACH group = table.col %] [ [% group.first %] - [% group.last %] ([% group.size %] letters) ] [% END %] This produces the following output: [ a - i (9 letters) ] [ j - r (9 letters) ] [ s - z (8 letters) ] We can also use the general purpose C<join> virtual method which joins the items of the list using the connecting string specified. [% USE table(alphabet, cols=5) %] [% FOREACH row = table.rows %] [% row.join(' - ') %] [% END %] Data in the table is ordered downwards rather than across but can easily be transformed on output. For example, to format our data in 5 columns with data ordered across rather than down, we specify C<rows=5> to order the data as such: a f . . b g . c h d i e j and then iterate down through each column (a-e, f-j, etc.) printing the data across. a b c d e f g h i j . . . Example code to do so would be much like the following: [% USE table(alphabet, rows=3) %] [% FOREACH cols = table.cols %] [% FOREACH item = cols %] [% item %] [% END %] [% END %] Output: a b c d e f g h i j . . . In addition to a list reference, the C<Table> plugin constructor may be passed a reference to a L<Template::Iterator> object or subclass thereof. The L<Template::Iterator> L<get_all()|Template::Iterator#get_all()> method is first called on the iterator to return all remaining items. These are then available via the usual Table interface. [% USE DBI(dsn,user,pass) -%] # query() returns an iterator [% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %] # pass into Table plugin [% USE table(results, rows=8 overlap=1 pad=0) -%] [% FOREACH row = table.cols -%] [% row.first.letter %] - [% row.last.letter %]: [% row.join(', ') %] [% END %] =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[7��- �- lib/Template/Plugin/Image.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Image # # DESCRIPTION # Plugin for encapsulating information about an image. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Image; use strict; use warnings; use base 'Template::Plugin'; use Template::Exception; use File::Spec; our $VERSION = '3.100'; our $AUTOLOAD; BEGIN { if (eval { require Image::Info; }) { *img_info = \&Image::Info::image_info; } elsif (eval { require Image::Size; }) { *img_info = sub { my $file = shift; my @stuff = Image::Size::imgsize($file); return { "width" => $stuff[0], "height" => $stuff[1], "error" => # imgsize returns either a three letter file type # or an error message as third value (defined($stuff[2]) && length($stuff[2]) > 3 ? $stuff[2] : undef), }; } } else { die(Template::Exception->new("image", "Couldn't load Image::Info or Image::Size: $@")); } } #------------------------------------------------------------------------ # new($context, $name, \%config) # # Create a new Image object. Takes the pathname of the file as # the argument following the context and an optional # hash reference of configuration parameters. #------------------------------------------------------------------------ sub new { my $config = ref($_[-1]) eq 'HASH' ? pop(@_) : { }; my ($class, $context, $name) = @_; my ($root, $file, $type); # name can be a positional or named argument $name = $config->{ name } unless defined $name; return $class->throw('no image file specified') unless defined $name and length $name; # name can be specified as an absolute path or relative # to a root directory if ($root = $config->{ root }) { $file = File::Spec->catfile($root, $name); } else { $file = defined $config->{file} ? $config->{file} : $name; } # Make a note of whether we are using Image::Size or # Image::Info -- at least for the test suite $type = $INC{"Image/Size.pm"} ? "Image::Size" : "Image::Info"; # set a default (empty) alt attribute for tag() $config->{ alt } = '' unless defined $config->{ alt }; # do we want to check to see if file exists? bless { %$config, name => $name, file => $file, root => $root, type => $type, }, $class; } #------------------------------------------------------------------------ # init() # # Calls image_info on $self->{ file } #------------------------------------------------------------------------ sub init { my $self = shift; return $self if $self->{ size }; my $image = img_info($self->{ file }); return $self->throw($image->{ error }) if defined $image->{ error }; @$self{ keys %$image } = values %$image; $self->{ size } = [ $image->{ width }, $image->{ height } ]; $self->{ modtime } = (stat $self->{ file })[10]; return $self; } #------------------------------------------------------------------------ # attr() # # Return the width and height as HTML/XML attributes. #------------------------------------------------------------------------ sub attr { my $self = shift; my $size = $self->size(); return "width=\"$size->[0]\" height=\"$size->[1]\""; } #------------------------------------------------------------------------ # modtime() # # Return last modification time as a time_t: # # [% date.format(image.modtime, "%Y/%m/%d") %] #------------------------------------------------------------------------ sub modtime { my $self = shift; $self->init; return $self->{ modtime }; } #------------------------------------------------------------------------ # tag(\%options) # # Return an XHTML img tag. #------------------------------------------------------------------------ sub tag { my $self = shift; my $options = ref $_[0] eq 'HASH' ? shift : { @_ }; my $tag = '<img src="' . $self->name() . '" ' . $self->attr(); # XHTML spec says that the alt attribute is mandatory, so who # are we to argue? $options->{ alt } = $self->{ alt } unless defined $options->{ alt }; if (%$options) { for my $key (sort keys %$options) { my $escaped = escape( $options->{$key} ); $tag .= qq[ $key="$escaped"]; } } $tag .= ' />'; return $tag; } sub escape { my ($text) = @_; for ($text) { s/&/&/g; s/</</g; s/>/>/g; s/"/"/g; } $text; } sub throw { my ($self, $error) = @_; die (Template::Exception->new('Image', $error)); } sub AUTOLOAD { my $self = shift; (my $a = $AUTOLOAD) =~ s/.*:://; $self->init; return $self->{ $a }; } 1; __END__ =head1 NAME Template::Plugin::Image - Plugin access to image sizes =head1 SYNOPSIS [% USE Image(filename) %] [% Image.width %] [% Image.height %] [% Image.size.join(', ') %] [% Image.attr %] [% Image.tag %] =head1 DESCRIPTION This plugin provides an interface to the L<Image::Info> or L<Image::Size> modules for determining the size of image files. You can specify the plugin name as either 'C<Image>' or 'C<image>'. The plugin object created will then have the same name. The file name of the image should be specified as a positional or named argument. [% # all these are valid, take your pick %] [% USE Image('foo.gif') %] [% USE image('bar.gif') %] [% USE Image 'ping.gif' %] [% USE image(name='baz.gif') %] [% USE Image name='pong.gif' %] A C<root> parameter can be used to specify the location of the image file: [% USE Image(root='/path/to/root', name='images/home.png') %] # image path: /path/to/root/images/home.png # img src: images/home.png In cases where the image path and image url do not match up, specify the file name directly: [% USE Image(file='/path/to/home.png', name='/images/home.png') %] The C<alt> parameter can be used to specify an alternate name for the image, for use in constructing an XHTML element (see the C<tag()> method below). [% USE Image('home.png', alt="Home") %] You can also provide an alternate name for an C<Image> plugin object. [% USE img1 = image 'foo.gif' %] [% USE img2 = image 'bar.gif' %] The C<name> method returns the image file name. [% img1.name %] # foo.gif The C<width> and C<height> methods return the width and height of the image, respectively. The C<size> method returns a reference to a 2 element list containing the width and height. [% USE image 'foo.gif' %] width: [% image.width %] height: [% image.height %] size: [% image.size.join(', ') %] The C<modtime> method returns the modification time of the file in question, suitable for use with the L<Date|Template::Plugin::Date> plugin, for example: [% USE image 'foo.gif' %] [% USE date %] [% date.format(image.modtime, "%B, %e %Y") %] The C<attr> method returns the height and width as HTML/XML attributes. [% USE image 'foo.gif' %] [% image.attr %] Typical output: width="60" height="20" The C<tag> method returns a complete XHTML tag referencing the image. [% USE image 'foo.gif' %] [% image.tag %] Typical output: <img src="foo.gif" width="60" height="20" alt="" /> You can provide any additional attributes that should be added to the XHTML tag. [% USE image 'foo.gif' %] [% image.tag(class="logo" alt="Logo") %] Typical output: <img src="foo.gif" width="60" height="20" alt="Logo" class="logo" /> Note that the C<alt> attribute is mandatory in a strict XHTML C<img> element (even if it's empty) so it is always added even if you don't explicitly provide a value for it. You can do so as an argument to the C<tag> method, as shown in the previous example, or as an argument [% USE image('foo.gif', alt='Logo') %] =head1 CATCHING ERRORS If the image file cannot be found then the above methods will throw an C<Image> error. You can enclose calls to these methods in a C<TRY...CATCH> block to catch any potential errors. [% TRY; image.width; CATCH; error; # print error END %] =head1 USING Image::Info At run time, the plugin tries to load L<Image::Info> in preference to L<Image::Size>. If L<Image::Info> is found, then some additional methods are available, in addition to C<size>, C<width>, C<height>, C<attr>, and C<tag>. These additional methods are named after the elements that L<Image::Info> retrieves from the image itself. The types of methods available depend on the type of image (see L<Image::Info> for more details). These additional methods will always include the following: =head2 file_media_type This is the MIME type that is appropriate for the given file format. The corresponding value is a string like: "C<image/png>" or "C<image/jpeg>". =head2 file_ext The is the suggested file name extension for a file of the given file format. The value is a 3 letter, lowercase string like "C<png>", "C<jpg>". =head2 color_type The value is a short string describing what kind of values the pixels encode. The value can be one of the following: Gray GrayA RGB RGBA CMYK YCbCr CIELab These names can also be prefixed by "C<Indexed->" if the image is composed of indexes into a palette. Of these, only "C<Indexed-RGB>" is likely to occur. (It is similar to the TIFF field PhotometricInterpretation, but this name was found to be too long, so we used the PNG inspired term instead.) =head2 resolution The value of this field normally gives the physical size of the image on screen or paper. When the unit specifier is missing then this field denotes the squareness of pixels in the image. The syntax of this field is: <res> <unit> <xres> "/" <yres> <unit> <xres> "/" <yres> The C<E<lt>resE<gt>>, C<E<lt>xresE<gt>> and C<E<lt>yresE<gt>> fields are numbers. The C<E<lt>unitE<gt>> is a string like C<dpi>, C<dpm> or C<dpcm> (denoting "dots per inch/cm/meter). =head2 SamplesPerPixel This says how many channels there are in the image. For some image formats this number might be higher than the number implied from the C<color_type>. =head2 BitsPerSample This says how many bits are used to encode each of samples. The value is a reference to an array containing numbers. The number of elements in the array should be the same as C<SamplesPerPixel>. =head2 Comment Textual comments found in the file. The value is a reference to an array if there are multiple comments found. =head2 Interlace If the image is interlaced, then this returns the interlace type. =head2 Compression This returns the name of the compression algorithm is used. =head2 Gamma A number indicating the gamma curve of the image (e.g. 2.2) =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Image::Info> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��V� � lib/Template/Plugin/Assert.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Assert # # DESCRIPTION # Template Toolkit plugin module which allows you to assert that # items fetches from the stash are defined. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2008-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Assert; use base 'Template::Plugin'; use strict; use warnings; use Template::Exception; our $VERSION = '3.100'; our $MONAD = 'Template::Monad::Assert'; our $EXCEPTION = 'Template::Exception'; our $AUTOLOAD; sub load { my $class = shift; my $context = shift; my $stash = $context->stash; my $vmethod = sub { $MONAD->new($stash, shift); }; # define .assert vmethods for hash and list objects $context->define_vmethod( hash => assert => $vmethod ); $context->define_vmethod( list => assert => $vmethod ); return $class; } sub new { my ($class, $context, @args) = @_; # create an assert plugin object which will handle simple variable # lookups. return bless { _CONTEXT => $context }, $class; } sub AUTOLOAD { my ($self, @args) = @_; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; # lookup the named values my $stash = $self->{ _CONTEXT }->stash; my $value = $stash->dotop($stash, $item, \@args); if (! defined $value) { die $EXCEPTION->new( assert => "undefined value for $item" ); } return $value; } package Template::Monad::Assert; our $EXCEPTION = 'Template::Exception'; our $AUTOLOAD; sub new { my ($class, $stash, $this) = @_; bless [$stash, $this], $class; } sub AUTOLOAD { my ($self, @args) = @_; my ($stash, $this) = @$self; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; my $value = $stash->dotop($stash, $item, \@args); if (! defined $value) { die $EXCEPTION->new( assert => "undefined value for $item" ); } return $value; } 1; __END__ =head1 NAME Template::Plugin::Assert - trap undefined values =head1 SYNOPSIS [% USE assert %] # throws error if any undefined values are returned [% object.assert.method %] [% hash.assert.key %] [% list.assert.item %] =head1 DESCRIPTION This plugin defines the C<assert> virtual method that can be used to automatically throw errors when undefined values are used. For example, consider this dotop: [% user.name %] If C<user.name> is an undefined value then TT will silently ignore the fact and print nothing. If you C<USE> the C<assert> plugin then you can add the C<assert> vmethod between the C<user> and C<name> elements, like so: [% user.assert.name %] Now, if C<user.name> is an undefined value, an exception will be thrown: assert error - undefined value for name =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 2008-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[)�N�+ �+ lib/Template/Plugin/Directory.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Directory # # DESCRIPTION # Plugin for encapsulating information about a file system directory. # # AUTHORS # Michael Stevens <michael@etla.org>, with some mutilations from # Andy Wardley <abw@wardley.org>. # # COPYRIGHT # Copyright (C) 2000-2022 Michael Stevens, Andy Wardley. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Directory; use strict; use warnings; use Cwd; use File::Spec; use Template::Plugin::File; use base 'Template::Plugin::File'; our $VERSION = '3.100'; #------------------------------------------------------------------------ # new(\%config) # # Constructor method. #------------------------------------------------------------------------ sub new { my $config = ref($_[-1]) eq 'HASH' ? pop(@_) : { }; my ($class, $context, $path) = @_; return $class->throw('no directory specified') unless defined $path and length $path; my $self = $class->SUPER::new($context, $path, $config); my ($dir, @files, $name, $item, $abs, $rel, $check); $self->{ files } = [ ]; $self->{ dirs } = [ ]; $self->{ list } = [ ]; $self->{ _dir } = { }; # don't read directory if 'nostat' or 'noscan' set return $self if $config->{ nostat } || $config->{ noscan }; $self->throw("$path: not a directory") unless $self->{ isdir }; $self->scan($config); return $self; } #------------------------------------------------------------------------ # scan(\%config) # # Scan directory for files and sub-directories. #------------------------------------------------------------------------ sub scan { my ($self, $config) = @_; $config ||= { }; local *DH; my ($dir, @files, $name, $abs, $rel, $item); # set 'noscan' in config if recurse isn't set, to ensure Directories # created don't try to scan deeper $config->{ noscan } = 1 unless $config->{ recurse }; $dir = $self->{ abs }; opendir(DH, $dir) or return $self->throw("$dir: $!"); @files = readdir DH; closedir(DH) or return $self->throw("$dir close: $!"); my ($path, $files, $dirs, $list) = @$self{ qw( path files dirs list ) }; @$files = @$dirs = @$list = (); foreach $name (sort @files) { next if $name =~ /^\./; $abs = File::Spec->catfile($dir, $name); $rel = File::Spec->catfile($path, $name); if (-d $abs) { $item = Template::Plugin::Directory->new(undef, $rel, $config); push(@$dirs, $item); } else { $item = Template::Plugin::File->new(undef, $rel, $config); push(@$files, $item); } push(@$list, $item); $self->{ _dir }->{ $name } = $item; } return ''; } #------------------------------------------------------------------------ # file($filename) # # Fetch a named file from this directory. #------------------------------------------------------------------------ sub file { my ($self, $name) = @_; return $self->{ _dir }->{ $name }; } #------------------------------------------------------------------------ # present($view) # # Present self to a Template::View #------------------------------------------------------------------------ sub present { my ($self, $view) = @_; $view->view_directory($self); } #------------------------------------------------------------------------ # content($view) # # Present directory content to a Template::View. #------------------------------------------------------------------------ sub content { my ($self, $view) = @_; return $self->{ list } unless $view; my $output = ''; foreach my $file (@{ $self->{ list } }) { $output .= $file->present($view); } return $output; } #------------------------------------------------------------------------ # throw($msg) # # Throw a 'Directory' exception. #------------------------------------------------------------------------ sub throw { my ($self, $error) = @_; die (Template::Exception->new('Directory', $error)); } 1; __END__ =head1 NAME Template::Plugin::Directory - Plugin for generating directory listings =head1 SYNOPSIS [% USE dir = Directory(dirpath) %] # files returns list of regular files [% FOREACH file = dir.files %] [% file.name %] [% file.path %] ... [% END %] # dirs returns list of sub-directories [% FOREACH subdir = dir.dirs %] [% subdir.name %] [% subdir.path %] ... [% END %] # list returns both interleaved in order [% FOREACH item = dir.list %] [% IF item.isdir %] Directory: [% item.name %] [% ELSE %] File: [% item.name %] [% END %] [% END %] # define a VIEW to display dirs/files [% VIEW myview %] [% BLOCK file %] File: [% item.name %] [% END %] [% BLOCK directory %] Directory: [% item.name %] [% item.content(myview) | indent -%] [% END %] [% END %] # display directory content using view [% myview.print(dir) %] =head1 DESCRIPTION This Template Toolkit plugin provides a simple interface to directory listings. It is derived from the L<Template::Plugin::File> module and uses L<Template::Plugin::File> object instances to represent files within a directory. Sub-directories within a directory are represented by further C<Template::Plugin::Directory> instances. The constructor expects a directory name as an argument. [% USE dir = Directory('/tmp') %] It then provides access to the files and sub-directories contained within the directory. # regular files (not directories) [% FOREACH file IN dir.files %] [% file.name %] [% END %] # directories only [% FOREACH file IN dir.dirs %] [% file.name %] [% END %] # files and/or directories [% FOREACH file IN dir.list %] [% file.name %] ([% file.isdir ? 'directory' : 'file' %]) [% END %] The plugin constructor will throw a C<Directory> error if the specified path does not exist, is not a directory or fails to C<stat()> (see L<Template::Plugin::File>). Otherwise, it will scan the directory and create lists named 'C<files>' containing files, 'C<dirs>' containing directories and 'C<list>' containing both files and directories combined. The C<nostat> option can be set to disable all file/directory checks and directory scanning. Each file in the directory will be represented by a L<Template::Plugin::File> object instance, and each directory by another C<Template::Plugin::Directory>. If the C<recurse> flag is set, then those directories will contain further nested entries, and so on. With the C<recurse> flag unset, as it is by default, then each is just a place marker for the directory and does not contain any further content unless its C<scan()> method is explicitly called. The C<isdir> flag can be tested against files and/or directories, returning true if the item is a directory or false if it is a regular file. [% FOREACH file = dir.list %] [% IF file.isdir %] * Directory: [% file.name %] [% ELSE %] * File: [% file.name %] [% END %] [% END %] This example shows how you might walk down a directory tree, displaying content as you go. With the recurse flag disabled, as is the default, we need to explicitly call the C<scan()> method on each directory, to force it to lookup files and further sub-directories contained within. [% USE dir = Directory(dirpath) %] * [% dir.path %] [% INCLUDE showdir %] [% BLOCK showdir -%] [% FOREACH file = dir.list -%] [% IF file.isdir -%] * [% file.name %] [% file.scan -%] [% INCLUDE showdir dir=file FILTER indent(4) -%] [% ELSE -%] - [% f.name %] [% END -%] [% END -%] [% END %] This example is adapted (with some re-formatting for clarity) from a test in F<t/directry.t> which produces the following output: * test/dir - file1 - file2 * sub_one - bar - foo * sub_two - waz.html - wiz.html - xyzfile The C<recurse> flag can be set (disabled by default) to cause the constructor to automatically recurse down into all sub-directories, creating a new C<Template::Plugin::Directory> object for each one and filling it with any further content. In this case there is no need to explicitly call the C<scan()> method. [% USE dir = Directory(dirpath, recurse=1) %] ... [% IF file.isdir -%] * [% file.name %] [% INCLUDE showdir dir=file FILTER indent(4) -%] [% ELSE -%] ... The directory plugin also provides support for views. A view can be defined as a C<VIEW ... END> block and should contain C<BLOCK> definitions for files ('C<file>') and directories ('C<directory>'). [% VIEW myview %] [% BLOCK file %] - [% item.name %] [% END %] [% BLOCK directory %] * [% item.name %] [% item.content(myview) FILTER indent %] [% END %] [% END %] The view C<print()> method can then be called, passing the C<Directory> object as an argument. [% USE dir = Directory(dirpath, recurse=1) %] [% myview.print(dir) %] When a directory is presented to a view, either as C<[% myview.print(dir) %]> or C<[% dir.present(view) %]>, then the C<directory> C<BLOCK> within the C<myview> C<VIEW> is processed. The C<item> variable will be set to alias the C<Directory> object. [% BLOCK directory %] * [% item.name %] [% item.content(myview) FILTER indent %] [% END %] In this example, the directory name is first printed and the content(view) method is then called to present each item within the directory to the view. Further directories will be mapped to the C<directory> block, and files will be mapped to the C<file> block. With the recurse option disabled, as it is by default, the C<directory> block should explicitly call a C<scan()> on each directory. [% VIEW myview %] [% BLOCK file %] - [% item.name %] [% END %] [% BLOCK directory %] * [% item.name %] [% item.scan %] [% item.content(myview) FILTER indent %] [% END %] [% END %] [% USE dir = Directory(dirpath) %] [% myview.print(dir) %] =head1 AUTHORS Michael Stevens wrote the original Directory plugin on which this is based. Andy Wardley split it into separate L<File|Template::Plugin::File> and L<Directory|Template::Plugin::Directory> plugins, added some extra code and documentation for C<VIEW> support, and made a few other minor tweaks. =head1 COPYRIGHT Copyright (C) 2000-2022 Michael Stevens, Andy Wardley. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Template::Plugin::File>, L<Template::View> PK � �[>{ �{ { lib/Template/Plugin/HTML.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::HTML # # DESCRIPTION # Template Toolkit plugin providing useful functionality for generating # HTML. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::HTML; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; sub new { my ($class, $context, @args) = @_; my $hash = ref $args[-1] eq 'HASH' ? pop @args : { }; bless { _SORTED => $hash->{ sorted } || 0, attributes => $hash->{ attributes } || $hash->{ attrs } || { }, }, $class; } sub element { my ($self, $name, $attr) = @_; ($name, $attr) = %$name if ref $name eq 'HASH'; return '' unless defined $name and length $name; $attr = $self->attributes($attr); $attr = " $attr" if $attr; return "<$name$attr>"; } sub closed_element { my ($self, $name, $attr) = @_; ($name, $attr) = %$name if ref $name eq 'HASH'; return '' unless defined $name and length $name; $attr = $self->attributes( $attr ); $attr = " $attr" if $attr; return "<$name$attr />"; } sub attributes { my ($self, $hash) = @_; $hash ||= $self->{ attributes }; return '' unless ref $hash eq 'HASH'; my @keys = keys %$hash; @keys = sort @keys if $self->{ _SORTED }; join(' ', map { "$_=\"" . $self->escape( $hash->{ $_ } ) . '"'; } @keys); } sub add_attributes { my ($self, $attr) = @_; return unless ref $attr eq 'HASH'; my $cur = $self->{ attributes }; for (keys %{$attr}) { $cur->{$_} = exists $cur->{$_} ? $cur->{$_} . " $attr->{$_}" : $attr->{$_}; } return; } *add_attribute = \&add_attributes; *add = \&add_attributes; sub replace_attributes { my ($self, $attr) = @_; return unless ref $attr eq 'HASH'; my $cur = $self->{ attributes }; for (keys %{$attr}) { $cur->{$_} = $attr->{$_}; } return; } *replace_attribute = \&replace_attributes; *replace = \&replace_attributes; sub clear_attributes { my $self = shift; $self->{ attributes } = { }; return; } sub escape { my ($self, $text) = @_; for ($text) { s/&/&/g; s/</</g; s/>/>/g; s/"/"/g; } $text; } sub url { my ($self, $text) = @_; return undef unless defined $text; $text =~ s/([^a-zA-Z0-9_.-])/uc sprintf("%%%02x",ord($1))/eg; return $text; } 1; __END__ =head1 NAME Template::Plugin::HTML - Plugin to create HTML elements =head1 SYNOPSIS [% USE HTML %] [% HTML.escape("if (a < b && c > d) ..." %] [% HTML.element(table => { border => 1, cellpadding => 2 }) %] [% HTML.attributes(border => 1, cellpadding => 2) %] =head1 DESCRIPTION The C<HTML> plugin is a very basic plugin, implementing a few useful methods for generating HTML. =head1 METHODS =head2 escape(text) Returns the source text with any HTML reserved characters such as C<E<lt>>, C<E<gt>>, etc., correctly escaped to their entity equivalents. =head2 attributes(hash) Returns the elements of the hash array passed by reference correctly formatted (e.g. values quoted and correctly escaped) as attributes for an HTML element. =head2 add_attribute(attributes) This provides a way to incrementally add attributes to the object. The values passed in are stored in the object. Calling L<element> with just a tag or L<attributes> without an parameters will used the saved attributes. USE tag = HTML; tag.add_attributes( { class => 'navbar' } ); tag.add_attributes( { id => 'foo' } ); tag.add_attributes( { class => 'active' } ); tag.element( 'li' ); # <li class="navbar active" id="foo"> This method has two aliases: add_attribute() and add(). =head2 replace_attribute(attributes) This will replace an attribute value instead of add to existing. USE tag = HTML; tag.add_attributes( { class => 'navbar' } ); tag.add_attributes( { id => 'foo' } ); tag.replace_attributes( { class => 'active' } ); tag.element( 'li' ); # <li class="active" id="foo"> This method has two aliases: replace_attribute() and replace(). =head2 clear_attributes Clears any saved attributes =head2 element(type, attributes) Generates an HTML element of the specified type and with the attributes provided as an optional hash array reference as the second argument or as named arguments. [% HTML.element(table => { border => 1, cellpadding => 2 }) %] [% HTML.element('table', border=1, cellpadding=2) %] [% HTML.element(table => attribs) %] =head1 DEBUGGING The HTML plugin accepts a C<sorted> option as a constructor argument which, when set to any true value, causes the attributes generated by the C<attributes()> method (either directly or via C<element()>) to be returned in sorted order. Order of attributes isn't important in HTML, but this is provided mainly for the purposes of debugging where it is useful to have attributes generated in a deterministic order rather than whatever order the hash happened to feel like returning the keys in. [% USE HTML(sorted=1) %] [% HTML.element( foo => { charlie => 1, bravo => 2, alpha => 3 } ) %] generates: <foo alpha="3" bravo="2" charlie="1"> =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[)Kg �, �, lib/Template/Plugin/Date.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Date # # DESCRIPTION # # Plugin to generate formatted date strings. # # AUTHORS # Thierry-Michel Barral <kktos@electron-libre.com> # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2000-2022 Thierry-Michel Barral, Andy Wardley. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Date; use strict; use warnings; use base 'Template::Plugin'; use POSIX (); use Config (); use constant HAS_SETLOCALE => $Config::Config{d_setlocale}; our $VERSION = '3.100'; our $FORMAT = '%H:%M:%S %d-%b-%Y'; # default strftime() format our @LOCALE_SUFFIX = qw( .ISO8859-1 .ISO_8859-15 .US-ASCII .UTF-8 ); #------------------------------------------------------------------------ # new(\%options) #------------------------------------------------------------------------ sub new { my ($class, $context, $params) = @_; bless { $params ? %$params : () }, $class; } #------------------------------------------------------------------------ # now() # # Call time() to return the current system time in seconds since the epoch. #------------------------------------------------------------------------ sub now { return time(); } sub _strftime { my ( @args ) = @_; my $str = POSIX::strftime( @args ); # POSIX.pm now utf8-flags the output of strftime since perl 5.22 if ( $] < 5.022 ) { require Encode; Encode::_utf8_on( $str ); } return $str; } #------------------------------------------------------------------------ # format() # format($time) # format($time, $format) # format($time, $format, $locale) # format($time, $format, $locale, $gmt_flag) # format(\%named_params); # # Returns a formatted time/date string for the specified time, $time, # (or the current system time if unspecified) using the $format, $locale, # and $gmt values specified as arguments or internal values set defined # at construction time). Specifying a Perl-true value for $gmt will # override the local time zone and force the output to be for GMT. # Any or all of the arguments may be specified as named parameters which # get passed as a hash array reference as the final argument. # ------------------------------------------------------------------------ sub format { my $self = shift; my $params = ref($_[$#_]) eq 'HASH' ? pop(@_) : { }; my $time = shift(@_); $time = $params->{ time } || $self->{ time } || $self->now() if !defined $time; my $format = @_ ? shift(@_) : ($params->{ format } || $self->{ format } || $FORMAT); my $locale = @_ ? shift(@_) : ($params->{ locale } || $self->{ locale }); my $gmt = @_ ? shift(@_) : ($params->{ gmt } || $self->{ gmt }); my $offset = @_ ? shift(@_) : ( $params->{ use_offset } || $self->{ use_offset }); my (@date, $datestr); if ($time =~ /^-?\d+$/) { # $time is now in seconds since epoch if ($gmt) { @date = (gmtime($time))[ 0 .. ( $offset ? 6 : 8 ) ]; } else { @date = (localtime($time))[ 0 .. ( $offset ? 6 : 8 ) ]; } } else { # if $time is numeric, then we assume it's seconds since the epoch # otherwise, we try to parse it as either a 'Y:M:D H:M:S' or a # 'H:M:S D:M:Y' string my @parts = (split(/\D/, $time)); if (@parts >= 6) { if (length($parts[0]) == 4) { # year is first; assume 'Y:M:D H:M:S' @date = @parts[reverse 0..5]; } else { # year is last; assume 'H:M:S D:M:Y' @date = @parts[2,1,0,3..5]; } } if (!@date) { return ( undef, Template::Exception->new( 'date', "bad time/date string: " . "expects 'h:m:s d:m:y' got: '$time'" ) ); } $date[4] -= 1; # correct month number 1-12 to range 0-11 $date[5] -= 1900; # convert absolute year to years since 1900 $time = &POSIX::mktime(@date); if ($offset) { push @date, $gmt ? (gmtime($time))[6..8] : (localtime($time))[6..8]; } } if ($locale) { # format the date in a specific locale, saving and subsequently # restoring the current locale. my $old_locale = HAS_SETLOCALE ? &POSIX::setlocale(&POSIX::LC_ALL) : undef; # some systems expect locales to have a particular suffix for my $suffix ('', @LOCALE_SUFFIX) { my $try_locale = $locale.$suffix; my $setlocale = HAS_SETLOCALE ? &POSIX::setlocale(&POSIX::LC_ALL, $try_locale) : undef; if (defined $setlocale && $try_locale eq $setlocale) { $locale = $try_locale; last; } } $datestr = _strftime($format, @date); &POSIX::setlocale(&POSIX::LC_ALL, $old_locale) if HAS_SETLOCALE; } else { $datestr = _strftime($format, @date); } return $datestr; } sub calc { my $self = shift; eval { require "Date/Calc.pm" }; $self->throw("failed to load Date::Calc: $@") if $@; return Template::Plugin::Date::Calc->new('no context'); } sub manip { my $self = shift; eval { require "Date/Manip.pm" }; $self->throw("failed to load Date::Manip: $@") if $@; return Template::Plugin::Date::Manip->new('no context'); } sub throw { my $self = shift; die (Template::Exception->new('date', join(', ', @_))); } package Template::Plugin::Date::Calc; use base qw( Template::Plugin ); our $AUTOLOAD; *throw = \&Template::Plugin::Date::throw; sub AUTOLOAD { my $self = shift; my $method = $AUTOLOAD; $method =~ s/.*:://; return if $method eq 'DESTROY'; my $sub = \&{"Date::Calc::$method"}; $self->throw("no such Date::Calc method: $method") unless $sub; &$sub(@_); } package Template::Plugin::Date::Manip; use base qw( Template::Plugin ); our $AUTOLOAD; *throw = \&Template::Plugin::Date::throw; sub AUTOLOAD { my $self = shift; my $method = $AUTOLOAD; $method =~ s/.*:://; return if $method eq 'DESTROY'; my $sub = \&{"Date::Manip::$method"}; $self->throw("no such Date::Manip method: $method") unless $sub; &$sub(@_); } 1; __END__ =head1 NAME Template::Plugin::Date - Plugin to generate formatted date strings =head1 SYNOPSIS [% USE date %] # use current time and default format [% date.format %] # specify time as seconds since epoch # or as a 'h:m:s d-m-y' or 'y-m-d h:m:s' string [% date.format(960973980) %] [% date.format('4:20:36 21/12/2000') %] [% date.format('2000/12/21 4:20:36') %] # specify format [% date.format(mytime, '%H:%M:%S') %] # specify locale [% date.format(date.now, '%a %d %b %y', 'en_GB') %] # named parameters [% date.format(mytime, format = '%H:%M:%S') %] [% date.format(locale = 'en_GB') %] [% date.format(time = date.now, format = '%H:%M:%S', locale = 'en_GB' use_offset = 1) %] # specify default format to plugin [% USE date(format = '%H:%M:%S', locale = 'de_DE') %] [% date.format %] ... =head1 DESCRIPTION The C<Date> plugin provides an easy way to generate formatted time and date strings by delegating to the C<POSIX> C<strftime()> routine. The plugin can be loaded via the familiar USE directive. [% USE date %] This creates a plugin object with the default name of 'C<date>'. An alternate name can be specified as such: [% USE myname = date %] The plugin provides the C<format()> method which accepts a time value, a format string and a locale name. All of these parameters are optional with the current system time, default format ('C<%H:%M:%S %d-%b-%Y>') and current locale being used respectively, if undefined. Default values for the time, format and/or locale may be specified as named parameters in the C<USE> directive. [% USE date(format = '%a %d-%b-%Y', locale = 'fr_FR') %] When called without any parameters, the C<format()> method returns a string representing the current system time, formatted by C<strftime()> according to the default format and for the default locale (which may not be the current one, if locale is set in the C<USE> directive). [% date.format %] The plugin allows a time/date to be specified as seconds since the epoch, as is returned by C<time()>. File last modified: [% date.format(filemod_time) %] The time/date can also be specified as a string of the form C<h:m:s d/m/y> or C<y/m/d h:m:s>. Any of the characters : / - or space may be used to delimit fields. [% USE day = date(format => '%A', locale => 'en_GB') %] [% day.format('4:20:00 9-13-2000') %] Output: Tuesday A format string can also be passed to the C<format()> method, and a locale specification may follow that. [% date.format(filemod, '%d-%b-%Y') %] [% date.format(filemod, '%d-%b-%Y', 'en_GB') %] A fourth parameter allows you to force output in GMT, in the case of seconds-since-the-epoch input: [% date.format(filemod, '%d-%b-%Y', 'en_GB', 1) %] Note that in this case, if the local time is not GMT, then also specifying 'C<%Z>' (time zone) in the format parameter will lead to an extremely misleading result. To maintain backwards compatibility, using the C<%z> placeholder in the format string (to output the UTC offset) currently requires the C<use_offset> parameter to be set to a true value. This can also be passed as the fifth parameter to format (but the former will probably be clearer). Any or all of these parameters may be named. Positional parameters should always be in the order C<($time, $format, $locale)>. [% date.format(format => '%H:%M:%S') %] [% date.format(time => filemod, format => '%H:%M:%S') %] [% date.format(mytime, format => '%H:%M:%S') %] [% date.format(mytime, format => '%H:%M:%S', locale => 'fr_FR') %] [% date.format(mytime, format => '%H:%M:%S', gmt => 1) %] ...etc... The C<now()> method returns the current system time in seconds since the epoch. [% date.format(date.now, '%A') %] The C<calc()> method can be used to create an interface to the C<Date::Calc> module (if installed on your system). [% calc = date.calc %] [% calc.Monday_of_Week(22, 2001).join('/') %] The C<manip()> method can be used to create an interface to the C<Date::Manip> module (if installed on your system). [% manip = date.manip %] [% manip.UnixDate("Noon Yesterday","%Y %b %d %H:%M") %] =head1 AUTHORS Thierry-Michel Barral wrote the original plugin. Andy Wardley provided some minor fixups/enhancements, a test script and documentation. Mark D. Mills cloned C<Date::Manip> from the C<Date::Calc> sub-plugin. =head1 COPYRIGHT Copyright (C) 2000-2022 Thierry-Michel Barral, Andy Wardley. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<POSIX> PK � �[����� � lib/Template/Plugin/Iterator.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Iterator # # DESCRIPTION # # Plugin to create a Template::Iterator from a list of items and optional # configuration parameters. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Iterator; use strict; use warnings; use base 'Template::Plugin'; use Template::Iterator; our $VERSION = '3.100'; #------------------------------------------------------------------------ # new($context, \@data, \%args) #------------------------------------------------------------------------ sub new { my $class = shift; my $context = shift; Template::Iterator->new(@_); } 1; __END__ =head1 NAME Template::Plugin::Iterator - Plugin to create iterators (Template::Iterator) =head1 SYNOPSIS [% USE iterator(list, args) %] [% FOREACH item = iterator %] [% '<ul>' IF iterator.first %] <li>[% item %] [% '</ul>' IF iterator.last %] [% END %] =head1 DESCRIPTION The iterator plugin provides a way to create a L<Template::Iterator> object to iterate over a data set. An iterator is implicitly automatically by the L<FOREACH> directive. This plugin allows the iterator to be explicitly created with a given name. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Template::Iterator> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�4�ӵ � lib/Template/Plugin/Wrap.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Wrap # # DESCRIPTION # Plugin for wrapping text via the Text::Wrap module. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Wrap; use strict; use warnings; use base 'Template::Plugin'; use Text::Wrap; our $VERSION = '3.100'; sub new { my ($class, $context, $format) = @_;; $context->define_filter('wrap', [ \&wrap_filter_factory => 1 ]); return \&tt_wrap; } sub tt_wrap { my $text = shift; my $width = shift || 72; my $itab = shift; my $ntab = shift; $itab = '' unless defined $itab; $ntab = '' unless defined $ntab; $Text::Wrap::columns = $width; Text::Wrap::wrap($itab, $ntab, $text); } sub wrap_filter_factory { my ($context, @args) = @_; return sub { my $text = shift; tt_wrap($text, @args); } } 1; __END__ =head1 NAME Template::Plugin::Wrap - Plugin interface to Text::Wrap =head1 SYNOPSIS [% USE wrap %] # call wrap subroutine [% wrap(mytext, width, initial_tab, subsequent_tab) %] # or use wrap FILTER [% mytext FILTER wrap(width, initital_tab, subsequent_tab) %] =head1 DESCRIPTION This plugin provides an interface to the L<Text::Wrap> module which provides simple paragraph formatting. It defines a C<wrap> subroutine which can be called, passing the input text and further optional parameters to specify the page width (default: 72), and tab characters for the first and subsequent lines (no defaults). [% USE wrap %] [% text = BLOCK %] First, attach the transmutex multiplier to the cross-wired quantum homogeniser. [% END %] [% wrap(text, 40, '* ', ' ') %] Output: * First, attach the transmutex multiplier to the cross-wired quantum homogeniser. It also registers a C<wrap> filter which accepts the same three optional arguments but takes the input text directly via the filter input. Example 1: [% FILTER bullet = wrap(40, '* ', ' ') -%] First, attach the transmutex multiplier to the cross-wired quantum homogeniser. [%- END %] Output: * First, attach the transmutex multiplier to the cross-wired quantum homogeniser. Example 2: [% FILTER bullet -%] Then remodulate the shield to match the harmonic frequency, taking care to correct the phase difference. [% END %] Output: * Then remodulate the shield to match the harmonic frequency, taking care to correct the phase difference. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> The L<Text::Wrap> module was written by David Muir Sharnoff with help from Tim Pierce and many others. =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Text::Wrap> PK � �[��+� � lib/Template/Plugin/URL.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::URL # # DESCRIPTION # Template Toolkit Plugin for constructing URL's from a base stem # and adaptable parameters. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2000-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::URL; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; our $JOINT = '&'; #------------------------------------------------------------------------ # new($context, $baseurl, \%url_params) # # Constructor method which returns a sub-routine closure for constructing # complex URL's from a base part and hash of additional parameters. #------------------------------------------------------------------------ sub new { my ($class, $context, $base, $args) = @_; $args ||= { }; return sub { my $newbase = shift unless ref $_[0] eq 'HASH'; my $newargs = shift || { }; my $combo = { %$args, %$newargs }; my $urlargs = join( $JOINT, map { args($_, $combo->{ $_ }) } grep { defined $combo->{ $_ } && length $combo->{ $_ } } sort keys %$combo ); my $query = $newbase || $base || ''; $query .= '?' if length $query && length $urlargs; $query .= $urlargs if length $urlargs; return $query } } sub args { my ($key, $val) = @_; $key = escape($key); return map { "$key=" . escape($_); } ref $val eq 'ARRAY' ? @$val : $val; } #------------------------------------------------------------------------ # escape($url) # # URL-encode data. Borrowed with minor modifications from CGI.pm. # Kudos to Lincold Stein. #------------------------------------------------------------------------ sub escape { my $toencode = shift; return undef unless defined($toencode); utf8::encode($toencode); $toencode=~s/([^a-zA-Z0-9_.-])/uc sprintf("%%%02x",ord($1))/eg; return $toencode; } 1; __END__ =head1 NAME Template::Plugin::URL - Plugin to construct complex URLs =head1 SYNOPSIS [% USE url('/cgi-bin/foo.pl') %] [% url(debug = 1, id = 123) %] # ==> /cgi/bin/foo.pl?debug=1&id=123 [% USE mycgi = url('/cgi-bin/bar.pl', mode='browse', debug=1) %] [% mycgi %] # ==> /cgi/bin/bar.pl?mode=browse&debug=1 [% mycgi(mode='submit') %] # ==> /cgi/bin/bar.pl?mode=submit&debug=1 [% mycgi(debug='d2 p0', id='D4-2k[4]') %] # ==> /cgi-bin/bar.pl?mode=browse&debug=d2%20p0&id=D4-2k%5B4%5D =head1 DESCRIPTION The C<URL> plugin can be used to construct complex URLs from a base stem and a hash array of additional query parameters. The constructor should be passed a base URL and optionally, a hash array reference of default parameters and values. Used from with a template, it would look something like the following: [% USE url('http://www.somewhere.com/cgi-bin/foo.pl') %] [% USE url('/cgi-bin/bar.pl', mode='browse') %] [% USE url('/cgi-bin/baz.pl', mode='browse', debug=1) %] When the plugin is then called without any arguments, the default base and parameters are returned as a formatted query string. [% url %] For the above three examples, these will produce the following outputs: http://www.somewhere.com/cgi-bin/foo.pl /cgi-bin/bar.pl?mode=browse /cgi-bin/baz.pl?mode=browse&debug=1 Note that additional parameters are separated by 'C<&>' rather than simply 'C<&>'. This is the correct behaviour for HTML pages but is, unfortunately, incorrect when creating URLs that do not need to be encoded safely for HTML. This is likely to be corrected in a future version of the plugin (most probably with TT3). In the mean time, you can set C<$Template::Plugin::URL::JOINT> to C<&> to get the correct behaviour. Additional parameters may be also be specified to the URL: [% url(mode='submit', id='wiz') %] Which, for the same three examples, produces: http://www.somewhere.com/cgi-bin/foo.pl?mode=submit&id=wiz /cgi-bin/bar.pl?mode=browse&id=wiz /cgi-bin/baz.pl?mode=browse&debug=1&id=wiz A new base URL may also be specified as the first option: [% url('/cgi-bin/waz.pl', test=1) %] producing /cgi-bin/waz.pl?test=1 /cgi-bin/waz.pl?mode=browse&test=1 /cgi-bin/waz.pl?mode=browse&debug=1&test=1 The ordering of the parameters is non-deterministic due to fact that Perl's hashes themselves are unordered. This isn't a problem as the ordering of CGI parameters is insignificant (to the best of my knowledge). All values will be properly escaped thanks to some code borrowed from Lincoln Stein's C<CGI> module. e.g. [% USE url('/cgi-bin/woz.pl') %] [% url(name="Elrich von Benjy d'Weiro") %] Here the space and "C<'>" single quote characters are escaped in the output: /cgi-bin/woz.pl?name=Elrich%20von%20Benjy%20d%27Weiro An alternate name may be provided for the plugin at construction time as per regular Template Toolkit syntax. [% USE mycgi = url('cgi-bin/min.pl') %] [% mycgi(debug=1) %] =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��La a ! lib/Template/Plugin/Procedural.pmnu ��6�$ #============================================================================== # # Template::Plugin::Procedural # # DESCRIPTION # A Template Plugin to provide a Template Interface to Data::Dumper # # AUTHOR # Mark Fowler <mark@twoshortplanks.com> # # COPYRIGHT # Copyright (C) 2002 Mark Fowler. All Rights Reserved # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================== package Template::Plugin::Procedural; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $AUTOLOAD; #------------------------------------------------------------------------ # load #------------------------------------------------------------------------ sub load { my ($class, $context) = @_; # create a proxy namespace that will be used for objects my $proxy = "Template::Plugin::" . $class; # okay, in our proxy create the autoload routine that will # call the right method in the real class no strict "refs"; unless( defined( *{ $proxy . "::AUTOLOAD" } ) ) { *{ $proxy . "::AUTOLOAD" } = sub { # work out what the method is called $AUTOLOAD =~ s!^.*::!!; print STDERR "Calling '$AUTOLOAD' in '$class'\n" if $DEBUG; # look up the sub for that method (but in a OO way) my $uboat = $class->can($AUTOLOAD); # if it existed call it as a subroutine, not as a method if ($uboat) { shift @_; return $uboat->(@_); } print STDERR "Eeek, no such method '$AUTOLOAD'\n" if $DEBUG; return ""; }; } # create a simple new method that simply returns a blessed # scalar as the object. unless( defined( *{ $proxy . "::new" } ) ) { *{ $proxy . "::new" } = sub { my $this; return bless \$this, $_[0]; }; } return $proxy; } 1; __END__ =head1 NAME Template::Plugin::Procedural - Base class for procedural plugins =head1 SYNOPSIS package Template::Plugin::LWPSimple; use base qw(Template::Plugin::Procedural); use LWP::Simple; # exports 'get' 1; [% USE LWPSimple %] [% LWPSimple.get("http://www.tt2.org/") %] =head1 DESCRIPTION C<Template::Plugin::Procedural> is a base class for Template Toolkit plugins that causes defined subroutines to be called directly rather than as a method. Essentially this means that subroutines will not receive the class name or object as its first argument. This is most useful when creating plugins for modules that normally work by exporting subroutines that do not expect such additional arguments. Despite the fact that subroutines will not be called in an OO manner, inheritance still function as normal. A class that uses C<Template::Plugin::Procedural> can be subclassed and both subroutines defined in the subclass and subroutines defined in the original class will be available to the Template Toolkit and will be called without the class/object argument. =head1 AUTHOR Mark Fowler E<lt>mark@twoshortplanks.comE<gt> L<http://www.twoshortplanks.com> =head1 COPYRIGHT Copyright (C) 2002 Mark Fowler E<lt>mark@twoshortplanks.comE<gt> This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��K��F �F lib/Template/Plugin/String.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::String # # DESCRIPTION # Template Toolkit plugin to implement a basic String object. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2001-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::String; use strict; use warnings; use base 'Template::Plugin'; use Template::Exception; use overload q|""| => "text", fallback => 1; our $VERSION = '3.100'; our $ERROR = ''; *centre = \*center; *append = \*push; *prepend = \*unshift; #------------------------------------------------------------------------ sub new { my ($class, @args) = @_; my $context = ref $class ? undef : shift(@args); my $config = @args && ref $args[-1] eq 'HASH' ? pop(@args) : { }; $class = ref($class) || $class; my $text = defined $config->{ text } ? $config->{ text } : (@args ? shift(@args) : ''); # print STDERR "text: [$text]\n"; # print STDERR "class: [$class]\n"; my $self = bless { text => $text, filters => [ ], _CONTEXT => $context, }, $class; my $filter = $config->{ filter } || $config->{ filters }; # install any output filters specified as 'filter' or 'filters' option $self->output_filter($filter) if $filter; return $self; } sub text { my $self = shift; return $self->{ text } unless @{ $self->{ filters } }; my $text = $self->{ text }; my $context = $self->{ _CONTEXT }; foreach my $dispatch (@{ $self->{ filters } }) { my ($name, $args) = @$dispatch; my $code = $context->filter($name, $args) || $self->throw($context->error()); $text = &$code($text); } return $text; } sub copy { my $self = shift; $self->new($self->{ text }); } sub throw { my $self = shift; die (Template::Exception->new('String', join('', @_))); } #------------------------------------------------------------------------ # output_filter($filter) # # Install automatic output filter(s) for the string. $filter can a list: # [ 'name1', 'name2' => [ ..args.. ], name4 => { ..args.. } ] or a hash # { name1 => '', name2 => [ args ], name3 => { args } } #------------------------------------------------------------------------ sub output_filter { my ($self, $filter) = @_; my ($name, $args, $dispatch); my $filters = $self->{ filters }; my $count = 0; if (ref $filter eq 'HASH') { $filter = [ %$filter ]; } elsif (ref $filter ne 'ARRAY') { $filter = [ split(/\s*\W+\s*/, $filter) ]; } while (@$filter) { $name = shift @$filter; # args may follow as a reference (or empty string, e.g. { foo => '' } if (@$filter && (ref($filter->[0]) || ! length $filter->[0])) { $args = shift @$filter; if ($args) { $args = [ $args ] unless ref $args eq 'ARRAY'; } else { $args = [ ]; } } else { $args = [ ]; } # $self->DEBUG("adding output filter $name(@$args)\n"); push(@$filters, [ $name, $args ]); $count++; } return ''; } #------------------------------------------------------------------------ sub push { my $self = shift; $self->{ text } .= join('', @_); return $self; } sub unshift { my $self = shift; $self->{ text } = join('', @_) . $self->{ text }; return $self; } sub pop { my $self = shift; my $strip = shift || return $self; $self->{ text } =~ s/$strip$//; return $self; } sub shift { my $self = shift; my $strip = shift || return $self; $self->{ text } =~ s/^$strip//; return $self; } #------------------------------------------------------------------------ sub center { my ($self, $width) = @_; my $text = $self->{ text }; my $len = length $text; $width ||= 0; if ($len < $width) { my $lpad = int(($width - $len) / 2); my $rpad = $width - $len - $lpad; $self->{ text } = (' ' x $lpad) . $self->{ text } . (' ' x $rpad); } return $self; } sub left { my ($self, $width) = @_; my $len = length $self->{ text }; $width ||= 0; $self->{ text } .= (' ' x ($width - $len)) if $width > $len; return $self; } sub right { my ($self, $width) = @_; my $len = length $self->{ text }; $width ||= 0; $self->{ text } = (' ' x ($width - $len)) . $self->{ text } if $width > $len; return $self; } sub format { my ($self, $format) = @_; $format = '%s' unless defined $format; $self->{ text } = sprintf($format, $self->{ text }); return $self; } sub filter { my ($self, $name, @args) = @_; my $context = $self->{ _CONTEXT }; my $code = $context->filter($name, \@args) || $self->throw($context->error()); return &$code($self->{ text }); } #------------------------------------------------------------------------ sub upper { my $self = CORE::shift; $self->{ text } = uc $self->{ text }; return $self; } sub lower { my $self = CORE::shift; $self->{ text } = lc $self->{ text }; return $self; } sub capital { my $self = CORE::shift; $self->{ text } =~ s/^(.)/\U$1/; return $self; } #------------------------------------------------------------------------ sub chop { my $self = CORE::shift; chop $self->{ text }; return $self; } sub chomp { my $self = CORE::shift; chomp $self->{ text }; return $self; } sub trim { my $self = CORE::shift; for ($self->{ text }) { s/^\s+//; s/\s+$//; } return $self; } sub collapse { my $self = CORE::shift; for ($self->{ text }) { s/^\s+//; s/\s+$//; s/\s+/ /g } return $self; } #------------------------------------------------------------------------ sub length { my $self = CORE::shift; return length $self->{ text }; } sub truncate { my ($self, $length, $suffix) = @_; return $self unless defined $length; $suffix ||= ''; return $self if CORE::length $self->{ text } <= $length; $self->{ text } = CORE::substr($self->{ text }, 0, $length - CORE::length($suffix)) . $suffix; return $self; } sub substr { my ($self, $offset, $length, $replacement) = @_; $offset ||= 0; if(defined $length) { if (defined $replacement) { my $removed = CORE::substr( $self->{text}, $offset, $length ); CORE::substr( $self->{text}, $offset, $length ) = $replacement; return $removed; } else { return CORE::substr( $self->{text}, $offset, $length ); } } else { return CORE::substr( $self->{text}, $offset ); } } sub repeat { my ($self, $n) = @_; return $self unless defined $n; $self->{ text } = $self->{ text } x $n; return $self; } sub replace { my ($self, $search, $replace) = @_; return $self unless defined $search; $replace = '' unless defined $replace; $self->{ text } =~ s/$search/$replace/g; return $self; } sub remove { my ($self, $search) = @_; $search = '' unless defined $search; $self->{ text } =~ s/$search//g; return $self; } sub split { my $self = CORE::shift; my $split = CORE::shift; my $limit = CORE::shift || 0; $split = '\s+' unless defined $split; return [ split($split, $self->{ text }, $limit) ]; } sub search { my ($self, $pattern) = @_; return $self->{ text } =~ /$pattern/; } sub equals { my ($self, $comparison) = @_; return $self->{ text } eq $comparison; } 1; __END__ =head1 NAME Template::Plugin::String - Object oriented interface for string manipulation =head1 SYNOPSIS # create String objects via USE directive [% USE String %] [% USE String 'initial text' %] [% USE String text => 'initial text' %] # or from an existing String via new() [% newstring = String.new %] [% newstring = String.new('newstring text') %] [% newstring = String.new( text => 'newstring text' ) %] # or from an existing String via copy() [% newstring = String.copy %] # append text to string [% String.append('text to append') %] # format left, right or center/centre padded [% String.left(20) %] [% String.right(20) %] [% String.center(20) %] # American spelling [% String.centre(20) %] # European spelling # and various other methods... =head1 DESCRIPTION This module implements a C<String> class for doing stringy things to text in an object-oriented way. You can create a C<String> object via the C<USE> directive, adding any initial text value as an argument or as the named parameter C<text>. [% USE String %] [% USE String 'initial text' %] [% USE String text='initial text' %] The object created will be referenced as C<String> by default, but you can provide a different variable name for the object to be assigned to: [% USE greeting = String 'Hello World' %] Once you've got a C<String> object, you can use it as a prototype to create other C<String> objects with the C<new()> method. [% USE String %] [% greeting = String.new('Hello World') %] The C<new()> method also accepts an initial text string as an argument or the named parameter C<text>. [% greeting = String.new( text => 'Hello World' ) %] You can also call C<copy()> to create a new C<String> as a copy of the original. [% greet2 = greeting.copy %] The C<String> object has a C<text()> method to return the content of the string. [% greeting.text %] However, it is sufficient to simply print the string and let the overloaded stringification operator call the C<text()> method automatically for you. [% greeting %] Thus, you can treat C<String> objects pretty much like any regular piece of text, interpolating it into other strings, for example: [% msg = "It printed '$greeting' and then dumped core\n" %] You also have the benefit of numerous other methods for manipulating the string. [% msg.append("PS Don't eat the yellow snow") %] Note that all methods operate on and mutate the contents of the string itself. If you want to operate on a copy of the string then simply take a copy first: [% msg.copy.append("PS Don't eat the yellow snow") %] These methods return a reference to the C<String> object itself. This allows you to chain multiple methods together. [% msg.copy.append('foo').right(72) %] It also means that in the above examples, the C<String> is returned which causes the C<text()> method to be called, which results in the new value of the string being printed. To suppress printing of the string, you can use the C<CALL> directive. [% foo = String.new('foo') %] [% foo.append('bar') %] # prints "foobar" [% CALL foo.append('bar') %] # nothing =head1 CONSTRUCTOR METHODS These methods are used to create new C<String> objects. =head2 new() Creates a new string using an initial value passed as a positional argument or the named parameter C<text>. [% USE String %] [% msg = String.new('Hello World') %] [% msg = String.new( text => 'Hello World' ) %] =head2 copy() Creates a new C<String> object which contains a copy of the original string. [% msg2 = msg.copy %] =head1 INSPECTOR METHODS These methods are used to examine the string. =head2 text() Returns the internal text value of the string. The stringification operator is overloaded to call this method. Thus the following are equivalent: [% msg.text %] [% msg %] =head2 length() Returns the length of the string. [% USE String("foo") %] [% String.length %] # => 3 =head2 search($pattern) Searches the string for the regular expression specified in C<$pattern> returning true if found or false otherwise. [% item = String.new('foo bar baz wiz waz woz') %] [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %] =head2 split($pattern, $limit) Splits the string based on the delimiter C<$pattern> and optional C<$limit>. Delegates to Perl's internal C<split()> so the parameters are exactly the same. [% FOREACH item.split %] ... [% END %] [% FOREACH item.split('baz|waz') %] ... [% END %] =head1 MUTATOR METHODS These methods modify the internal value of the string. For example: [% USE str=String('foobar') %] [% str.append('.html') %] # str => 'foobar.html' The value of C<str> is now 'C<foobar.html>'. If you don't want to modify the string then simply take a copy first. [% str.copy.append('.html') %] These methods all return a reference to the C<String> object itself. This has two important benefits. The first is that when used as above, the C<String> object 'C<str>' returned by the C<append()> method will be stringified with a call to its C<text()> method. This will return the newly modified string content. In other words, a directive like: [% str.append('.html') %] will update the string and also print the new value. If you just want to update the string but not print the new value then use C<CALL>. [% CALL str.append('.html') %] The other benefit of these methods returning a reference to the C<String> is that you can chain as many different method calls together as you like. For example: [% String.append('.html').trim.format(href) %] Here are the methods: =head2 push($suffix, ...) / append($suffix, ...) Appends all arguments to the end of the string. The C<append()> method is provided as an alias for C<push()>. [% msg.push('foo', 'bar') %] [% msg.append('foo', 'bar') %] =head2 pop($suffix) Removes the suffix passed as an argument from the end of the String. [% USE String 'foo bar' %] [% String.pop(' bar') %] # => 'foo' =head2 unshift($prefix, ...) / prepend($prefix, ...) Prepends all arguments to the beginning of the string. The C<prepend()> method is provided as an alias for C<unshift()>. [% msg.unshift('foo ', 'bar ') %] [% msg.prepend('foo ', 'bar ') %] =head2 shift($prefix) Removes the prefix passed as an argument from the start of the String. [% USE String 'foo bar' %] [% String.shift('foo ') %] # => 'bar' =head2 left($pad) If the length of the string is less than C<$pad> then the string is left formatted and padded with spaces to C<$pad> length. [% msg.left(20) %] =head2 right($pad) As per L<left()> but right padding the C<String> to a length of C<$pad>. [% msg.right(20) %] =head2 center($pad) / centre($pad) As per L<left()> and L<right()> but formatting the C<String> to be centered within a space padded string of length C<$pad>. The C<centre()> method is provided as an alias for C<center()>. [% msg.center(20) %] # American spelling [% msg.centre(20) %] # European spelling =head2 format($format) Apply a format in the style of C<sprintf()> to the string. [% USE String("world") %] [% String.format("Hello %s\n") %] # => "Hello World\n" =head2 upper() Converts the string to upper case. [% USE String("foo") %] [% String.upper %] # => 'FOO' =head2 lower() Converts the string to lower case [% USE String("FOO") %] [% String.lower %] # => 'foo' =head2 capital() Converts the first character of the string to upper case. [% USE String("foo") %] [% String.capital %] # => 'Foo' The remainder of the string is left untouched. To force the string to be all lower case with only the first letter capitalised, you can do something like this: [% USE String("FOO") %] [% String.lower.capital %] # => 'Foo' =head2 chop() Removes the last character from the string. [% USE String("foop") %] [% String.chop %] # => 'foo' =head2 chomp() Removes the trailing newline from the string. [% USE String("foo\n") %] [% String.chomp %] # => 'foo' =head2 trim() Removes all leading and trailing whitespace from the string [% USE String(" foo \n\n ") %] [% String.trim %] # => 'foo' =head2 collapse() Removes all leading and trailing whitespace and collapses any sequences of multiple whitespace to a single space. [% USE String(" \n\r \t foo \n \n bar \n") %] [% String.collapse %] # => "foo bar" =head2 truncate($length, $suffix) Truncates the string to C<$length> characters. [% USE String('long string') %] [% String.truncate(4) %] # => 'long' If C<$suffix> is specified then it will be appended to the truncated string. In this case, the string will be further shortened by the length of the suffix to ensure that the newly constructed string complete with suffix is exactly C<$length> characters long. [% USE msg = String('Hello World') %] [% msg.truncate(8, '...') %] # => 'Hello...' =head2 replace($search, $replace) Replaces all occurrences of C<$search> in the string with C<$replace>. [% USE String('foo bar foo baz') %] [% String.replace('foo', 'wiz') %] # => 'wiz bar wiz baz' =head2 remove($search) Remove all occurrences of C<$search> in the string. [% USE String('foo bar foo baz') %] [% String.remove('foo ') %] # => 'bar baz' =head2 repeat($count) Repeats the string C<$count> times. [% USE String('foo ') %] [% String.repeat(3) %] # => 'foo foo foo ' =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[F��� � lib/Template/Plugin/Scalar.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Scalar # # DESCRIPTION # Template Toolkit plugin module which allows you to call object methods # in scalar context. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 2008-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Scalar; use base 'Template::Plugin'; use strict; use warnings; use Template::Exception; use Scalar::Util qw(); our $VERSION = '3.100'; our $MONAD = 'Template::Monad::Scalar'; our $EXCEPTION = 'Template::Exception'; our $AUTOLOAD; sub load { my $class = shift; my $context = shift; # define .scalar vmethods for hash and list objects $context->define_vmethod( hash => scalar => \&scalar_monad ); $context->define_vmethod( list => scalar => \&scalar_monad ); return $class; } sub scalar_monad { # create a .scalar monad which wraps the hash- or list-based object # and delegates any method calls back to it, calling them in scalar # context, e.g. foo.scalar.bar becomes $MONAD->new($foo)->bar and # the monad calls $foo->bar in scalar context $MONAD->new(shift); } sub new { my ($class, $context, @args) = @_; # create a scalar plugin object which will lookup a variable subroutine # and call it. e.g. scalar.foo results in a call to foo() in scalar context my $self = bless { _CONTEXT => $context, }, $class; return $self; } sub AUTOLOAD { my $self = shift; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; # lookup the named values my $stash = $self->{ _CONTEXT }->stash; my $value = $stash->{ $item }; if (! defined $value) { die $EXCEPTION->new( scalar => "undefined value for scalar call: $item" ); } elsif (ref $value eq 'CODE') { $value = $value->(@_); } return $value; } package Template::Monad::Scalar; our $EXCEPTION = 'Template::Exception'; our $AUTOLOAD; sub new { my ($class, $this) = @_; bless \$this, $class; } sub AUTOLOAD { my $self = shift; my $this = $$self; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; my $method; if (Scalar::Util::blessed($this)) { # lookup the method... $method = $this->can($item); } else { die $EXCEPTION->new( scalar => "invalid object method: $item" ); } # ...and call it in scalar context my $result = $method->($this, @_); return $result; } 1; __END__ =head1 NAME Template::Plugin::Scalar - call object methods in scalar context =head1 SYNOPSIS [% USE scalar %] # TT2 calls object methods in array context by default [% object.method %] # force it to use scalar context [% object.scalar.method %] # also works with subroutine references [% scalar.my_sub_ref %] =head1 DESCRIPTION The Template Toolkit calls user-defined subroutines and object methods using Perl's array context by default. This plugin module provides a way for you to call subroutines and methods in scalar context. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 2008-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��v$� � lib/Template/Plugin/Dumper.pmnu ��6�$ #============================================================================== # # Template::Plugin::Dumper # # DESCRIPTION # # A Template Plugin to provide a Template Interface to Data::Dumper # # AUTHOR # Simon Matthews <sam@tt2.org> # # COPYRIGHT # Copyright (C) 2000 Simon Matthews. All Rights Reserved # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================== package Template::Plugin::Dumper; use strict; use warnings; use base 'Template::Plugin'; use Data::Dumper; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our @DUMPER_ARGS = qw( Indent Pad Varname Purity Useqq Terse Freezer Toaster Deepcopy Quotekeys Bless Maxdepth Sortkeys ); our $AUTOLOAD; #============================================================================== # ----- CLASS METHODS ----- #============================================================================== #------------------------------------------------------------------------ # new($context, \@params) #------------------------------------------------------------------------ sub new { my ($class, $context, $params) = @_; bless { _CONTEXT => $context, params => $params || {}, }, $class; } sub get_dump_obj { my $self = shift; my $dumper_obj = Data::Dumper->new( \@_ ); my $params = $self->{ params }; foreach my $arg ( @DUMPER_ARGS ) { my $val = exists $params->{ lc $arg } ? $params->{ lc $arg } : $params->{ $arg }; $dumper_obj->$arg( $val ) if defined $val; } return $dumper_obj; } sub dump { scalar shift->get_dump_obj( @_ )->Dump() } sub dump_html { my $self = shift; my $content = $self->dump( @_ ); for ($content) { s/&/&/g; s/</</g; s/>/>/g; s/\n/<br>\n/g; } return $content; } 1; __END__ =head1 NAME Template::Plugin::Dumper - Plugin interface to Data::Dumper =head1 SYNOPSIS [% USE Dumper %] [% Dumper.dump(variable) %] [% Dumper.dump_html(variable) %] =head1 DESCRIPTION This is a very simple Template Toolkit Plugin Interface to the L<Data::Dumper> module. A C<Dumper> object will be instantiated via the following directive: [% USE Dumper %] As a standard plugin, you can also specify its name in lower case: [% USE dumper %] The C<Data::Dumper> C<Pad>, C<Indent> and C<Varname> options are supported as constructor arguments to affect the output generated. See L<Data::Dumper> for further details. [% USE dumper(Indent=0, Pad="<br>") %] These options can also be specified in lower case. [% USE dumper(indent=0, pad="<br>") %] =head1 METHODS There are two methods supported by the C<Dumper> object. Each will output into the template the contents of the variables passed to the object method. =head2 dump() Generates a raw text dump of the data structure(s) passed [% USE Dumper %] [% Dumper.dump(myvar) %] [% Dumper.dump(myvar, yourvar) %] =head2 dump_html() Generates a dump of the data structures, as per L<dump()>, but with the characters E<lt>, E<gt> and E<amp> converted to their equivalent HTML entities and newlines converted to E<lt>brE<gt>. [% USE Dumper %] [% Dumper.dump_html(myvar) %] =head1 AUTHOR Simon Matthews E<lt>sam@tt2.orgE<gt> =head1 COPYRIGHT Copyright (C) 2000 Simon Matthews. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin>, L<Data::Dumper> PK � �[�b�( ( lib/Template/Plugin/Format.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin::Format # # DESCRIPTION # # Simple Template Toolkit Plugin which creates formatting functions. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin::Format; use strict; use warnings; use base 'Template::Plugin'; our $VERSION = '3.100'; sub new { my ($class, $context, $format) = @_;; return defined $format ? make_formatter($format) : \&make_formatter; } sub make_formatter { my $format = shift; $format = '%s' unless defined $format; return sub { my @args = @_; push(@args, '') unless @args; return sprintf($format, @args); } } 1; __END__ =head1 NAME Template::Plugin::Format - Plugin to create formatting functions =head1 SYNOPSIS [% USE format %] [% commented = format('# %s') %] [% commented('The cat sat on the mat') %] [% USE bold = format('<b>%s</b>') %] [% bold('Hello') %] =head1 DESCRIPTION The format plugin constructs sub-routines which format text according to a C<printf()>-like format string. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Plugin> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��5X1= 1= lib/Template/VMethods.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::VMethods # # DESCRIPTION # Module defining virtual methods for the Template Toolkit # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::VMethods; use strict; use warnings; use Scalar::Util qw( blessed looks_like_number ); use Template::Filters; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $ROOT_VMETHODS = { inc => \&root_inc, dec => \&root_dec, }; our $TEXT_VMETHODS = { item => \&text_item, list => \&text_list, hash => \&text_hash, length => \&text_length, size => \&text_size, empty => \&text_empty, defined => \&text_defined, upper => \&text_upper, lower => \&text_lower, ucfirst => \&text_ucfirst, lcfirst => \&text_lcfirst, match => \&text_match, search => \&text_search, repeat => \&text_repeat, replace => \&text_replace, remove => \&text_remove, split => \&text_split, chunk => \&text_chunk, substr => \&text_substr, trim => \&text_trim, collapse => \&text_collapse, squote => \&text_squote, dquote => \&text_dquote, html => \&Template::Filters::html_filter, xml => \&Template::Filters::xml_filter, }; our $HASH_VMETHODS = { item => \&hash_item, hash => \&hash_hash, size => \&hash_size, empty => \&hash_empty, each => \&hash_each, keys => \&hash_keys, values => \&hash_values, items => \&hash_items, pairs => \&hash_pairs, list => \&hash_list, exists => \&hash_exists, defined => \&hash_defined, delete => \&hash_delete, import => \&hash_import, sort => \&hash_sort, nsort => \&hash_nsort, }; our $LIST_VMETHODS = { item => \&list_item, list => \&list_list, hash => \&list_hash, push => \&list_push, pop => \&list_pop, unshift => \&list_unshift, shift => \&list_shift, max => \&list_max, size => \&list_size, empty => \&list_empty, defined => \&list_defined, first => \&list_first, last => \&list_last, reverse => \&list_reverse, grep => \&list_grep, join => \&list_join, sort => \&list_sort, nsort => \&list_nsort, unique => \&list_unique, import => \&list_import, merge => \&list_merge, slice => \&list_slice, splice => \&list_splice, }; # Template::Stash needs the above, so defer loading this module # until they are defined. require Template::Stash; our $PRIVATE = $Template::Stash::PRIVATE; #======================================================================== # root virtual methods #======================================================================== sub root_inc { no warnings; my $item = shift; ++$item; } sub root_dec { no warnings; my $item = shift; --$item; } #======================================================================== # text virtual methods #======================================================================== sub text_item { $_[0]; } sub text_list { [ $_[0] ]; } sub text_hash { { value => $_[0] }; } sub text_length { length $_[0]; } sub text_size { return 1; } sub text_empty { return 0 == text_length($_[0]) ? 1 : 0; } sub text_defined { return 1; } sub text_upper { return uc $_[0]; } sub text_lower { return lc $_[0]; } sub text_ucfirst { return ucfirst $_[0]; } sub text_lcfirst { return lcfirst $_[0]; } sub text_trim { for ($_[0]) { s/^\s+//; s/\s+$//; } return $_[0]; } sub text_collapse { for ($_[0]) { s/^\s+//; s/\s+$//; s/\s+/ /g } return $_[0]; } sub text_match { my ($str, $search, $global) = @_; return $str unless defined $str and defined $search; my @matches = $global ? ($str =~ /$search/g) : ($str =~ /$search/); return @matches ? \@matches : ''; } sub text_search { my ($str, $pattern) = @_; return $str unless defined $str and defined $pattern; return $str =~ /$pattern/; } sub text_repeat { my ($str, $count) = @_; $str = '' unless defined $str; return '' unless $count; $count ||= 1; return $str x $count; } sub text_replace { my ($text, $pattern, $replace, $global) = @_; $text = '' unless defined $text; $pattern = '' unless defined $pattern; $replace = '' unless defined $replace; $global = 1 unless defined $global; if ($replace =~ /\$\d+/) { # replacement string may contain backrefs my $expand = sub { my ($chunk, $start, $end) = @_; $chunk =~ s{ \\(\\|\$) | \$ (\d+) }{ $1 ? $1 : ($2 > $#$start || $2 == 0 || !defined $start->[$2]) ? '' : substr($text, $start->[$2], $end->[$2] - $start->[$2]); }exg; $chunk; }; if ($global) { $text =~ s{$pattern}{ &$expand($replace, [@-], [@+]) }eg; } else { $text =~ s{$pattern}{ &$expand($replace, [@-], [@+]) }e; } } else { if ($global) { $text =~ s/$pattern/$replace/g; } else { $text =~ s/$pattern/$replace/; } } return $text; } sub text_remove { my ($str, $search) = @_; return $str unless defined $str and defined $search; $str =~ s/$search//g; return $str; } sub text_split { my ($str, $split, $limit) = @_; $str = '' unless defined $str; # For versions of Perl prior to 5.18 we have to be very careful about # spelling out each possible combination of arguments because split() # is very sensitive to them, for example C<split(' ', ...)> behaves # differently to C<$space=' '; split($space, ...)>. Test 33 of # vmethods/text.t depends on this behaviour. if ($] < 5.018) { if (defined $limit) { return [ defined $split ? split($split, $str, $limit) : split(' ', $str, $limit) ]; } else { return [ defined $split ? split($split, $str) : split(' ', $str) ]; } } # split's behavior changed in Perl 5.18.0 making this: # C<$space=' '; split($space, ...)> # behave the same as this: # C<split(' ', ...)> # qr// behaves the same, so use that for user-defined split. my $split_re; if (defined $split) { eval { $split_re = qr/$split/; }; } $split_re = ' ' unless defined $split_re; $limit ||= 0; return [split($split_re, $str, $limit)]; } sub text_chunk { my ($string, $size) = @_; my @list; $size ||= 1; if ($size < 0) { # sexeger! It's faster to reverse the string, search # it from the front and then reverse the output than to # search it from the end, believe it nor not! $string = reverse $string; $size = -$size; unshift(@list, scalar reverse $1) while ($string =~ /((.{$size})|(.+))/g); } else { push(@list, $1) while ($string =~ /((.{$size})|(.+))/g); } return \@list; } sub text_substr { my ($text, $offset, $length, $replacement) = @_; $offset ||= 0; if(defined $length) { if (defined $replacement) { substr( $text, $offset, $length, $replacement ); return $text; } else { return substr( $text, $offset, $length ); } } else { return substr( $text, $offset ); } } sub text_squote { my $text = shift; for ($text) { s/(['\\])/\\$1/g; } return $text; } sub text_dquote { my $text = shift; for ($text) { s/(["\\])/\\$1/g; s/\n/\\n/g; } return $text; } #======================================================================== # hash virtual methods #======================================================================== sub hash_item { my ($hash, $item) = @_; $item = '' unless defined $item; return if $PRIVATE && $item =~ /$PRIVATE/; $hash->{ $item }; } sub hash_hash { $_[0]; } sub hash_size { scalar keys %{$_[0]}; } sub hash_empty { return 0 == hash_size($_[0]) ? 1 : 0; } sub hash_each { # this will be changed in TT3 to do what hash_pairs() does [ %{ $_[0] } ]; } sub hash_keys { [ keys %{ $_[0] } ]; } sub hash_values { [ values %{ $_[0] } ]; } sub hash_items { [ %{ $_[0] } ]; } sub hash_pairs { [ map { { key => $_ , value => $_[0]->{ $_ } } } sort keys %{ $_[0] } ]; } sub hash_list { my ($hash, $what) = @_; $what ||= ''; return ($what eq 'keys') ? [ keys %$hash ] : ($what eq 'values') ? [ values %$hash ] : ($what eq 'each') ? [ %$hash ] : [ # for now we do what pairs does but this will be changed # in TT3 to return [ $hash ] by default map { { key => $_ , value => $hash->{ $_ } } } sort keys %$hash ]; } sub hash_exists { exists $_[0]->{ $_[1] }; } sub hash_defined { # return the item requested, or 1 if no argument # to indicate that the hash itself is defined my $hash = shift; return @_ ? defined $hash->{ $_[0] } : 1; } sub hash_delete { my $hash = shift; delete $hash->{ $_ } for @_; } sub hash_import { my ($hash, $imp) = @_; if (ref $imp eq 'HASH') { @$hash{ keys %$imp } = values %$imp; } return ''; } sub hash_sort { my ($hash) = @_; [ sort { lc $hash->{$a} cmp lc $hash->{$b} } (keys %$hash) ]; } sub hash_nsort { my ($hash) = @_; [ sort { $hash->{$a} <=> $hash->{$b} } (keys %$hash) ]; } #======================================================================== # list virtual methods #======================================================================== sub list_item { $_[0]->[ $_[1] || 0 ]; } sub list_list { $_[0]; } sub list_hash { my $list = shift; if (@_) { my $n = shift || 0; return { map { ($n++, $_) } @$list }; } no warnings; return { @$list }; } sub list_push { my $list = shift; push(@$list, @_); return ''; } sub list_pop { my $list = shift; pop(@$list); } sub list_unshift { my $list = shift; unshift(@$list, @_); return ''; } sub list_shift { my $list = shift; shift(@$list); } sub list_max { no warnings; my $list = shift; $#$list; } sub list_size { no warnings; my $list = shift; $#$list + 1; } sub list_empty { return 0 == list_size($_[0]) ? 1 : 0; } sub list_defined { # return the item requested, or 1 if no argument to # indicate that the hash itself is defined my $list = shift; return 1 unless @_; # list.defined is always true return unless looks_like_number $_[0]; # list.defined('bah') is always false return defined $list->[$_[0]]; # list.defined(n) } sub list_first { my $list = shift; return $list->[0] unless @_; return [ @$list[0..$_[0]-1] ]; } sub list_last { my $list = shift; return $list->[-1] unless @_; return [ @$list[-$_[0]..-1] ]; } sub list_reverse { my $list = shift; [ reverse @$list ]; } sub list_grep { my ($list, $pattern) = @_; $pattern ||= ''; return [ grep /$pattern/, @$list ]; } sub list_join { my ($list, $joint) = @_; join(defined $joint ? $joint : ' ', map { defined $_ ? $_ : '' } @$list); } sub _list_sort_make_key { my ($item, $fields) = @_; my @keys; if (ref($item) eq 'HASH') { @keys = map { $item->{ $_ } } @$fields; } elsif (blessed $item) { @keys = map { $item->can($_) ? $item->$_() : $item } @$fields; } else { @keys = $item; } # ugly hack to generate a single string using a delimiter that is # unlikely (but not impossible) to be found in the wild. return lc join('/*^UNLIKELY^*/', map { defined $_ ? $_ : '' } @keys); } sub list_sort { my ($list, @fields) = @_; return $list unless @$list > 1; # no need to sort 1 item lists return [ @fields # Schwartzian Transform ? map { $_->[0] } # for case insensitivity sort { $a->[1] cmp $b->[1] } map { [ $_, _list_sort_make_key($_, \@fields) ] } @$list : map { $_->[0] } sort { $a->[1] cmp $b->[1] } map { [ $_, lc $_ ] } @$list, ]; } sub list_nsort { my ($list, @fields) = @_; return $list unless @$list > 1; # no need to sort 1 item lists my $sort = sub { my $cmp; if(@fields) { # compare each field individually for my $field (@fields) { my $A = _list_sort_make_key($a, [ $field ]); my $B = _list_sort_make_key($b, [ $field ]); ($cmp = $A <=> $B) and last; } } else { my $A = _list_sort_make_key($a); my $B = _list_sort_make_key($b); $cmp = $A <=> $B; } $cmp; }; return [ sort $sort @{ $list } ]; } sub list_unique { my %u; [ grep { ++$u{$_} == 1 } @{$_[0]} ]; } sub list_import { my $list = shift; push(@$list, grep defined, map ref eq 'ARRAY' ? @$_ : undef, @_); return $list; } sub list_merge { my $list = shift; return [ @$list, grep defined, map ref eq 'ARRAY' ? @$_ : undef, @_ ]; } sub list_slice { my ($list, $from, $to) = @_; $from ||= 0; $to = $#$list unless defined $to; $from += @$list if $from < 0; $to += @$list if $to < 0; return [ @$list[$from..$to] ]; } sub list_splice { my ($list, $offset, $length, @replace) = @_; if (@replace) { # @replace can contain a list of multiple replace items, or # be a single reference to a list @replace = @{ $replace[0] } if @replace == 1 && ref $replace[0] eq 'ARRAY'; return [ splice @$list, $offset, $length, @replace ]; } elsif (defined $length) { return [ splice @$list, $offset, $length ]; } elsif (defined $offset) { return [ splice @$list, $offset ]; } else { return [ splice(@$list) ]; } } 1; __END__ =head1 NAME Template::VMethods - Virtual methods for variables =head1 DESCRIPTION The C<Template::VMethods> module implements the virtual methods that can be applied to variables. Please see L<Template::Manual::VMethods> for further information. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Stash>, L<Template::Manual::VMethods> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��ō lib/Template/Tutorial.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Tutorial # # DESCRIPTION # Section index for the Template::Tutorial documentation. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Tutorial - Template Toolkit Tutorials =head1 Template Toolkit Tutorials =head2 Template::Tutorial::Web The L<Template::Tutorial::Web> tutorial shows how you can use the Template Toolkit to generate static and dynamic web content. =head2 Template::Tutorial::Datafile The L<Template::Tutorial::Datafile> tutorial shows how you can use the Template Toolkit to generate other data formats like XML. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��[�� �� lib/Template/Provider.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Provider # # DESCRIPTION # This module implements a class which handles the loading, compiling # and caching of templates. Multiple Template::Provider objects can # be stacked and queried in turn to effect a Chain-of-Command between # them. A provider will attempt to return the requested template, # an error (STATUS_ERROR) or decline to provide the template # (STATUS_DECLINE), allowing subsequent providers to attempt to # deliver it. See 'Design Patterns' for further details. # # AUTHORS # Andy Wardley <abw@wardley.org> # # Refactored by Bill Moseley for v2.19 to add negative caching (i.e. # tracking templates that are NOTFOUND so that we can decline quickly) # and to provide better support for subclassing the provider. # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # WARNING: # This code is ugly and contorted and is being totally re-written for TT3. # In particular, we'll be throwing errors rather than messing around # returning (value, status) pairs. With the benefit of hindsight, that # was a really bad design decision on my part. I deserve to be knocked # to the ground and kicked around a bit by hoards of angry TT developers # for that one. Bill's refactoring has made the module easier to subclass, # (so you can ease off the kicking now), but it really needs to be totally # redesigned and rebuilt from the ground up along with the bits of TT that # use it. -- abw 2007/04/27 #============================================================================ package Template::Provider; use strict; use warnings; use base 'Template::Base'; use Template::Config; use Template::Constants; use Template::Document; use File::Basename; use File::Spec; use constant PREV => 0; use constant NAME => 1; # template name -- indexed by this name in LOOKUP use constant DATA => 2; # Compiled template use constant LOAD => 3; # mtime of template use constant NEXT => 4; # link to next item in cache linked list use constant STAT => 5; # Time last stat()ed use constant MSWin32 => $^O eq 'MSWin32'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $ERROR = ''; # name of document class our $DOCUMENT = 'Template::Document' unless defined $DOCUMENT; # maximum time between performing stat() on file to check staleness our $STAT_TTL = 1 unless defined $STAT_TTL; # maximum number of directories in an INCLUDE_PATH, to prevent runaways our $MAX_DIRS = 64 unless defined $MAX_DIRS; # UNICODE is supported in versions of Perl from 5.007 onwards our $UNICODE = $] > 5.007 ? 1 : 0; my $boms = [ 'UTF-8' => "\x{ef}\x{bb}\x{bf}", 'UTF-32BE' => "\x{0}\x{0}\x{fe}\x{ff}", 'UTF-32LE' => "\x{ff}\x{fe}\x{0}\x{0}", 'UTF-16BE' => "\x{fe}\x{ff}", 'UTF-16LE' => "\x{ff}\x{fe}", ]; # regex to match relative paths our $RELATIVE_PATH = qr[(?:^|/)\.+/]; #======================================================================== # -- PUBLIC METHODS -- #======================================================================== #------------------------------------------------------------------------ # fetch($name) # # Returns a compiled template for the name specified by parameter. # The template is returned from the internal cache if it exists, or # loaded and then subsequently cached. The ABSOLUTE and RELATIVE # configuration flags determine if absolute (e.g. '/something...') # and/or relative (e.g. './something') paths should be honoured. The # INCLUDE_PATH is otherwise used to find the named file. $name may # also be a reference to a text string containing the template text, # or a file handle from which the content is read. The compiled # template is not cached in these latter cases given that there is no # filename to cache under. A subsequent call to store($name, # $compiled) can be made to cache the compiled template for future # fetch() calls, if necessary. # # Returns a compiled template or (undef, STATUS_DECLINED) if the # template could not be found. On error (e.g. the file was found # but couldn't be read or parsed), the pair ($error, STATUS_ERROR) # is returned. The TOLERANT configuration option can be set to # downgrade any errors to STATUS_DECLINE. #------------------------------------------------------------------------ sub fetch { my ($self, $name) = @_; my ($data, $error); if (ref $name) { # $name can be a reference to a scalar, GLOB or file handle ($data, $error) = $self->_load($name); ($data, $error) = $self->_compile($data) unless $error; $data = $data->{ data } unless $error; } elsif (File::Spec->file_name_is_absolute($name)) { # absolute paths (starting '/') allowed if ABSOLUTE set ($data, $error) = $self->{ ABSOLUTE } ? $self->_fetch($name) : $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ("$name: absolute paths are not allowed (set ABSOLUTE option)", Template::Constants::STATUS_ERROR); } elsif ($name =~ m/$RELATIVE_PATH/o) { # anything starting "./" is relative to cwd, allowed if RELATIVE set ($data, $error) = $self->{ RELATIVE } ? $self->_fetch($name) : $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ("$name: relative paths are not allowed (set RELATIVE option)", Template::Constants::STATUS_ERROR); } else { # otherwise, it's a file name relative to INCLUDE_PATH ($data, $error) = $self->{ INCLUDE_PATH } ? $self->_fetch_path($name) : (undef, Template::Constants::STATUS_DECLINED); } return ($data, $error); } #------------------------------------------------------------------------ # store($name, $data) # # Store a compiled template ($data) in the cached as $name. # Returns compiled template #------------------------------------------------------------------------ sub store { my ($self, $name, $data, $mtime) = @_; $self->_store($name, { data => $data, load => 0, mtime => $mtime }); } #------------------------------------------------------------------------ # load($name) # # Load a template without parsing/compiling it, suitable for use with # the INSERT directive. There's some duplication with fetch() and at # some point this could be reworked to integrate them a little closer. #------------------------------------------------------------------------ sub load { my ($self, $name) = @_; my ($data, $error); my $path = $name; if (File::Spec->file_name_is_absolute($name)) { # absolute paths (starting '/') allowed if ABSOLUTE set $error = "$name: absolute paths are not allowed (set ABSOLUTE option)" unless $self->{ ABSOLUTE }; } elsif ($name =~ m[$RELATIVE_PATH]o) { # anything starting "./" is relative to cwd, allowed if RELATIVE set $error = "$name: relative paths are not allowed (set RELATIVE option)" unless $self->{ RELATIVE }; } else { INCPATH: { # otherwise, it's a file name relative to INCLUDE_PATH my $paths = $self->paths() || return ($self->error(), Template::Constants::STATUS_ERROR); foreach my $dir (@$paths) { $path = File::Spec->catfile($dir, $name); last INCPATH if defined $self->_template_modified($path); } undef $path; # not found } } # Now fetch the content ($data, $error) = $self->_template_content($path) if defined $path && !$error; if ($error) { return $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ($error, Template::Constants::STATUS_ERROR); } elsif (! defined $path) { return (undef, Template::Constants::STATUS_DECLINED); } else { return ($data, Template::Constants::STATUS_OK); } } #------------------------------------------------------------------------ # include_path(\@newpath) # # Accessor method for the INCLUDE_PATH setting. If called with an # argument, this method will replace the existing INCLUDE_PATH with # the new value. #------------------------------------------------------------------------ sub include_path { my ($self, $path) = @_; $self->{ INCLUDE_PATH } = $path if $path; return $self->{ INCLUDE_PATH }; } #------------------------------------------------------------------------ # paths() # # Evaluates the INCLUDE_PATH list, ignoring any blank entries, and # calling and subroutine or object references to return dynamically # generated path lists. Returns a reference to a new list of paths # or undef on error. #------------------------------------------------------------------------ sub paths { my $self = shift; my @ipaths = @{ $self->{ INCLUDE_PATH } }; my (@opaths, $dpaths, $dir); my $count = $MAX_DIRS; while (@ipaths && --$count) { $dir = shift @ipaths || next; # $dir can be a sub or object ref which returns a reference # to a dynamically generated list of search paths. if (ref $dir eq 'CODE') { eval { $dpaths = &$dir() }; if ($@) { chomp $@; return $self->error($@); } unshift(@ipaths, @$dpaths); next; } elsif (ref($dir) && UNIVERSAL::can($dir, 'paths')) { $dpaths = $dir->paths() || return $self->error($dir->error()); unshift(@ipaths, @$dpaths); next; } else { push(@opaths, $dir); } } return $self->error("INCLUDE_PATH exceeds $MAX_DIRS directories") if @ipaths; return \@opaths; } #------------------------------------------------------------------------ # DESTROY # # The provider cache is implemented as a doubly linked list which Perl # cannot free by itself due to the circular references between NEXT <=> # PREV items. This cleanup method walks the list deleting all the NEXT/PREV # references, allowing the proper cleanup to occur and memory to be # repooled. #------------------------------------------------------------------------ sub DESTROY { my $self = shift; my ($slot, $next); $slot = $self->{ HEAD }; while ($slot) { $next = $slot->[ NEXT ]; undef $slot->[ PREV ]; undef $slot->[ NEXT ]; $slot = $next; } undef $self->{ HEAD }; undef $self->{ TAIL }; } #======================================================================== # -- PRIVATE METHODS -- #======================================================================== #------------------------------------------------------------------------ # _init() # # Initialise the cache. #------------------------------------------------------------------------ sub _init { my ($self, $params) = @_; my $size = $params->{ CACHE_SIZE }; my $path = $params->{ INCLUDE_PATH } || '.'; my $cdir = $params->{ COMPILE_DIR } || ''; my $dlim = $params->{ DELIMITER }; my $debug; # tweak delim to ignore C:/ unless (defined $dlim) { $dlim = MSWin32 ? qr/:(?!\\|\/)/ : qr/:/; } # coerce INCLUDE_PATH to an array ref, if not already so $path = [ split(/$dlim/, $path) ] unless ref $path eq 'ARRAY'; # don't allow a CACHE_SIZE 1 because it breaks things and the # additional checking isn't worth it $size = 2 if defined $size && ($size == 1 || $size < 0); if (defined ($debug = $params->{ DEBUG })) { $self->{ DEBUG } = $debug & ( Template::Constants::DEBUG_PROVIDER | Template::Constants::DEBUG_FLAGS ); } else { $self->{ DEBUG } = $DEBUG; } if ($self->{ DEBUG }) { local $" = ', '; $self->debug( "creating cache of ", defined $size ? $size : 'unlimited', " slots for [ @$path ]" ); } # create COMPILE_DIR and sub-directories representing each INCLUDE_PATH # element in which to store compiled files if ($cdir) { require File::Path; foreach my $dir (@$path) { next if ref $dir; my $wdir = $dir; $wdir =~ tr[:][]d if MSWin32; { no warnings 'syntax'; $wdir = each %{ { $wdir => undef } } if ${^TAINT}; #untaint } $wdir = File::Spec->catfile($cdir, $wdir); File::Path::mkpath($wdir) unless -d $wdir; } } $self->{ LOOKUP } = { }; $self->{ NOTFOUND } = { }; # Tracks templates *not* found. $self->{ SLOTS } = 0; $self->{ SIZE } = $size; $self->{ INCLUDE_PATH } = $path; $self->{ DELIMITER } = $dlim; $self->{ COMPILE_DIR } = $cdir; $self->{ COMPILE_EXT } = $params->{ COMPILE_EXT } || ''; $self->{ ABSOLUTE } = $params->{ ABSOLUTE } || 0; $self->{ RELATIVE } = $params->{ RELATIVE } || 0; $self->{ TOLERANT } = $params->{ TOLERANT } || 0; $self->{ DOCUMENT } = $params->{ DOCUMENT } || $DOCUMENT; $self->{ PARSER } = $params->{ PARSER }; $self->{ DEFAULT } = $params->{ DEFAULT }; $self->{ ENCODING } = $params->{ ENCODING }; # $self->{ PREFIX } = $params->{ PREFIX }; $self->{ STAT_TTL } = $params->{ STAT_TTL } || $STAT_TTL; $self->{ PARAMS } = $params; # look for user-provided UNICODE parameter or use default from package var $self->{ UNICODE } = defined $params->{ UNICODE } ? $params->{ UNICODE } : $UNICODE; return $self; } #------------------------------------------------------------------------ # _fetch($name, $t_name) # # Fetch a file from cache or disk by specification of an absolute or # relative filename. No search of the INCLUDE_PATH is made. If the # file is found and loaded, it is compiled and cached. # Call with: # $name = path to search (possible prefixed by INCLUDE_PATH) # $t_name = template name #------------------------------------------------------------------------ sub _fetch { my ($self, $name, $t_name) = @_; my $stat_ttl = $self->{ STAT_TTL }; $self->debug("_fetch($name)") if $self->{ DEBUG }; # First see if the named template is in the memory cache if ((my $slot = $self->{ LOOKUP }->{ $name })) { # Test if cache is fresh, and reload/compile if not. my ($data, $error) = $self->_refresh($slot); return $error ? ( $data, $error ) # $data may contain error text : $slot->[ DATA ]; # returned document object } # Otherwise, see if we already know the template is not found if (my $last_stat_time = $self->{ NOTFOUND }->{ $name }) { my $expires_in = $last_stat_time + $stat_ttl - time; if ($expires_in > 0) { $self->debug(" file [$name] in negative cache. Expires in $expires_in seconds") if $self->{ DEBUG }; return (undef, Template::Constants::STATUS_DECLINED); } else { delete $self->{ NOTFOUND }->{ $name }; } } my($template,$error); my $uncompiled_template_mtime = $self->_template_modified( $name ); # does template exist? # some templates like Provider::FromDATA does not provide mtime information $uncompiled_template_mtime = 0 unless defined $uncompiled_template_mtime; # Is there an up-to-date compiled version on disk? if (my $template_mtime = $self->_compiled_is_current($name, $uncompiled_template_mtime)) { # require() the compiled template. my $compiled_template = $self->_load_compiled( $self->_compiled_filename($name) ); # Store and return the compiled template return $self->store( $name, $compiled_template, $template_mtime ) if $compiled_template; # Problem loading compiled template: # warn and continue to fetch source template warn($self->error(), "\n"); } # load template from source ($template, $error) = $self->_load($name, $t_name); if ($error) { # Template could not be fetched. Add to the negative/notfound cache. $self->{ NOTFOUND }->{ $name } = time; return ( $template, $error ); } # compile template source ($template, $error) = $self->_compile($template, $self->_compiled_filename($name) ); if ($error) { # return any compile time error return ($template, $error); } else { # Store compiled template and return it return $self->store($name, $template->{data}) ; } } #------------------------------------------------------------------------ # _fetch_path($name) # # Fetch a file from cache or disk by specification of an absolute cache # name (e.g. 'header') or filename relative to one of the INCLUDE_PATH # directories. If the file isn't already cached and can be found and # loaded, it is compiled and cached under the full filename. #------------------------------------------------------------------------ sub _fetch_path { my ($self, $name) = @_; $self->debug("_fetch_path($name)") if $self->{ DEBUG }; # the template may have been stored using a non-filename name # so look for the plain name in the cache first if ((my $slot = $self->{ LOOKUP }->{ $name })) { # cached entry exists, so refresh slot and extract data my ($data, $error) = $self->_refresh($slot); return $error ? ($data, $error) : ($slot->[ DATA ], $error ); } my $paths = $self->paths || return ( $self->error, Template::Constants::STATUS_ERROR ); # search the INCLUDE_PATH for the file, in cache or on disk foreach my $dir (@$paths) { my $path = File::Spec->catfile($dir, $name); $self->debug("searching path: $path\n") if $self->{ DEBUG }; my ($data, $error) = $self->_fetch( $path, $name ); # Return if no error or if a serious error. return ( $data, $error ) if !$error || $error == Template::Constants::STATUS_ERROR; } # not found in INCLUDE_PATH, now try DEFAULT return $self->_fetch_path( $self->{DEFAULT} ) if defined $self->{DEFAULT} && $name ne $self->{DEFAULT}; # We could not handle this template name return (undef, Template::Constants::STATUS_DECLINED); } sub _compiled_filename { my ($self, $file) = @_; return $self->{ COMPILEDPATH }{$file} if $self->{ COMPILEDPATH }{$file}; my ($compext, $compdir) = @$self{ qw( COMPILE_EXT COMPILE_DIR ) }; my ($path, $compiled); return undef unless $compext || $compdir; $path = $file; $path or die "invalid filename: $path"; $path =~ tr[:][]d if MSWin32; $compiled = "$path$compext"; $self->{ COMPILEDPATH }{$file} = $compiled = File::Spec->catfile($compdir, $compiled) if length $compdir; return $compiled; } sub _load_compiled { my ($self, $file) = @_; # Implicitly Relative paths are not supported # by "require" and invoke @INC traversal, where relative # paths only traditionally worked prior to Perl 5.26 # due to the presence of '.' in @INC # # Given load_compiled never wants to traverse @INC, forcing # an absolute path for the loaded file and the INC key is # sensible. # # NB: %INC Keys are always identical to their respective # "require" invocations regardless of OS, and the only time # one needs to care about slash direction is when dealing # with Module::Name -> Module/Name.pm translation. my $fpath = File::Spec->rel2abs( $file ); return $self->error("compiled template missing path") unless defined $fpath; ($fpath) = $fpath =~ /^(.*)$/s; my $compiled; # load compiled template via require(); we zap any # %INC entry to ensure it is reloaded (we don't # want 1 returned by require() to say it's in memory) delete $INC{ $fpath }; eval { $compiled = require $fpath; }; return $@ ? $self->error("compiled template $compiled: $@") : $compiled; } #------------------------------------------------------------------------ # _load($name, $alias) # # Load template text from a string ($name = scalar ref), GLOB or file # handle ($name = ref), or from an absolute filename ($name = scalar). # Returns a hash array containing the following items: # name filename or $alias, if provided, or 'input text', etc. # text template text # time modification time of file, or current time for handles/strings # load time file was loaded (now!) # # On error, returns ($error, STATUS_ERROR), or (undef, STATUS_DECLINED) # if TOLERANT is set. #------------------------------------------------------------------------ sub _load { my ($self, $name, $alias) = @_; my ($data, $error); my $tolerant = $self->{ TOLERANT }; my $now = time; $alias = $name unless defined $alias or ref $name; $self->debug("_load($name, ", defined $alias ? $alias : '<no alias>', ')') if $self->{ DEBUG }; # SCALAR ref is the template text if (ref $name eq 'SCALAR') { # $name can be a SCALAR reference to the input text... return { name => defined $alias ? $alias : 'input text', path => defined $alias ? $alias : 'input text', text => $$name, time => $now, load => 0, }; } # Otherwise, assume GLOB as a file handle if (ref $name) { local $/; my $text = <$name>; $text = $self->_decode_unicode($text) if $self->{ UNICODE }; return { name => defined $alias ? $alias : 'input file handle', path => defined $alias ? $alias : 'input file handle', text => $text, time => $now, load => 0, }; } # Otherwise, it's the name of the template if ( defined $self->_template_modified( $name ) ) { # does template exist? my ($text, $error, $mtime ) = $self->_template_content( $name ); unless ( $error ) { $text = $self->_decode_unicode($text) if $self->{ UNICODE }; return { name => $alias, path => $name, text => $text, time => $mtime, load => $now, }; } return ( $error, Template::Constants::STATUS_ERROR ) unless $tolerant; } # Unable to process template, pass onto the next Provider. return (undef, Template::Constants::STATUS_DECLINED); } #------------------------------------------------------------------------ # _refresh(\@slot) # # Private method called to mark a cache slot as most recently used. # A reference to the slot array should be passed by parameter. The # slot is relocated to the head of the linked list. If the file from # which the data was loaded has been updated since it was compiled, then # it is re-loaded from disk and re-compiled. #------------------------------------------------------------------------ sub _refresh { my ($self, $slot) = @_; my $stat_ttl = $self->{ STAT_TTL }; my ($head, $file, $data, $error); $self->debug( "_refresh([ ", join(', ', map { defined $_ ? $_ : '<undef>' } @$slot), '])' ) if $self->{ DEBUG }; # if it's more than $STAT_TTL seconds since we last performed a # stat() on the file then we need to do it again and see if the file # time has changed my $now = time; my $expires_in_sec = $slot->[ STAT ] + $stat_ttl - $now; if ( $expires_in_sec <= 0 ) { # Time to check! $slot->[ STAT ] = $now; # Grab mtime of template. # Seems like this should be abstracted to compare to # just ask for a newer compiled template (if it's newer) # and let that check for a newer template source. my $template_mtime = $self->_template_modified( $slot->[ NAME ] ); if ( ! defined $template_mtime || ( $template_mtime != $slot->[ LOAD ] )) { $self->debug("refreshing cache file ", $slot->[ NAME ]) if $self->{ DEBUG }; ($data, $error) = $self->_load($slot->[ NAME ], $slot->[ DATA ]->{ name }); ($data, $error) = $self->_compile($data) unless $error; if ($error) { # if the template failed to load/compile then we wipe out the # STAT entry. This forces the provider to try and reload it # each time instead of using the previously cached version # until $STAT_TTL is next up $slot->[ STAT ] = 0; } else { $slot->[ DATA ] = $data->{ data }; $slot->[ LOAD ] = $data->{ time }; } } } elsif ( $self->{ DEBUG } ) { $self->debug( sprintf('STAT_TTL not met for file [%s]. Expires in %d seconds', $slot->[ NAME ], $expires_in_sec ) ); } # Move this slot to the head of the list unless( $self->{ HEAD } == $slot ) { # remove existing slot from usage chain... if ($slot->[ PREV ]) { $slot->[ PREV ]->[ NEXT ] = $slot->[ NEXT ]; } else { $self->{ HEAD } = $slot->[ NEXT ]; } if ($slot->[ NEXT ]) { $slot->[ NEXT ]->[ PREV ] = $slot->[ PREV ]; } else { $self->{ TAIL } = $slot->[ PREV ]; } # ..and add to start of list $head = $self->{ HEAD }; $head->[ PREV ] = $slot if $head; $slot->[ PREV ] = undef; $slot->[ NEXT ] = $head; $self->{ HEAD } = $slot; } return ($data, $error); } #------------------------------------------------------------------------ # _store($name, $data) # # Private method called to add a data item to the cache. If the cache # size limit has been reached then the oldest entry at the tail of the # list is removed and its slot relocated to the head of the list and # reused for the new data item. If the cache is under the size limit, # or if no size limit is defined, then the item is added to the head # of the list. # Returns compiled template #------------------------------------------------------------------------ sub _store { my ($self, $name, $data, $compfile) = @_; my $size = $self->{ SIZE }; my ($slot, $head); # Return if memory cache disabled. (overriding code should also check) # $$$ What's the expected behaviour of store()? Can't tell from the # docs if you can call store() when SIZE = 0. return $data->{data} if defined $size and !$size; # check the modification time -- extra stat here my $load = $data->{ mtime } || $self->_modified($name); # extract the compiled template from the data hash $data = $data->{ data }; $self->debug("_store($name, $data)") if $self->{ DEBUG }; if (defined $size && $self->{ SLOTS } >= $size) { # cache has reached size limit, so reuse oldest entry $self->debug("reusing oldest cache entry (size limit reached: $size)\nslots: $self->{ SLOTS }") if $self->{ DEBUG }; # remove entry from tail of list $slot = $self->{ TAIL }; $slot->[ PREV ]->[ NEXT ] = undef; $self->{ TAIL } = $slot->[ PREV ]; # remove name lookup for old node delete $self->{ LOOKUP }->{ $slot->[ NAME ] }; # add modified node to head of list $head = $self->{ HEAD }; $head->[ PREV ] = $slot if $head; @$slot = ( undef, $name, $data, $load, $head, time ); $self->{ HEAD } = $slot; # add name lookup for new node $self->{ LOOKUP }->{ $name } = $slot; } else { # cache is under size limit, or none is defined $self->debug("adding new cache entry") if $self->{ DEBUG }; # add new node to head of list $head = $self->{ HEAD }; $slot = [ undef, $name, $data, $load, $head, time ]; $head->[ PREV ] = $slot if $head; $self->{ HEAD } = $slot; $self->{ TAIL } = $slot unless $self->{ TAIL }; # add lookup from name to slot and increment nslots $self->{ LOOKUP }->{ $name } = $slot; $self->{ SLOTS }++; } return $data; } #------------------------------------------------------------------------ # _compile($data) # # Private method called to parse the template text and compile it into # a runtime form. Creates and delegates a Template::Parser object to # handle the compilation, or uses a reference passed in PARSER. On # success, the compiled template is stored in the 'data' item of the # $data hash and returned. On error, ($error, STATUS_ERROR) is returned, # or (undef, STATUS_DECLINED) if the TOLERANT flag is set. # The optional $compiled parameter may be passed to specify # the name of a compiled template file to which the generated Perl # code should be written. Errors are (for now...) silently # ignored, assuming that failures to open a file for writing are # intentional (e.g directory write permission). #------------------------------------------------------------------------ sub _compile { my ($self, $data, $compfile) = @_; my $text = $data->{ text }; my ($parsedoc, $error); $self->debug("_compile($data, ", defined $compfile ? $compfile : '<no compfile>', ')') if $self->{ DEBUG }; my $parser = $self->{ PARSER } ||= Template::Config->parser($self->{ PARAMS }) || return (Template::Config->error(), Template::Constants::STATUS_ERROR); # discard the template text - we don't need it any more delete $data->{ text }; # call parser to compile template into Perl code if ($parsedoc = $parser->parse($text, $data)) { $parsedoc->{ METADATA } = { 'name' => $data->{ name }, 'modtime' => $data->{ 'time' }, %{ $parsedoc->{ METADATA } }, }; # write the Perl code to the file $compfile, if defined if ($compfile) { my $basedir = &File::Basename::dirname($compfile); { no warnings 'syntax'; $basedir = each %{ { $basedir => undef } } if ${^TAINT}; #untaint } unless (-d $basedir) { eval { File::Path::mkpath($basedir) }; $error = "failed to create compiled templates directory: $basedir ($@)" if ($@); } unless ($error) { my $docclass = $self->{ DOCUMENT }; $error = 'cache failed to write ' . &File::Basename::basename($compfile) . ': ' . $docclass->error() unless $docclass->write_perl_file($compfile, $parsedoc); } # set atime and mtime of newly compiled file, don't bother # if time is undef if (!defined($error) && defined $data->{ 'time' }) { my $cfile = do { no warnings 'syntax'; each %{ { $compfile => undef } }; }; if (!length $cfile) { return( "invalid filename: $compfile", Template::Constants::STATUS_ERROR ); }; my $ctime = $data->{ time }; if (!length $ctime || $ctime =~ tr{0-9}{}c) { return( "invalid time: $ctime", Template::Constants::STATUS_ERROR ); } utime($ctime, $ctime, $cfile); $self->debug(" cached compiled template to file [$compfile]") if $self->{ DEBUG }; } } unless ($error) { return $data ## RETURN ## if $data->{ data } = $DOCUMENT->new($parsedoc); $error = $Template::Document::ERROR; } } else { $error = Template::Exception->new( 'parse', "$data->{ name } " . $parser->error() ); } # return STATUS_ERROR, or STATUS_DECLINED if we're being tolerant return $self->{ TOLERANT } ? (undef, Template::Constants::STATUS_DECLINED) : ($error, Template::Constants::STATUS_ERROR) } #------------------------------------------------------------------------ # _compiled_is_current( $template_name ) # # Returns true if $template_name and its compiled name # exist and they have the same mtime. #------------------------------------------------------------------------ sub _compiled_is_current { my ( $self, $template_name, $uncompiled_template_mtime ) = @_; my $compiled_name = $self->_compiled_filename($template_name); return unless defined $compiled_name; my $compiled_mtime = (stat($compiled_name))[9]; return unless defined $compiled_mtime; my $template_mtime = $uncompiled_template_mtime || $self->_template_modified( $template_name ) or return; return unless defined $template_mtime; # This was >= in the 2.15, but meant that downgrading # a source template would not get picked up. return $compiled_mtime == $template_mtime ? $template_mtime : 0; } #------------------------------------------------------------------------ # _template_modified($path) # # Returns the last modified time of the $path. # Returns undef if the path does not exist. # Override if templates are not on disk, for example #------------------------------------------------------------------------ sub _template_modified { my $self = shift; my $template = shift || return; return (stat( $template ))[9]; } #------------------------------------------------------------------------ # _template_content($path) # # Fetches content pointed to by $path. # Returns the content in scalar context. # Returns ($data, $error, $mtime) in list context where # $data - content # $error - error string if there was an error, otherwise undef # $mtime - last modified time from calling stat() on the path #------------------------------------------------------------------------ sub _template_content { my ($self, $path) = @_; return (undef, "No path specified to fetch content from ") unless $path; my $data; my $mod_date; my $error; local *FH; if(-d $path) { $error = "$path: not a file"; } elsif (open(FH, "<", $path)) { local $/; binmode(FH); $data = <FH>; $mod_date = (stat($path))[9]; close(FH); } else { $error = "$path: $!"; } return wantarray ? ( $data, $error, $mod_date ) : $data; } #------------------------------------------------------------------------ # _modified($name) # _modified($name, $time) # # When called with a single argument, it returns the modification time # of the named template. When called with a second argument it returns # true if $name has been modified since $time. #------------------------------------------------------------------------ sub _modified { my ($self, $name, $time) = @_; my $load = $self->_template_modified($name); return $time ? 1 : 0 unless defined $load; return $time ? $load > $time : $load; } #------------------------------------------------------------------------ # _decode_unicode # # Decodes encoded unicode text that starts with a BOM and # turns it into perl's internal representation #------------------------------------------------------------------------ sub _decode_unicode { my $self = shift; my $string = shift; return undef unless defined $string; use bytes; require Encode; return $string if Encode::is_utf8( $string ); # try all the BOMs in order looking for one (order is important # 32bit BOMs look like 16bit BOMs) my $count = 0; while ($count < @{ $boms }) { my $enc = $boms->[$count++]; my $bom = $boms->[$count++]; # does the string start with the bom? if ($bom eq substr($string, 0, length($bom))) { # decode it and hand it back return Encode::decode($enc, substr($string, length($bom)), 1); } } return $self->{ ENCODING } ? Encode::decode( $self->{ ENCODING }, $string ) : $string; } 1; __END__ =head1 NAME Template::Provider - Provider module for loading/compiling templates =head1 SYNOPSIS $provider = Template::Provider->new(\%options); ($template, $error) = $provider->fetch($name); =head1 DESCRIPTION The L<Template::Provider> is used to load, parse, compile and cache template documents. This object may be sub-classed to provide more specific facilities for loading, or otherwise providing access to templates. The L<Template::Context> objects maintain a list of L<Template::Provider> objects which are polled in turn (via L<fetch()|Template::Context#fetch()>) to return a requested template. Each may return a compiled template, raise an error, or decline to serve the request, giving subsequent providers a chance to do so. The L<Template::Provider> can also be subclassed to provide templates from a different source, e.g. a database. See L<SUBCLASSING> below. This documentation needs work. =head1 PUBLIC METHODS =head2 new(\%options) Constructor method which instantiates and returns a new C<Template::Provider> object. A reference to a hash array of configuration options may be passed. See L<CONFIGURATION OPTIONS> below for a summary of configuration options and L<Template::Manual::Config> for full details. =head2 fetch($name) Returns a compiled template for the name specified. If the template cannot be found then C<(undef, STATUS_DECLINED)> is returned. If an error occurs (e.g. read error, parse error) then C<($error, STATUS_ERROR)> is returned, where C<$error> is the error message generated. If the L<TOLERANT> option is set the the method returns C<(undef, STATUS_DECLINED)> instead of returning an error. =head2 load($name) Loads a template without parsing or compiling it. This is used by the the L<INSERT|Template::Manual::Directives#INSERT> directive. =head2 store($name, $template) Stores the compiled template, C<$template>, in the cache under the name, C<$name>. Susbequent calls to C<fetch($name)> will return this template in preference to any disk-based file. =head2 include_path(\@newpath) Accessor method for the C<INCLUDE_PATH> setting. If called with an argument, this method will replace the existing C<INCLUDE_PATH> with the new value. =head2 paths() This method generates a copy of the C<INCLUDE_PATH> list. Any elements in the list which are dynamic generators (e.g. references to subroutines or objects implementing a C<paths()> method) will be called and the list of directories returned merged into the output list. It is possible to provide a generator which returns itself, thus sending this method into an infinite loop. To detect and prevent this from happening, the C<$MAX_DIRS> package variable, set to C<64> by default, limits the maximum number of paths that can be added to, or generated for the output list. If this number is exceeded then the method will immediately return an error reporting as much. =head1 CONFIGURATION OPTIONS The following list summarises the configuration options that can be provided to the C<Template::Provider> L<new()> constructor. Please consult L<Template::Manual::Config> for further details and examples of each configuration option in use. =head2 INCLUDE_PATH The L<INCLUDE_PATH|Template::Manual::Config#INCLUDE_PATH> option is used to specify one or more directories in which template files are located. # single path my $provider = Template::Provider->new({ INCLUDE_PATH => '/usr/local/templates', }); # multiple paths my $provider = Template::Provider->new({ INCLUDE_PATH => [ '/usr/local/templates', '/tmp/my/templates' ], }); =head2 ABSOLUTE The L<ABSOLUTE|Template::Manual::Config#ABSOLUTE> flag is used to indicate if templates specified with absolute filenames (e.g. 'C</foo/bar>') should be processed. It is disabled by default and any attempt to load a template by such a name will cause a 'C<file>' exception to be raised. my $provider = Template::Provider->new({ ABSOLUTE => 1, }); =head2 RELATIVE The L<RELATIVE|Template::Manual::Config#RELATIVE> flag is used to indicate if templates specified with filenames relative to the current directory (e.g. C<./foo/bar> or C<../../some/where/else>) should be loaded. It is also disabled by default, and will raise a C<file> error if such template names are encountered. my $provider = Template::Provider->new({ RELATIVE => 1, }); =head2 DEFAULT The L<DEFAULT|Template::Manual::Config#DEFAULT> option can be used to specify a default template which should be used whenever a specified template can't be found in the L<INCLUDE_PATH>. my $provider = Template::Provider->new({ DEFAULT => 'notfound.html', }); If a non-existant template is requested through the L<Template> L<process()|Template#process()> method, or by an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive, then the C<DEFAULT> template will instead be processed, if defined. Note that the C<DEFAULT> template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string. =head2 ENCODING The Template Toolkit will automatically decode Unicode templates that have a Byte Order Marker (BOM) at the start of the file. This option can be used to set the default encoding for templates that don't define a BOM. my $provider = Template::Provider->new({ ENCODING => 'utf8', }); See L<Encode> for further information. =head2 CACHE_SIZE The L<CACHE_SIZE|Template::Manual::Config#CACHE_SIZE> option can be used to limit the number of compiled templates that the module should cache. By default, the L<CACHE_SIZE|Template::Manual::Config#CACHE_SIZE> is undefined and all compiled templates are cached. my $provider = Template::Provider->new({ CACHE_SIZE => 64, # only cache 64 compiled templates }); =head2 STAT_TTL The L<STAT_TTL|Template::Manual::Config#STAT_TTL> value can be set to control how long the C<Template::Provider> will keep a template cached in memory before checking to see if the source template has changed. my $provider = Template::Provider->new({ STAT_TTL => 60, # one minute }); =head2 COMPILE_EXT The L<COMPILE_EXT|Template::Manual::Config#COMPILE_EXT> option can be provided to specify a filename extension for compiled template files. It is undefined by default and no attempt will be made to read or write any compiled template files. my $provider = Template::Provider->new({ COMPILE_EXT => '.ttc', }); =head2 COMPILE_DIR The L<COMPILE_DIR|Template::Manual::Config#COMPILE_DIR> option is used to specify an alternate directory root under which compiled template files should be saved. my $provider = Template::Provider->new({ COMPILE_DIR => '/tmp/ttc', }); =head2 TOLERANT The L<TOLERANT|Template::Manual::Config#TOLERANT> flag can be set to indicate that the C<Template::Provider> module should ignore any errors encountered while loading a template and instead return C<STATUS_DECLINED>. =head2 PARSER The L<PARSER|Template::Manual::Config#PARSER> option can be used to define a parser module other than the default of L<Template::Parser>. my $provider = Template::Provider->new({ PARSER => MyOrg::Template::Parser->new({ ... }), }); =head2 DEBUG The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable debugging messages from the L<Template::Provider> module by setting it to include the C<DEBUG_PROVIDER> value. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_PROVIDER, }); =head1 SUBCLASSING The C<Template::Provider> module can be subclassed to provide templates from a different source (e.g. a database). In most cases you'll just need to provide custom implementations of the C<_template_modified()> and C<_template_content()> methods. If your provider requires and custom initialisation then you'll also need to implement a new C<_init()> method. Caching in memory and on disk will still be applied (if enabled) when overriding these methods. =head2 _template_modified($path) Returns a timestamp of the C<$path> passed in by calling C<stat()>. This can be overridden, for example, to return a last modified value from a database. The value returned should be a timestamp value (as returned by C<time()>, although a sequence number should work as well. =head2 _template_content($path) This method returns the content of the template for all C<INCLUDE>, C<PROCESS>, and C<INSERT> directives. When called in scalar context, the method returns the content of the template located at C<$path>, or C<undef> if C<$path> is not found. When called in list context it returns C<($content, $error, $mtime)>, where C<$content> is the template content, C<$error> is an error string (e.g. "C<$path: File not found>"), and C<$mtime> is the template modification time. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Parser>, L<Template::Context> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[BL*0t� t� lib/Template/App/ttree.pmnu ��6�$ package Template::App::ttree; #======================================================================== # # Template::App::ttre # # DESCRIPTION # Script for processing all directory trees containing templates. # Template files are processed and the output directed to the # relvant file in an output tree. The timestamps of the source and # destination files can then be examined for future invocations # to process only those files that have changed. In other words, # it's a lot like 'make' for templates. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2013 Andy Wardley. All Rights Reserved. # Copyright (C) 1998-2003 Canon Research Centre Europe Ltd. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== use strict; use warnings; use base 'Template::Base'; our $VERSION = '2.91'; use Template; use AppConfig qw( :expand ); use File::Copy; use File::Path; use File::Spec; use File::Basename; use Text::ParseWords qw(quotewords); use constant DEFAULT_TTMODULE => 'Template'; use constant DEFAULT_HOME => $ENV{ HOME } || ''; sub emit_warn { my $self = shift; my $msg = shift; warn $msg; } sub emit_log { my $self = shift; print @_ } sub _get_myname { my $self = shift; (split /[:]{2}/, __PACKAGE__)[-1]; } sub _get_rc_file { my $self = shift; my $NAME = $self->_get_myname(); return $ENV{"\U${NAME}rc"} || DEFAULT_HOME . "/.${NAME}rc"; } sub offer_create_a_sample_config_file { my $self = shift; my $RCFILE = $self->_get_rc_file(); # offer create a sample config file if it doesn't exist, unless a '-f' # has been specified on the command line unless (-f $RCFILE or grep(/^(-f|-h|--help)$/, @ARGV) ) { $self->emit_log("Do you want me to create a sample '.ttreerc' file for you?\n", "(file: $RCFILE) [y/n]: "); my $y = <STDIN>; if ($y =~ /^y(es)?/i) { $self->write_config($RCFILE); exit(0); } } } sub run { my $self = shift; my $NAME = $self->_get_myname(); #------------------------------------------------------------------------ # configuration options #------------------------------------------------------------------------ # read configuration file and command line arguments - I need to remember # to fix varlist() and varhash() in AppConfig to make this nicer... my $config = $self->read_config( $self->_get_rc_file() ); my $dryrun = $config->nothing; my $verbose = $config->verbose || $dryrun; my $colour = $config->colour; my $summary = $config->summary; my $recurse = $config->recurse; my $preserve = $config->preserve; my $all = $config->all; my $libdir = $config->lib; my $ignore = $config->ignore; my $copy = $config->copy; my $link = $config->link; my $accept = $config->accept; my $absolute = $config->absolute; my $relative = $config->relative; my $suffix = $config->suffix; my $binmode = $config->binmode; my $depends = $config->depend; my $depsfile = $config->depend_file; my $copy_dir = $config->copy_dir; my ($n_proc, $n_unmod, $n_skip, $n_copy, $n_link, $n_mkdir) = (0) x 6; my $srcdir = $config->src || die "Source directory not set (-s)\n"; my $destdir = $config->dest || die "Destination directory not set (-d)\n"; die "Source and destination directories may not be the same:\n $srcdir\n" if $srcdir eq $destdir; # unshift any perl5lib directories onto front of INC unshift(@INC, @{ $config->perl5lib }); # get all template_* options from the config and fold keys to UPPER CASE my %ttopts = $config->varlist('^template_', 1); my $ttmodule = delete($ttopts{ module }); my $ucttopts = { map { my $v = $ttopts{ $_ }; defined $v ? (uc $_, $v) : () } keys %ttopts, }; # get all template variable definitions my $replace = $config->get('define'); # now create complete parameter hash for creating template processor my $ttopts = { %$ucttopts, RELATIVE => $relative, ABSOLUTE => $absolute, INCLUDE_PATH => [ $srcdir, @$libdir ], OUTPUT_PATH => $destdir, }; # load custom template module if ($ttmodule) { my $ttpkg = $ttmodule; $ttpkg =~ s[::][/]g; $ttpkg .= '.pm'; require $ttpkg; } else { $ttmodule = DEFAULT_TTMODULE; } #------------------------------------------------------------------------ # inter-file dependencies #------------------------------------------------------------------------ if ($depsfile or $depends) { $depends = $self->dependencies($depsfile, $depends); } else { $depends = { }; } my $global_deps = $depends->{'*'} || [ ]; # add any PRE_PROCESS, etc., templates as global dependencies foreach my $ttopt (qw( PRE_PROCESS POST_PROCESS PROCESS WRAPPER )) { my $deps = $ucttopts->{ $ttopt } || next; my @deps = ref $deps eq 'ARRAY' ? (@$deps) : ($deps); next unless @deps; push(@$global_deps, @deps); } # remove any duplicates $global_deps = { map { ($_ => 1) } @$global_deps }; $global_deps = [ keys %$global_deps ]; # update $depends hash or delete it if there are no dependencies if (@$global_deps) { $depends->{'*'} = $global_deps; } else { delete $depends->{'*'}; $global_deps = undef; } $depends = undef unless keys %$depends; my $DEP_DEBUG = $config->depend_debug(); #------------------------------------------------------------------------ # pre-amble #------------------------------------------------------------------------ if ($colour) { no strict 'refs'; *red = \&_red; *green = \&_green; *yellow = \&_yellow; *blue = \&_blue; } else { no strict 'refs'; *red = \&_white; *green = \&_white; *yellow = \&_white; *blue = \&_white; } if ($verbose) { local $" = ', '; $self->emit_log( "$NAME $VERSION (Template Toolkit version $Template::VERSION)\n\n" ); my $sfx = join(', ', map { "$_ => $suffix->{$_}" } keys %$suffix); $self->emit_log(" Source: $srcdir\n", " Destination: $destdir\n", "Include Path: [ @$libdir ]\n", " Ignore: [ @$ignore ]\n", " Copy: [ @$copy ]\n", " Link: [ @$link ]\n", " Copy_Dir: [ @$copy_dir ]\n", " Accept: [ @$accept ]\n", " Suffix: [ $sfx ]\n"); $self->emit_log(" Module: $ttmodule ", $ttmodule->module_version(), "\n") unless $ttmodule eq DEFAULT_TTMODULE; if ($depends && $DEP_DEBUG) { $self->emit_log("Dependencies:\n"); foreach my $key ('*', grep { !/\*/ } keys %$depends) { $self->emit_log( sprintf( " %-16s %s\n", $key, join(', ', @{ $depends->{ $key } }) ) ) if defined $depends->{ $key }; } } $self->emit_log( "\n" ) if $verbose > 1; $self->emit_log( red("NOTE: dry run, doing nothing...\n") ) if $dryrun; } #------------------------------------------------------------------------ # main processing loop #------------------------------------------------------------------------ my $template = $ttmodule->new($ttopts) || die $ttmodule->error(); my $running_conf = { accept => $accept, all => $all, binmode => $binmode, config => $config, copy => $copy, copy_dir => $copy_dir, depends => $depends, destdir => $destdir, dryrun => $dryrun, ignore => $ignore, libdir => $libdir, link => $link, n_copy => $n_copy, n_link => $n_link, n_mkdir => $n_mkdir, n_proc => $n_proc, n_skip => $n_skip, n_unmod => $n_unmod, preserve => $preserve, recurse => $recurse, replace => $replace, srcdir => $srcdir, suffix => $suffix, template => $template, verbose => $verbose, }; if (@ARGV) { # explicitly process files specified on command lines foreach my $file (@ARGV) { my $path = $srcdir ? File::Spec->catfile($srcdir, $file) : $file; if ( -d $path ) { $self->process_tree($file, $running_conf); } else { $self->process_file($file, $path, $running_conf, force => 1); } } } else { # implicitly process all file in source directory $self->process_tree(undef, $running_conf); } if ($summary || $verbose) { my $format = "%13d %s %s\n"; $self->emit_log( "\n" ) if $verbose > 1; $self->emit_log( " Summary: ", $dryrun ? red("This was a dry run. Nothing was actually done\n") : "\n", green(sprintf($format, $n_proc, $n_proc == 1 ? 'file' : 'files', 'processed')), green(sprintf($format, $n_copy, $n_copy == 1 ? 'file' : 'files', 'copied')), green(sprintf($format, $n_link, $n_link == 1 ? 'file' : 'files', 'linked')), green(sprintf($format, $n_mkdir, $n_mkdir == 1 ? 'directory' : 'directories', 'created')), yellow(sprintf($format, $n_unmod, $n_unmod == 1 ? 'file' : 'files', 'skipped (not modified)')), yellow(sprintf($format, $n_skip, $n_skip == 1 ? 'file' : 'files', 'skipped (ignored)')) ); } } #======================================================================== # END #======================================================================== #------------------------------------------------------------------------ # $self->process_tree($dir) # # Walks the directory tree starting at $dir or the current directory # if unspecified, processing files as found. #------------------------------------------------------------------------ sub process_tree { my $self = shift; my $dir = shift; my $running_conf = shift; my( $destdir, $dryrun, $ignore, $n_mkdir, $n_skip, $recurse, $srcdir, $verbose, ) = @{ $running_conf }{ qw( destdir dryrun ignore n_mkdir n_skip recurse srcdir verbose )}; my ($file, $path, $abspath, $check); my $target; local *DIR; my $absdir = join('/', $srcdir ? $srcdir : (), defined $dir ? $dir : ()); $absdir ||= '.'; opendir(DIR, $absdir) || do { $self->emit_warn("$absdir: $!\n"); return undef; }; FILE: while (defined ($file = readdir(DIR))) { next if $file eq '.' || $file eq '..'; $path = defined $dir ? "$dir/$file" : $file; $abspath = "$absdir/$file"; next unless -e $abspath; # check against ignore list foreach $check (@$ignore) { if ($path =~ /$check/) { $self->emit_log( yellow(sprintf " - %-32s (ignored, matches /$check/)\n", $path ) ) if $verbose > 1; $n_skip++; next FILE; } } if (-d $abspath) { if ($recurse) { my ($uid, $gid, $mode); (undef, undef, $mode, undef, $uid, $gid, undef, undef, undef, undef, undef, undef, undef) = stat($abspath); # create target directory if required $target = "$destdir/$path"; unless (-d $target || $dryrun) { mkpath($target, $verbose, $mode) or die red("Could not mkpath ($target): $!\n"); # commented out by abw on 2000/12/04 - seems to raise a warning? # chown($uid, $gid, $target) || warn "chown($target): $!\n"; $n_mkdir++; $self->emit_log( green( sprintf " + %-32s (created target directory)\n", $path ) ) if $verbose; } # recurse into directory $self->process_tree($path, $running_conf); } else { $n_skip++; $self->emit_log( yellow(sprintf " - %-32s (directory, not recursing)\n", $path ) ) if $verbose > 1; } } else { $self->process_file($path, $abspath, $running_conf); } } closedir(DIR); } #------------------------------------------------------------------------ # $self->process_file() # # File filtering and processing sub-routine called by $self->process_tree() #------------------------------------------------------------------------ sub process_file { my $self = shift; my ($file, $absfile, $running_conf, %options) = @_; my( $accept, $all, $binmode, $config, $copy, $copy_dir, $depends, $destdir, $dryrun, $libdir, $link, $n_copy, $n_link, $n_proc, $n_skip, $n_unmod, $preserve, $replace, $srcdir, $suffix, $template, $verbose, ) = @{ $running_conf }{ qw( accept all binmode config copy copy_dir depends destdir dryrun libdir link n_copy n_link n_proc n_skip n_unmod preserve replace srcdir suffix template verbose )}; my ($dest, $destfile, $filename, $check, $srctime, $desttime, $mode, $uid, $gid); my ($old_suffix, $new_suffix); my $is_dep = 0; my $copy_file = 0; my $link_file = 0; $absfile ||= $file; $filename = basename($file); $destfile = $file; # look for any relevant suffix mapping if (%$suffix) { if ($filename =~ m/\.(.+)$/) { $old_suffix = $1; if ($new_suffix = $suffix->{ $old_suffix }) { $destfile =~ s/$old_suffix$/$new_suffix/; } } } $dest = $destdir ? "$destdir/$destfile" : $destfile; # $self->emit_log( "proc $file => $dest\n" ); unless ($link_file) { # check against link list foreach my $link_pattern (@$link) { if ($filename =~ /$link_pattern/) { $link_file = $copy_file = 1; $check = "/$link_pattern/"; last; } } } unless ($link_file) { foreach my $prefix (@$copy_dir) { if ( index($file, "$prefix/") == 0 ) { $copy_file = 1; $check = "copy_dir: $prefix"; last; } } } unless ($copy_file) { # check against copy list foreach my $copy_pattern (@$copy) { if ($filename =~ /$copy_pattern/) { $copy_file = 1; $check = "/$copy_pattern/"; last; } } } # check against acceptance list if (not $copy_file and @$accept) { unless (grep { $filename =~ /$_/ } @$accept) { $self->emit_log( yellow( sprintf " - %-32s (not accepted)\n", $file ) ) if $verbose > 1; $n_skip++; return; } } # stat the source file unconditionally, so we can preserve # mode and ownership ( undef, undef, $mode, undef, $uid, $gid, undef, undef, undef, $srctime, undef, undef, undef ) = stat($absfile); # test modification time of existing destination file if (! $all && ! $options{ force } && -f $dest) { $desttime = ( stat($dest) )[9]; if (defined $depends and not $copy_file) { my $deptime = $self->depend_time($file, $depends, $config, $libdir, $srcdir); if (defined $deptime && ($srctime < $deptime)) { $srctime = $deptime; $is_dep = 1; } } if ($desttime >= $srctime) { $self->emit_log( yellow( sprintf " - %-32s (not modified)\n", $file ) ) if $verbose > 1; $n_unmod++; return; } } # check against link list if ($link_file) { unless ($dryrun) { if (link($absfile, $dest) == 1) { $copy_file = 0; } else { $self->emit_warn( red("Could not link ($absfile to $dest) : $!\n") ); } } unless ($copy_file) { $n_link++; $self->emit_log( green( sprintf " > %-32s (linked, matches $check)\n", $file ) ) if $verbose; return; } } # check against copy list if ($copy_file) { $n_copy++; unless ($dryrun) { copy($absfile, $dest) or die red("Could not copy ($absfile to $dest) : $!\n"); if ($preserve) { chown($uid, $gid, $dest) || $self->emit_warn( red("chown($dest): $!\n") ); chmod($mode, $dest) || $self->emit_warn( red("chmod($dest): $!\n") ); } } $self->emit_log( green( sprintf " > %-32s (copied, matches $check)\n", $file ) ) if $verbose; return; } $n_proc++; if ($verbose) { $self->emit_log( green( sprintf " + %-32s", $file) ); $self->emit_log( green( sprintf " (changed suffix to $new_suffix)") ) if $new_suffix; $self->emit_log( "\n" ); } # process file unless ($dryrun) { $template->process($file, $replace, $destfile, $binmode ? {binmode => $binmode} : {}) || $self->emit_log(red(" ! "), $template->error(), "\n"); if ($preserve) { chown($uid, $gid, $dest) || $self->emit_warn( red("chown($dest): $!\n") ); chmod($mode, $dest) || $self->emit_warn( red("chmod($dest): $!\n") ); } } } #------------------------------------------------------------------------ # $self->dependencies($file, $depends) # # Read the dependencies from $file, if defined, and merge in with # those passed in as the hash array $depends, if defined. #------------------------------------------------------------------------ sub dependencies { my $self = shift; my ($file, $depend) = @_; my %depends = (); if (defined $file) { my ($fh, $text, $line); open $fh, $file or die "Can't open $file, $!"; local $/ = undef; $text = <$fh>; close($fh); $text =~ s[\\\n][]mg; foreach $line (split("\n", $text)) { next if $line =~ /^\s*(#|$)/; chomp $line; my ($file, @files) = quotewords('\s*:\s*', 0, $line); $file =~ s/^\s+//; @files = grep(defined, quotewords('(,|\s)\s*', 0, @files)); $depends{$file} = \@files; } } if (defined $depend) { foreach my $key (keys %$depend) { $depends{$key} = [ quotewords(',', 0, $depend->{$key}) ]; } } return \%depends; } #------------------------------------------------------------------------ # $self->depend_time($file, \%depends) # # Returns the mtime of the most recent in @files. #------------------------------------------------------------------------ sub depend_time { my $self = shift; my ($file, $depends, $config, $libdir, $srcdir) = @_; my ($deps, $absfile, $modtime); my $maxtime = 0; my @pending = ($file); my @files; my %seen; my $DEP_DEBUG = $config->depend_debug(); # push any global dependencies onto the pending list if ($deps = $depends->{'*'}) { push(@pending, @$deps); } $self->emit_log( " # checking dependencies for $file...\n" ) if $DEP_DEBUG; # iterate through the list of pending files while (@pending) { $file = shift @pending; next if $seen{ $file }++; if (File::Spec->file_name_is_absolute($file) && -f $file) { $modtime = (stat($file))[9]; $self->emit_log( " # $file [$modtime]\n" ) if $DEP_DEBUG; } else { $modtime = 0; foreach my $dir ($srcdir, @$libdir) { $absfile = File::Spec->catfile($dir, $file); if (-f $absfile) { $modtime = (stat($absfile))[9]; $self->emit_log( " # $absfile [$modtime]\n" ) if $DEP_DEBUG; last; } } } $maxtime = $modtime if $modtime > $maxtime; if ($deps = $depends->{ $file }) { push(@pending, @$deps); $self->emit_log( " # depends on ", join(', ', @$deps), "\n" ) if $DEP_DEBUG; } } return $maxtime; } #------------------------------------------------------------------------ # read_config($file) # # Handles reading of config file and/or command line arguments. #------------------------------------------------------------------------ sub read_config { my $self = shift; my $file = shift; my $NAME = $self->_get_myname(); my $verbose = 0; my $verbinc = sub { my ($state, $var, $value) = @_; $state->{ VARIABLE }->{ verbose } = $value ? ++$verbose : --$verbose; }; my $config = AppConfig->new( { ERROR => sub { die(@_, "\ntry `$NAME --help'\n") } }, 'help|h' => { ACTION => sub { $self->help } }, 'src|s=s' => { EXPAND => EXPAND_ALL }, 'dest|d=s' => { EXPAND => EXPAND_ALL }, 'lib|l=s@' => { EXPAND => EXPAND_ALL }, 'cfg|c=s' => { EXPAND => EXPAND_ALL, DEFAULT => '.' }, 'verbose|v' => { DEFAULT => 0, ACTION => $verbinc }, 'recurse|r' => { DEFAULT => 0 }, 'nothing|n' => { DEFAULT => 0 }, 'preserve|p' => { DEFAULT => 0 }, 'absolute' => { DEFAULT => 0 }, 'relative' => { DEFAULT => 0 }, 'colour|color'=> { DEFAULT => 0 }, 'summary' => { DEFAULT => 0 }, 'all|a' => { DEFAULT => 0 }, 'define=s%', 'suffix=s%', 'binmode=s', 'ignore=s@', 'copy=s@', 'link=s@', 'accept=s@', 'depend=s%', 'depend_debug|depdbg', 'depend_file|depfile=s' => { EXPAND => EXPAND_ALL }, 'copy_dir=s@', 'template_module|module=s', 'template_anycase|anycase', 'template_encoding|encoding=s', 'template_eval_perl|eval_perl', 'template_load_perl|load_perl', 'template_interpolate|interpolate', 'template_pre_chomp|pre_chomp|prechomp', 'template_post_chomp|post_chomp|postchomp', 'template_trim|trim', 'template_pre_process|pre_process|preprocess=s@', 'template_post_process|post_process|postprocess=s@', 'template_process|process=s', 'template_wrapper|wrapper=s', 'template_recursion|recursion', 'template_expose_blocks|expose_blocks', 'template_default|default=s', 'template_error|error=s', 'template_debug|debug=s', 'template_strict|strict', 'template_start_tag|start_tag|starttag=s', 'template_end_tag|end_tag|endtag=s', 'template_tag_style|tag_style|tagstyle=s', 'template_compile_ext|compile_ext=s', 'template_compile_dir|compile_dir=s' => { EXPAND => EXPAND_ALL }, 'template_plugin_base|plugin_base|pluginbase=s@' => { EXPAND => EXPAND_ALL }, 'perl5lib|perllib=s@' => { EXPAND => EXPAND_ALL }, ); # add the 'file' option now that we have a $config object that we # can reference in a closure $config->define( 'file|f=s@' => { EXPAND => EXPAND_ALL, ACTION => sub { my ($state, $item, $file) = @_; $file = $state->cfg . "/$file" unless $file =~ /^[\.\/]|(?:\w:)/; $config->file($file) } } ); # process main config file, then command line args $config->file($file) if -f $file; $config->args(); $config; } sub ANSI_escape { my $attr = shift; my $text = join('', @_); return join("\n", map { # look for an existing escape start sequence and add new # attribute to it, otherwise add escape start/end sequences s/ \e \[ ([1-9][\d;]*) m/\e[$1;${attr}m/gx ? $_ : "\e[${attr}m" . $_ . "\e[0m"; } split(/\n/, $text, -1) # -1 prevents it from ignoring trailing fields ); } sub _red(@) { ANSI_escape(31, @_) } sub _green(@) { ANSI_escape(32, @_) } sub _yellow(@) { ANSI_escape(33, @_) } sub _blue(@) { ANSI_escape(34, @_) } sub _white(@) { @_ } # nullop #------------------------------------------------------------------------ # $self->write_config($file) # # Writes a sample configuration file to the filename specified. #------------------------------------------------------------------------ sub write_config { my $self = shift; my $file = shift; my $NAME = $self->_get_myname(); open(CONFIG, ">", $file) || die "failed to create $file: $!\n"; print(CONFIG <<END_OF_CONFIG); #------------------------------------------------------------------------ # sample .ttreerc file created automatically by $NAME version $VERSION # # This file originally written to $file # # For more information on the contents of this configuration file, see # # perldoc ttree # ttree -h # #------------------------------------------------------------------------ # The most flexible way to use ttree is to create a separate directory # for configuration files and simply use the .ttreerc to tell ttree where # it is. # # cfg = /path/to/ttree/config/directory # print summary of what's going on verbose # recurse into any sub-directories and process files recurse # regexen of things that aren't templates and should be ignored ignore = \\b(CVS|RCS)\\b ignore = ^# # ditto for things that should be copied rather than processed. copy = \\.png\$ copy = \\.gif\$ # ditto for things that should be linked rather than copied / processed. # link = \\.flv\$ # by default, everything not ignored or copied is accepted; add 'accept' # lines if you want to filter further. e.g. # # accept = \\.html\$ # accept = \\.tt2\$ # options to rewrite files suffixes (htm => html, tt2 => html) # # suffix htm=html # suffix tt2=html # options to define dependencies between templates # # depend *=header,footer,menu # depend index.html=mainpage,sidebar # depend menu=menuitem,menubar # #------------------------------------------------------------------------ # The following options usually relate to a particular project so # you'll probably want to put them in a separate configuration file # in the directory specified by the 'cfg' option and then invoke tree # using '-f' to tell it which configuration you want to use. # However, there's nothing to stop you from adding default 'src', # 'dest' or 'lib' options in the .ttreerc. The 'src' and 'dest' options # can be re-defined in another configuration file, but be aware that 'lib' # options accumulate so any 'lib' options defined in the .ttreerc will # be applied every time you run ttree. #------------------------------------------------------------------------ # # directory containing source page templates # src = /path/to/your/source/page/templates # # # directory where output files should be written # dest = /path/to/your/html/output/directory # # # additional directories of library templates # lib = /first/path/to/your/library/templates # lib = /second/path/to/your/library/templates END_OF_CONFIG close(CONFIG); $self->emit_log( "$file created. Please edit accordingly and re-run $NAME\n" ); } #------------------------------------------------------------------------ # help() # # Prints help message and exits. #------------------------------------------------------------------------ sub help { my $self = shift; my $NAME = $self->_get_myname(); print<<END_OF_HELP; $NAME $VERSION (Template Toolkit version $Template::VERSION) usage: $NAME [options] [files] Options: -a (--all) Process all files, regardless of modification -r (--recurse) Recurse into sub-directories -p (--preserve) Preserve file ownership and permission -n (--nothing) Do nothing, just print summary (enables -v) -v (--verbose) Verbose mode. Use twice for more verbosity: -v -v -h (--help) This help -s DIR (--src=DIR) Source directory -d DIR (--dest=DIR) Destination directory -c DIR (--cfg=DIR) Location of configuration files -l DIR (--lib=DIR) Library directory (INCLUDE_PATH) (multiple) -f FILE (--file=FILE) Read named configuration file (multiple) Display options: --colour / --color Enable colo(u)rful verbose output. --summary Show processing summary. File search specifications (all may appear multiple times): --ignore=REGEX Ignore files matching REGEX --copy=REGEX Copy files matching REGEX --link=REGEX Link files matching REGEX --copy_dir=DIR Copy files in dir DIR (recursive) --accept=REGEX Process only files matching REGEX File Dependencies Options: --depend foo=bar,baz Specify that 'foo' depends on 'bar' and 'baz'. --depend_file FILE Read file dependancies from FILE. --depend_debug Enable debugging for dependencies File suffix rewriting (may appear multiple times) --suffix old=new Change any '.old' suffix to '.new' File encoding options --binmode=value Set binary mode of output files --encoding=value Set encoding of input files Additional options to set Template Toolkit configuration items: --define var=value Define template variable --interpolate Interpolate '\$var' references in text --anycase Accept directive keywords in any case. --pre_chomp Chomp leading whitespace --post_chomp Chomp trailing whitespace --trim Trim blank lines around template blocks --eval_perl Evaluate [% PERL %] ... [% END %] code blocks --load_perl Load regular Perl modules via USE directive --absolute Enable the ABSOLUTE option --relative Enable the RELATIVE option --pre_process=TEMPLATE Process TEMPLATE before each main template --post_process=TEMPLATE Process TEMPLATE after each main template --process=TEMPLATE Process TEMPLATE instead of main template --wrapper=TEMPLATE Process TEMPLATE wrapper around main template --default=TEMPLATE Use TEMPLATE as default --error=TEMPLATE Use TEMPLATE to handle errors --debug=STRING Set TT DEBUG option to STRING --start_tag=STRING STRING defines start of directive tag --end_tag=STRING STRING defined end of directive tag --tag_style=STYLE Use pre-defined tag STYLE --plugin_base=PACKAGE Base PACKAGE for plugins --compile_ext=STRING File extension for compiled template files --compile_dir=DIR Directory for compiled template files --perl5lib=DIR Specify additional Perl library directories --template_module=MODULE Specify alternate Template module See 'perldoc ttree' for further information. END_OF_HELP exit(0); } 1; __END__ =head1 NAME Template::App::ttree - Backend of ttree =head1 SYNOPSIS See L<Template::Tools::ttree|ttree>. =head1 DESCRIPTION See L<Template::Tools::ttree|ttree>. =head1 AUTHORS Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://www.wardley.org> With contributions from Dylan William Hardison (support for dependencies), Bryce Harrington (C<absolute> and C<relative> options), Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon Brocard who gets everywhere, it seems. =head1 COPYRIGHT Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Tools::ttree|ttree> =cut PK � �[ �jh h lib/Template/Stash/XS.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Stash::XS # # DESCRIPTION # # Perl bootstrap for XS module. Inherits methods from # Template::Stash when not implemented in the XS module. # #======================================================================== package Template::Stash::XS; use strict; use warnings; use Template; use Template::Stash; use XSLoader; our $AUTOLOAD; our @ISA = qw( Template::Stash ); XSLoader::load 'Template::Stash::XS', $Template::VERSION; sub DESTROY { # no op 1; } # catch missing method calls here so perl doesn't barf # trying to load *.al files sub AUTOLOAD { my ($self, @args) = @_; my @c = caller(0); my $auto = $AUTOLOAD; $auto =~ s/.*:://; $self =~ s/=.*//; die "Can't locate object method \"$auto\"" . " via package \"$self\" at $c[1] line $c[2]\n"; } 1; __END__ =head1 NAME Template::Stash::XS - High-speed variable stash written in C =head1 SYNOPSIS use Template; use Template::Stash::XS; my $stash = Template::Stash::XS->new(\%vars); my $tt2 = Template->new({ STASH => $stash }); =head1 DESCRIPTION The Template:Stash::XS module is an implementation of the Template::Stash written in C. The "XS" in the name refers to Perl's XS extension system for interfacing Perl to C code. It works just like the regular Perl implementation of Template::Stash but runs about twice as fast. The easiest way to use the XS stash is to configure the Template Toolkit to use it by default. You can do this at installation time (when you run C<perl Makefile.PL>) by answering 'y' to the questions: Do you want to build the XS Stash module? y Do you want to use the XS Stash by default? y See the F<INSTALL> file distributed with the Template Toolkit for further details on installation. If you don't elect to use the XS stash by default then you should use the C<STASH> configuration item when you create a new Template object. This should reference an XS stash object that you have created manually. use Template; use Template::Stash::XS; my $stash = Template::Stash::XS->new(\%vars); my $tt2 = Template->new({ STASH => $stash }); Alternately, you can set the C<$Template::Config::STASH> package variable like so: use Template; use Template::Config; $Template::Config::STASH = 'Template::Stash::XS'; my $tt2 = Template->new(); The XS stash will then be automatically used. If you want to use the XS stash by default and don't want to re-install the Template Toolkit, then you can manually modify the C<Template/Config.pm> module near line 42 to read: $STASH = 'Template::Stash::XS'; =head1 BUGS Please report bugs to the Template Toolkit mailing list templates@template-toolkit.org =head1 AUTHORS Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> Doug Steinwand E<lt>dsteinwand@citysearch.comE<gt> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Stash> PK � �[ lib/Template/Stash/.existsnu �[��� PK � �[�c��f �f lib/Template/Stash/Context.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Stash::Context # # DESCRIPTION # This is an alternate stash object which includes a patch from # Craig Barratt to implement various new virtual methods to allow # dotted template variable to denote if object methods and subroutines # should be called in scalar or list context. It adds a little overhead # to each stash call and I'm a little wary of doing that. So for now, # it's implemented as a separate stash module which will allow us to # test it out, benchmark it and switch it in or out as we require. # # This is what Craig has to say about it: # # Here's a better set of features for the core. Attached is a new version # of Stash.pm (based on TT2.02) that: # # - supports the special op "scalar" that forces scalar context on # function calls, eg: # # cgi.param("foo").scalar # # calls cgi.param("foo") in scalar context (unlike my wimpy # scalar op from last night). Array context is the default. # # With non-function operands, scalar behaves like the perl # version (eg: no-op for scalar, size for arrays, etc). # # - supports the special op "ref" that behaves like the perl ref. # If applied to a function the function is not called. Eg: # # cgi.param("foo").ref # # does *not* call cgi.param and evaluates to "CODE". Similarly, # HASH.ref, ARRAY.ref return what you expect. # # - adds a new scalar and list op called "array" that is a no-op for # arrays and promotes scalars to one-element arrays. # # - allows scalar ops to be applied to arrays and hashes in place, # eg: ARRAY.repeat(3) repeats each element in place. # # - allows list ops to be applied to scalars by promoting the scalars # to one-element arrays (like an implicit "array"). So you can # do things like SCALAR.size, SCALAR.join and get a useful result. # # This also means you can now use x.0 to safely get the first element # whether x is an array or scalar. # # The new Stash.pm passes the TT2.02 test suite. But I haven't tested the # new features very much. One nagging implementation problem is that the # "scalar" and "ref" ops have higher precedence than user variable names. # # AUTHORS # Andy Wardley <abw@kfs.org> # Craig Barratt <craig@arraycomm.com> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # Copyright (C) 1998-2001 Canon Research Centre Europe Ltd. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Stash::Context; use strict; use warnings; use base 'Template::Stash'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; #======================================================================== # -- PACKAGE VARIABLES AND SUBS -- #======================================================================== #------------------------------------------------------------------------ # copy virtual methods from those in the regular Template::Stash #------------------------------------------------------------------------ our $ROOT_OPS = { %$Template::Stash::ROOT_OPS, defined $ROOT_OPS ? %$ROOT_OPS : (), }; our $SCALAR_OPS = { %$Template::Stash::SCALAR_OPS, 'array' => sub { return [$_[0]] }, defined $SCALAR_OPS ? %$SCALAR_OPS : (), }; our $LIST_OPS = { %$Template::Stash::LIST_OPS, 'array' => sub { return $_[0] }, defined $LIST_OPS ? %$LIST_OPS : (), }; our $HASH_OPS = { %$Template::Stash::HASH_OPS, defined $HASH_OPS ? %$HASH_OPS : (), }; #======================================================================== # ----- CLASS METHODS ----- #======================================================================== #------------------------------------------------------------------------ # new(\%params) # # Constructor method which creates a new Template::Stash object. # An optional hash reference may be passed containing variable # definitions that will be used to initialise the stash. # # Returns a reference to a newly created Template::Stash. #------------------------------------------------------------------------ sub new { my $class = shift; my $params = ref $_[0] eq 'HASH' ? shift(@_) : { @_ }; my $self = { global => { }, %$params, %$ROOT_OPS, '_PARENT' => undef, '_CLASS' => $class, }; bless $self, $class; } #======================================================================== # ----- PUBLIC OBJECT METHODS ----- #======================================================================== #------------------------------------------------------------------------ # clone(\%params) # # Creates a copy of the current stash object to effect localisation # of variables. The new stash is blessed into the same class as the # parent (which may be a derived class) and has a '_PARENT' member added # which contains a reference to the parent stash that created it # ($self). This member is used in a successive declone() method call to # return the reference to the parent. # # A parameter may be provided which should reference a hash of # variable/values which should be defined in the new stash. The # update() method is called to define these new variables in the cloned # stash. # # Returns a reference to a cloned Template::Stash. #------------------------------------------------------------------------ sub clone { my ($self, $params) = @_; $params ||= { }; # look out for magical 'import' argument which imports another hash my $import = $params->{ import }; if (defined $import && UNIVERSAL::isa($import, 'HASH')) { delete $params->{ import }; } else { undef $import; } my $clone = bless { %$self, # copy all parent members %$params, # copy all new data '_PARENT' => $self, # link to parent }, ref $self; # perform hash import if defined &{ $HASH_OPS->{ import }}($clone, $import) if defined $import; return $clone; } #------------------------------------------------------------------------ # declone($export) # # Returns a reference to the PARENT stash. When called in the following # manner: # $stash = $stash->declone(); # the reference count on the current stash will drop to 0 and be "freed" # and the caller will be left with a reference to the parent. This # contains the state of the stash before it was cloned. #------------------------------------------------------------------------ sub declone { my $self = shift; $self->{ _PARENT } || $self; } #------------------------------------------------------------------------ # get($ident) # # Returns the value for an variable stored in the stash. The variable # may be specified as a simple string, e.g. 'foo', or as an array # reference representing compound variables. In the latter case, each # pair of successive elements in the list represent a node in the # compound variable. The first is the variable name, the second a # list reference of arguments or 0 if undefined. So, the compound # variable [% foo.bar('foo').baz %] would be represented as the list # [ 'foo', 0, 'bar', ['foo'], 'baz', 0 ]. Returns the value of the # identifier or an empty string if undefined. Errors are thrown via # die(). #------------------------------------------------------------------------ sub get { my ($self, $ident, $args) = @_; my ($root, $result); $root = $self; if (ref $ident eq 'ARRAY' || ($ident =~ /\./) && ($ident = [ map { s/\(.*$//; ($_, 0) } split(/\./, $ident) ])) { my $size = $#$ident; # if $ident is a list reference, then we evaluate each item in the # identifier against the previous result, using the root stash # ($self) as the first implicit 'result'... foreach (my $i = 0; $i <= $size; $i += 2) { if ( $i + 2 <= $size && ($ident->[$i+2] eq "scalar" || $ident->[$i+2] eq "ref") ) { $result = $self->_dotop($root, @$ident[$i, $i+1], 0, $ident->[$i+2]); $i += 2; } else { $result = $self->_dotop($root, @$ident[$i, $i+1]); } last unless defined $result; $root = $result; } } else { $result = $self->_dotop($root, $ident, $args); } return defined $result ? $result : $self->undefined($ident, $args); } #------------------------------------------------------------------------ # set($ident, $value, $default) # # Updates the value for a variable in the stash. The first parameter # should be the variable name or array, as per get(). The second # parameter should be the intended value for the variable. The third, # optional parameter is a flag which may be set to indicate 'default' # mode. When set true, the variable will only be updated if it is # currently undefined or has a false value. The magical 'IMPORT' # variable identifier may be used to indicate that $value is a hash # reference whose values should be imported. Returns the value set, # or an empty string if not set (e.g. default mode). In the case of # IMPORT, returns the number of items imported from the hash. #------------------------------------------------------------------------ sub set { my ($self, $ident, $value, $default) = @_; my ($root, $result, $error); $root = $self; ELEMENT: { if (ref $ident eq 'ARRAY' || ($ident =~ /\./) && ($ident = [ map { s/\(.*$//; ($_, 0) } split(/\./, $ident) ]) ) { # a compound identifier may contain multiple elements (e.g. # foo.bar.baz) and we must first resolve all but the last, # using _dotop() with the $lvalue flag set which will create # intermediate hashes if necessary... my $size = $#$ident; foreach (my $i = 0; $i < $size - 2; $i += 2) { $result = $self->_dotop($root, @$ident[$i, $i+1], 1); last ELEMENT unless defined $result; $root = $result; } # then we call _assign() to assign the value to the last element $result = $self->_assign( $root, @$ident[$size-1, $size], $value, $default ); } else { $result = $self->_assign($root, $ident, 0, $value, $default); } } return defined $result ? $result : ''; } #------------------------------------------------------------------------ # getref($ident) # # Returns a "reference" to a particular item. This is represented as a # closure which will return the actual stash item when called. # WARNING: still experimental! #------------------------------------------------------------------------ sub getref { my ($self, $ident, $args) = @_; my ($root, $item, $result); $root = $self; if (ref $ident eq 'ARRAY') { my $size = $#$ident; foreach (my $i = 0; $i <= $size; $i += 2) { ($item, $args) = @$ident[$i, $i + 1]; last if $i >= $size - 2; # don't evaluate last node last unless defined ($root = $self->_dotop($root, $item, $args)); } } else { $item = $ident; } if (defined $root) { return sub { my @args = (@{$args||[]}, @_); $self->_dotop($root, $item, \@args); } } else { return sub { '' }; } } #------------------------------------------------------------------------ # update(\%params) # # Update multiple variables en masse. No magic is performed. Simple # variable names only. #------------------------------------------------------------------------ sub update { my ($self, $params) = @_; # look out for magical 'import' argument to import another hash my $import = $params->{ import }; if (defined $import && UNIVERSAL::isa($import, 'HASH')) { @$self{ keys %$import } = values %$import; delete $params->{ import }; } @$self{ keys %$params } = values %$params; } #======================================================================== # ----- PRIVATE OBJECT METHODS ----- #======================================================================== #------------------------------------------------------------------------ # _dotop($root, $item, \@args, $lvalue, $nextItem) # # This is the core 'dot' operation method which evaluates elements of # variables against their root. All variables have an implicit root # which is the stash object itself (a hash). Thus, a non-compound # variable 'foo' is actually '(stash.)foo', the compound 'foo.bar' is # '(stash.)foo.bar'. The first parameter is a reference to the current # root, initially the stash itself. The second parameter contains the # name of the variable element, e.g. 'foo'. The third optional # parameter is a reference to a list of any parenthesised arguments # specified for the variable, which are passed to sub-routines, object # methods, etc. The final parameter is an optional flag to indicate # if this variable is being evaluated on the left side of an assignment # (e.g. foo.bar.baz = 10). When set true, intermediated hashes will # be created (e.g. bar) if necessary. # # Returns the result of evaluating the item against the root, having # performed any variable "magic". The value returned can then be used # as the root of the next _dotop() in a compound sequence. Returns # undef if the variable is undefined. #------------------------------------------------------------------------ sub _dotop { my ($self, $root, $item, $args, $lvalue, $nextItem) = @_; my $rootref = ref $root; my ($value, @result, $ret, $retVal); $nextItem ||= ""; my $scalarContext = 1 if ( $nextItem eq "scalar" ); my $returnRef = 1 if ( $nextItem eq "ref" ); $args ||= [ ]; $lvalue ||= 0; # print STDERR "_dotop(root=$root, item=$item, args=[@$args])\n" # if $DEBUG; # return undef without an error if either side of the dot is unviable # or if an attempt is made to access a private member, starting _ or . return undef unless defined($root) and defined($item) and $item !~ /^[\._]/; if (ref(\$root) eq "SCALAR" && !$lvalue && (($value = $LIST_OPS->{ $item }) || $item =~ /^-?\d+$/) ) { # # Promote scalar to one element list, to be processed below. # $rootref = 'ARRAY'; $root = [$root]; } if ($rootref eq $self->{_CLASS} || $rootref eq 'HASH') { # if $root is a regular HASH or a Template::Stash kinda HASH (the # *real* root of everything). We first lookup the named key # in the hash, or create an empty hash in its place if undefined # and the $lvalue flag is set. Otherwise, we check the HASH_OPS # pseudo-methods table, calling the code if found, or return undef. if (defined($value = $root->{ $item })) { ($ret, $retVal, @result) = _dotop_return( $value, $args, $returnRef, $scalarContext ); return $retVal if ( $ret ); ## RETURN } elsif ($lvalue) { # we create an intermediate hash if this is an lvalue return $root->{ $item } = { }; ## RETURN } elsif ($value = $HASH_OPS->{ $item }) { @result = &$value($root, @$args); ## @result } elsif (ref $item eq 'ARRAY') { # hash slice return [@$root{@$item}]; ## RETURN } elsif ($value = $SCALAR_OPS->{ $item }) { # # Apply scalar ops to every hash element, in place. # foreach my $key ( keys %$root ) { $root->{$key} = &$value($root->{$key}, @$args); } } } elsif ($rootref eq 'ARRAY') { # if root is an ARRAY then we check for a LIST_OPS pseudo-method # (except for l-values for which it doesn't make any sense) # or return the numerical index into the array, or undef if (($value = $LIST_OPS->{ $item }) && ! $lvalue) { @result = &$value($root, @$args); ## @result } elsif (($value = $SCALAR_OPS->{ $item }) && ! $lvalue) { # # Apply scalar ops to every array element, in place. # for ( my $i = 0 ; $i < @$root ; $i++ ) { $root->[$i] = &$value($root->[$i], @$args); ## @result } } elsif ($item =~ /^-?\d+$/) { $value = $root->[$item]; ($ret, $retVal, @result) = _dotop_return( $value, $args, $returnRef, $scalarContext ); return $retVal if ( $ret ); ## RETURN } elsif (ref $item eq 'ARRAY' ) { # array slice return [@$root[@$item]]; ## RETURN } } # NOTE: we do the can-can because UNIVSERAL::isa($something, 'UNIVERSAL') # doesn't appear to work with CGI, returning true for the first call # and false for all subsequent calls. elsif (ref($root) && UNIVERSAL::can($root, 'can')) { # if $root is a blessed reference (i.e. inherits from the # UNIVERSAL object base class) then we call the item as a method. # If that fails then we try to fallback on HASH behaviour if # possible. return ref $root->can($item) if ( $returnRef ); ## RETURN eval { @result = $scalarContext ? scalar $root->$item(@$args) : $root->$item(@$args); ## @result }; if ($@) { # failed to call object method, so try some fallbacks if (UNIVERSAL::isa($root, 'HASH') && defined($value = $root->{ $item })) { ($ret, $retVal, @result) = _dotop_return( $value, $args, $returnRef, $scalarContext ); return $retVal if ( $ret ); ## RETURN } elsif (UNIVERSAL::isa($root, 'ARRAY') && ($value = $LIST_OPS->{ $item })) { @result = &$value($root, @$args); } else { @result = (undef, $@); } } } elsif (($value = $SCALAR_OPS->{ $item }) && ! $lvalue) { # at this point, it doesn't look like we've got a reference to # anything we know about, so we try the SCALAR_OPS pseudo-methods # table (but not for l-values) @result = &$value($root, @$args); ## @result } elsif ($self->{ _DEBUG }) { die "don't know how to access [ $root ].$item\n"; ## DIE } else { @result = (); } # fold multiple return items into a list unless first item is undef if (defined $result[0]) { return ref(@result > 1 ? [ @result ] : $result[0] ) if ( $returnRef ); ## RETURN if ( $scalarContext ) { return scalar @result if ( @result > 1 ); ## RETURN return scalar(@{$result[0]}) if ( ref $result[0] eq "ARRAY" ); return scalar(%{$result[0]}) if ( ref $result[0] eq "HASH" ); return $result[0]; ## RETURN } else { return @result > 1 ? [ @result ] : $result[0]; ## RETURN } } elsif (defined $result[1]) { die $result[1]; ## DIE } elsif ($self->{ _DEBUG }) { die "$item is undefined\n"; ## DIE } return undef; } #------------------------------------------------------------------------ # ($ret, $retVal, @result) = _dotop_return($value, $args, $returnRef, # $scalarContext); # # Handle the various return processing for _dotop #------------------------------------------------------------------------ sub _dotop_return { my($value, $args, $returnRef, $scalarContext) = @_; my(@result); return (1, ref $value) if ( $returnRef ); ## RETURN if ( $scalarContext ) { return (1, scalar(@$value)) if ref $value eq 'ARRAY'; ## RETURN return (1, scalar(%$value)) if ref $value eq 'HASH'; ## RETURN return (1, scalar($value)) unless ref $value eq 'CODE'; ## RETURN; @result = scalar &$value(@$args) ## @result; } else { return (1, $value) unless ref $value eq 'CODE'; ## RETURN @result = &$value(@$args); ## @result } return (0, undef, @result); } #------------------------------------------------------------------------ # _assign($root, $item, \@args, $value, $default) # # Similar to _dotop() above, but assigns a value to the given variable # instead of simply returning it. The first three parameters are the # root item, the item and arguments, as per _dotop(), followed by the # value to which the variable should be set and an optional $default # flag. If set true, the variable will only be set if currently false # (undefined/zero) #------------------------------------------------------------------------ sub _assign { my ($self, $root, $item, $args, $value, $default) = @_; my $rootref = ref $root; my $result; $args ||= [ ]; $default ||= 0; # print(STDERR "_assign(root=$root, item=$item, args=[@$args], \n", # "value=$value, default=$default)\n") # if $DEBUG; # return undef without an error if either side of the dot is unviable # or if an attempt is made to update a private member, starting _ or . return undef ## RETURN unless $root and defined $item and $item !~ /^[\._]/; if ($rootref eq 'HASH' || $rootref eq $self->{_CLASS}) { # if the root is a hash we set the named key return ($root->{ $item } = $value) ## RETURN unless $default && $root->{ $item }; } elsif ($rootref eq 'ARRAY' && $item =~ /^-?\d+$/) { # or set a list item by index number return ($root->[$item] = $value) ## RETURN unless $default && $root->{ $item }; } elsif (UNIVERSAL::isa($root, 'UNIVERSAL')) { # try to call the item as a method of an object return $root->$item(@$args, $value); ## RETURN } else { die "don't know how to assign to [$root].[$item]\n"; ## DIE } return undef; } 1; __END__ =head1 NAME Template::Stash::Context - Experimetal stash allowing list/scalar context definition =head1 SYNOPSIS use Template; use Template::Stash::Context; my $stash = Template::Stash::Context->new(\%vars); my $tt2 = Template->new({ STASH => $stash }); =head1 DESCRIPTION This is an alternate stash object which includes a patch from Craig Barratt to implement various new virtual methods to allow dotted template variable to denote if object methods and subroutines should be called in scalar or list context. It adds a little overhead to each stash call and I'm a little wary of applying that to the core default stash without investigating the effects first. So for now, it's implemented as a separate stash module which will allow us to test it out, benchmark it and switch it in or out as we require. This is what Craig has to say about it: Here's a better set of features for the core. Attached is a new version of Stash.pm (based on TT2.02) that: * supports the special op "scalar" that forces scalar context on function calls, eg: cgi.param("foo").scalar calls cgi.param("foo") in scalar context (unlike my wimpy scalar op from last night). Array context is the default. With non-function operands, scalar behaves like the perl version (eg: no-op for scalar, size for arrays, etc). * supports the special op "ref" that behaves like the perl ref. If applied to a function the function is not called. Eg: cgi.param("foo").ref does *not* call cgi.param and evaluates to "CODE". Similarly, HASH.ref, ARRAY.ref return what you expect. * adds a new scalar and list op called "array" that is a no-op for arrays and promotes scalars to one-element arrays. * allows scalar ops to be applied to arrays and hashes in place, eg: ARRAY.repeat(3) repeats each element in place. * allows list ops to be applied to scalars by promoting the scalars to one-element arrays (like an implicit "array"). So you can do things like SCALAR.size, SCALAR.join and get a useful result. This also means you can now use x.0 to safely get the first element whether x is an array or scalar. The new Stash.pm passes the TT2.02 test suite. But I haven't tested the new features very much. One nagging implementation problem is that the "scalar" and "ref" ops have higher precedence than user variable names. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/|http://wardley.org/> =head1 VERSION 1.63, distributed as part of the Template Toolkit version 3.100, released on 30 March 2020. =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Stash|Template::Stash> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�&fL�� �� lib/Template/Context.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Context # # DESCRIPTION # Module defining a context in which a template document is processed. # This is the runtime processing interface through which templates # can access the functionality of the Template Toolkit. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Context; use strict; use warnings; use base 'Template::Base'; use Template::Base; use Template::Config; use Template::Constants; use Template::Exception; use Scalar::Util 'blessed'; use constant DOCUMENT => 'Template::Document'; use constant EXCEPTION => 'Template::Exception'; use constant BADGER_EXCEPTION => 'Badger::Exception'; use constant MSWin32 => $^O eq 'MSWin32'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $DEBUG_FORMAT = "\n## \$file line \$line : [% \$text %] ##\n"; our $VIEW_CLASS = 'Template::View'; our $AUTOLOAD; #======================================================================== # ----- PUBLIC METHODS ----- #======================================================================== #------------------------------------------------------------------------ # template($name) # # General purpose method to fetch a template and return it in compiled # form. In the usual case, the $name parameter will be a simple string # containing the name of a template (e.g. 'header'). It may also be # a reference to Template::Document object (or sub-class) or a Perl # sub-routine. These are considered to be compiled templates and are # returned intact. Finally, it may be a reference to any other kind # of valid input source accepted by Template::Provider (e.g. scalar # ref, glob, IO handle, etc). # # Templates may be cached at one of 3 different levels. The internal # BLOCKS member is a local cache which holds references to all # template blocks used or imported via PROCESS since the context's # reset() method was last called. This is checked first and if the # template is not found, the method then walks down the BLOCKSTACK # list. This contains references to the block definition tables in # any enclosing Template::Documents that we're visiting (e.g. we've # been called via an INCLUDE and we want to access a BLOCK defined in # the template that INCLUDE'd us). If nothing is defined, then we # iterate through the LOAD_TEMPLATES providers list as a 'chain of # responsibility' (see Design Patterns) asking each object to fetch() # the template if it can. # # Returns the compiled template. On error, undef is returned and # the internal ERROR value (read via error()) is set to contain an # error message of the form "$name: $error". #------------------------------------------------------------------------ sub template { my ($self, $name) = @_; my ($prefix, $blocks, $defblocks, $provider, $template, $error); my ($shortname, $blockname, $providers); $self->debug("template($name)") if $self->{ DEBUG }; # references to Template::Document (or sub-class) objects, or # CODE references are assumed to be pre-compiled templates and are # returned intact return $name if (blessed($name) && $name->isa(DOCUMENT)) || ref($name) eq 'CODE'; $shortname = $name; unless (ref $name) { $self->debug("looking for block [$name]") if $self->{ DEBUG }; # we first look in the BLOCKS hash for a BLOCK that may have # been imported from a template (via PROCESS) return $template if ($template = $self->{ BLOCKS }->{ $name }); # then we iterate through the BLKSTACK list to see if any of the # Template::Documents we're visiting define this BLOCK foreach $blocks (@{ $self->{ BLKSTACK } }) { return $template if $blocks && ($template = $blocks->{ $name }); } # now it's time to ask the providers, so we look to see if any # prefix is specified to indicate the desired provider set. if (MSWin32) { # let C:/foo through $prefix = $1 if $shortname =~ s/^(\w{2,})://o; } else { $prefix = $1 if $shortname =~ s/^(\w+)://; } if (defined $prefix) { $providers = $self->{ PREFIX_MAP }->{ $prefix } || return $self->throw( Template::Constants::ERROR_FILE, "no providers for template prefix '$prefix'"); } } $providers = $self->{ PREFIX_MAP }->{ default } || $self->{ LOAD_TEMPLATES } unless $providers; # Finally we try the regular template providers which will # handle references to files, text, etc., as well as templates # reference by name. If $blockname = ''; while ($shortname) { $self->debug("asking providers for [$shortname] [$blockname]") if $self->{ DEBUG }; foreach my $provider (@$providers) { ($template, $error) = $provider->fetch($shortname, $prefix); if ($error) { if ($error == Template::Constants::STATUS_ERROR) { # $template contains exception object if (blessed($template) && $template->isa(EXCEPTION) && $template->type eq Template::Constants::ERROR_FILE) { $self->throw($template); } else { $self->throw( Template::Constants::ERROR_FILE, $template ); } } # DECLINE is ok, carry on } elsif (length $blockname) { return $template if $template = $template->blocks->{ $blockname }; } else { return $template; } } last if ref $shortname || ! $self->{ EXPOSE_BLOCKS }; $shortname =~ s{/([^/]+)$}{} || last; $blockname = length $blockname ? "$1/$blockname" : $1; } $self->throw(Template::Constants::ERROR_FILE, "$name: not found"); } #------------------------------------------------------------------------ # plugin($name, \@args) # # Calls on each of the LOAD_PLUGINS providers in turn to fetch() (i.e. load # and instantiate) a plugin of the specified name. Additional parameters # passed are propagated to the new() constructor for the plugin. # Returns a reference to a new plugin object or other reference. On # error, undef is returned and the appropriate error message is set for # subsequent retrieval via error(). #------------------------------------------------------------------------ sub plugin { my ($self, $name, $args) = @_; my ($provider, $plugin, $error); $self->debug("plugin($name, ", defined $args ? @$args : '[ ]', ')') if $self->{ DEBUG }; # request the named plugin from each of the LOAD_PLUGINS providers in turn foreach my $provider (@{ $self->{ LOAD_PLUGINS } }) { ($plugin, $error) = $provider->fetch($name, $args, $self); return $plugin unless $error; if ($error == Template::Constants::STATUS_ERROR) { $self->throw($plugin) if ref $plugin; $self->throw(Template::Constants::ERROR_PLUGIN, $plugin); } } $self->throw(Template::Constants::ERROR_PLUGIN, "$name: plugin not found"); } #------------------------------------------------------------------------ # filter($name, \@args, $alias) # # Similar to plugin() above, but querying the LOAD_FILTERS providers to # return filter instances. An alias may be provided which is used to # save the returned filter in a local cache. #------------------------------------------------------------------------ sub filter { my ($self, $name, $args, $alias) = @_; my ($provider, $filter, $error); $self->debug("filter($name, ", defined $args ? @$args : '[ ]', defined $alias ? $alias : '<no alias>', ')') if $self->{ DEBUG }; # use any cached version of the filter if no params provided return $filter if ! $args && ! ref $name && ($filter = $self->{ FILTER_CACHE }->{ $name }); # request the named filter from each of the FILTERS providers in turn foreach my $provider (@{ $self->{ LOAD_FILTERS } }) { ($filter, $error) = $provider->fetch($name, $args, $self); last unless $error; if ($error == Template::Constants::STATUS_ERROR) { $self->throw($filter) if ref $filter; $self->throw(Template::Constants::ERROR_FILTER, $filter); } # return $self->error($filter) # if $error == &Template::Constants::STATUS_ERROR; } return $self->error("$name: filter not found") unless $filter; # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - # commented out by abw on 19 Nov 2001 to fix problem with xmlstyle # plugin which may re-define a filter by calling define_filter() # multiple times. With the automatic aliasing/caching below, any # new filter definition isn't seen. Don't think this will cause # any problems as filters explicitly supplied with aliases will # still work as expected. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - # alias defaults to name if undefined # $alias = $name # unless defined($alias) or ref($name) or $args; # cache FILTER if alias is valid $self->{ FILTER_CACHE }->{ $alias } = $filter if $alias; return $filter; } #------------------------------------------------------------------------ # view(\%config) # # Create a new Template::View bound to this context. #------------------------------------------------------------------------ sub view { my $self = shift; require Template::View; return $VIEW_CLASS->new($self, @_) || $self->throw( &Template::Constants::ERROR_VIEW, $VIEW_CLASS->error ); } #------------------------------------------------------------------------ # process($template, \%params) [% PROCESS template var=val ... %] # process($template, \%params, $local) [% INCLUDE template var=val ... %] # # Processes the template named or referenced by the first parameter. # The optional second parameter may reference a hash array of variable # definitions. These are set before the template is processed by # calling update() on the stash. Note that, unless the third parameter # is true, the context is not localised and these, and any other # variables set in the template will retain their new values after this # method returns. The third parameter is in place so that this method # can handle INCLUDE calls: the stash will be localized. # # Returns the output of processing the template. Errors are thrown # as Template::Exception objects via die(). #------------------------------------------------------------------------ sub process { my ($self, $template, $params, $localize) = @_; my ($trim, $blocks) = @$self{ qw( TRIM BLOCKS ) }; my (@compiled, $name, $compiled); my ($stash, $component, $tblocks, $error, $tmpout); my $output = ''; $template = [ $template ] unless ref $template eq 'ARRAY'; $self->debug("process([ ", join(', '), @$template, ' ], ', defined $params ? $params : '<no params>', ', ', $localize ? '<localized>' : '<unlocalized>', ')') if $self->{ DEBUG }; # fetch compiled template for each name specified foreach $name (@$template) { push(@compiled, $self->template($name)); } if ($localize) { # localise the variable stash with any parameters passed $stash = $self->{ STASH } = $self->{ STASH }->clone($params); } else { # update stash with any new parameters passed $self->{ STASH }->update($params); $stash = $self->{ STASH }; } eval { # save current component eval { $component = $stash->get('component') }; foreach $name (@$template) { $compiled = shift @compiled; my $element = ref $compiled eq 'CODE' ? { (name => (ref $name ? '' : $name), modtime => time()) } : $compiled; if (blessed($component) && $component->isa(DOCUMENT)) { $element->{ caller } = $component->{ name }; $element->{ callers } = $component->{ callers } || []; push(@{$element->{ callers }}, $element->{ caller }); } $stash->set('component', $element); unless ($localize) { # merge any local blocks defined in the Template::Document # into our local BLOCKS cache @$blocks{ keys %$tblocks } = values %$tblocks if (blessed($compiled) && $compiled->isa(DOCUMENT)) && ($tblocks = $compiled->blocks); } if (ref $compiled eq 'CODE') { $tmpout = &$compiled($self); } elsif (ref $compiled) { $tmpout = $compiled->process($self); } else { $self->throw( 'file', "invalid template reference: $compiled" ); } if ($trim) { for ($tmpout) { s/^\s+//; s/\s+$//; } } $output .= $tmpout; # pop last item from callers. # NOTE - this will not be called if template throws an # error. The whole issue of caller and callers should be # revisited to try and avoid putting this info directly into # the component data structure. Perhaps use a local element # instead? pop(@{$element->{ callers }}) if (blessed($component) && $component->isa(DOCUMENT)); } $stash->set('component', $component); }; $error = $@; if ($localize) { # ensure stash is delocalised before dying $self->{ STASH } = $self->{ STASH }->declone(); } $self->throw( ref $error ? $error : (Template::Constants::ERROR_FILE, $error) ) if $error; return $output; } #------------------------------------------------------------------------ # include($template, \%params) [% INCLUDE template var = val, ... %] # # Similar to process() above but processing the template in a local # context. Any variables passed by reference to a hash as the second # parameter will be set before the template is processed and then # revert to their original values before the method returns. Similarly, # any changes made to non-global variables within the template will # persist only until the template is processed. # # Returns the output of processing the template. Errors are thrown # as Template::Exception objects via die(). #------------------------------------------------------------------------ sub include { my ($self, $template, $params) = @_; return $self->process($template, $params, 'localize me!'); } #------------------------------------------------------------------------ # insert($file) # # Insert the contents of a file without parsing. #------------------------------------------------------------------------ sub insert { my ($self, $file) = @_; my ($prefix, $providers, $text, $error); my $output = ''; my $files = ref $file eq 'ARRAY' ? $file : [ $file ]; $self->debug("insert([ ", join(', '), @$files, " ])") if $self->{ DEBUG }; FILE: foreach $file (@$files) { my $name = $file; if (MSWin32) { # let C:/foo through $prefix = $1 if $name =~ s/^(\w{2,})://o; } else { $prefix = $1 if $name =~ s/^(\w+)://; } if (defined $prefix) { $providers = $self->{ PREFIX_MAP }->{ $prefix } || return $self->throw( Template::Constants::ERROR_FILE, "no providers for file prefix '$prefix'" ); } else { $providers = $self->{ PREFIX_MAP }->{ default } || $self->{ LOAD_TEMPLATES }; } foreach my $provider (@$providers) { ($text, $error) = $provider->load($name, $prefix); next FILE unless $error; if ($error == Template::Constants::STATUS_ERROR) { $self->throw($text) if ref $text; $self->throw(Template::Constants::ERROR_FILE, $text); } } $self->throw(Template::Constants::ERROR_FILE, "$file: not found"); } continue { $output .= $text; } return $output; } #------------------------------------------------------------------------ # throw($type, $info, \$output) [% THROW errtype "Error info" %] # # Throws a Template::Exception object by calling die(). This method # may be passed a reference to an existing Template::Exception object; # a single value containing an error message which is used to # instantiate a Template::Exception of type 'undef'; or a pair of # values representing the exception type and info from which a # Template::Exception object is instantiated. e.g. # # $context->throw($exception); # $context->throw("I'm sorry Dave, I can't do that"); # $context->throw('denied', "I'm sorry Dave, I can't do that"); # # An optional third parameter can be supplied in the last case which # is a reference to the current output buffer containing the results # of processing the template up to the point at which the exception # was thrown. The RETURN and STOP directives, for example, use this # to propagate output back to the user, but it can safely be ignored # in most cases. # # This method rides on a one-way ticket to die() oblivion. It does not # return in any real sense of the word, but should get caught by a # surrounding eval { } block (e.g. a BLOCK or TRY) and handled # accordingly, or returned to the caller as an uncaught exception. #------------------------------------------------------------------------ sub throw { my ($self, $error, $info, $output) = @_; local $" = ', '; # die! die! die! if (blessed($error) && $error->isa(EXCEPTION)) { die $error; } elsif (blessed($error) && $error->isa(BADGER_EXCEPTION)) { # convert a Badger::Exception to a Template::Exception so that # things continue to work during the transition to Badger die EXCEPTION->new($error->type, $error->info); } elsif (defined $info) { die (EXCEPTION->new($error, $info, $output)); } else { $error ||= ''; die (EXCEPTION->new('undef', $error, $output)); } # not reached } #------------------------------------------------------------------------ # catch($error, \$output) # # Called by various directives after catching an error thrown via die() # from within an eval { } block. The first parameter contains the error # which may be a sanitized reference to a Template::Exception object # (such as that raised by the throw() method above, a plugin object, # and so on) or an error message thrown via die from somewhere in user # code. The latter are coerced into 'undef' Template::Exception objects. # Like throw() above, a reference to a scalar may be passed as an # additional parameter to represent the current output buffer # localised within the eval block. As exceptions are thrown upwards # and outwards from nested blocks, the catch() method reconstructs the # correct output buffer from these fragments, storing it in the # exception object for passing further onwards and upwards. # # Returns a reference to a Template::Exception object.. #------------------------------------------------------------------------ sub catch { my ($self, $error, $output) = @_; if ( blessed($error) && ( $error->isa(EXCEPTION) || $error->isa(BADGER_EXCEPTION) ) ) { $error->text($output) if $output; return $error; } else { return EXCEPTION->new('undef', $error, $output); } } #------------------------------------------------------------------------ # localise(\%params) # delocalise() # # The localise() method creates a local copy of the current stash, # allowing the existing state of variables to be saved and later # restored via delocalise(). # # A reference to a hash array may be passed containing local variable # definitions which should be added to the cloned namespace. These # values persist until delocalisation. #------------------------------------------------------------------------ sub localise { my $self = shift; $self->{ STASH } = $self->{ STASH }->clone(@_); } sub delocalise { my $self = shift; $self->{ STASH } = $self->{ STASH }->declone(); } #------------------------------------------------------------------------ # visit($document, $blocks) # # Each Template::Document calls the visit() method on the context # before processing itself. It passes a reference to the hash array # of named BLOCKs defined within the document, allowing them to be # added to the internal BLKSTACK list which is subsequently used by # template() to resolve templates. # from a provider. #------------------------------------------------------------------------ sub visit { my ($self, $document, $blocks) = @_; unshift(@{ $self->{ BLKSTACK } }, $blocks) } #------------------------------------------------------------------------ # leave() # # The leave() method is called when the document has finished # processing itself. This removes the entry from the BLKSTACK list # that was added visit() above. For persistence of BLOCK definitions, # the process() method (i.e. the PROCESS directive) does some extra # magic to copy BLOCKs into a shared hash. #------------------------------------------------------------------------ sub leave { my $self = shift; shift(@{ $self->{ BLKSTACK } }); } #------------------------------------------------------------------------ # define_block($name, $block) # # Adds a new BLOCK definition to the local BLOCKS cache. $block may # be specified as a reference to a sub-routine or Template::Document # object or as text which is compiled into a template. Returns a true # value (the $block reference or compiled block reference) if # successful or undef on failure. Call error() to retrieve the # relevant error message (i.e. compilation failure). #------------------------------------------------------------------------ sub define_block { my ($self, $name, $block) = @_; $block = $self->template(\$block) || return undef unless ref $block; $self->{ BLOCKS }->{ $name } = $block; } #------------------------------------------------------------------------ # define_filter($name, $filter, $is_dynamic) # # Adds a new FILTER definition to the local FILTER_CACHE. #------------------------------------------------------------------------ sub define_filter { my ($self, $name, $filter, $is_dynamic) = @_; my ($result, $error); $filter = [ $filter, 1 ] if $is_dynamic; foreach my $provider (@{ $self->{ LOAD_FILTERS } }) { ($result, $error) = $provider->store($name, $filter); return 1 unless $error; $self->throw(&Template::Constants::ERROR_FILTER, $result) if $error == &Template::Constants::STATUS_ERROR; } $self->throw( &Template::Constants::ERROR_FILTER, "FILTER providers declined to store filter $name" ); } #------------------------------------------------------------------------ # define_vmethod($type, $name, \&sub) # # Passes $type, $name, and &sub on to stash->define_vmethod(). #------------------------------------------------------------------------ sub define_vmethod { my $self = shift; $self->stash->define_vmethod(@_); } #------------------------------------------------------------------------ # define_view($name, $params) # # Defines a new view. #------------------------------------------------------------------------ sub define_view { my ($self, $name, $params) = @_; my $base; if (defined $params->{ base }) { my $base = $self->{ STASH }->get($params->{ base }); return $self->throw( &Template::Constants::ERROR_VIEW, "view base is not defined: $params->{ base }" ) unless $base; return $self->throw( &Template::Constants::ERROR_VIEW, "view base is not a $VIEW_CLASS object: $params->{ base } => $base" ) unless blessed($base) && $base->isa($VIEW_CLASS); $params->{ base } = $base; } my $view = $self->view($params); $view->seal(); $self->{ STASH }->set($name, $view); } #------------------------------------------------------------------------ # define_views($views) # # Defines multiple new views. #------------------------------------------------------------------------ sub define_views { my ($self, $views) = @_; # a list reference is better because the order is deterministic (and so # allows an earlier VIEW to be the base for a later VIEW), but we'll # accept a hash reference and assume that the user knows the order of # processing is undefined $views = [ %$views ] if ref $views eq 'HASH'; # make of copy so we don't destroy the original list reference my @items = @$views; my ($name, $view); while (@items) { $self->define_view(splice(@items, 0, 2)); } } #------------------------------------------------------------------------ # reset() # # Reset the state of the internal BLOCKS hash to clear any BLOCK # definitions imported via the PROCESS directive. Any original # BLOCKS definitions passed to the constructor will be restored. #------------------------------------------------------------------------ sub reset { my ($self, $blocks) = @_; $self->{ BLKSTACK } = [ ]; $self->{ BLOCKS } = { %{ $self->{ INIT_BLOCKS } } }; } #------------------------------------------------------------------------ # stash() # # Simple accessor methods to return the STASH values. This is likely # to be called quite often so we provide a direct method rather than # relying on the slower AUTOLOAD. #------------------------------------------------------------------------ sub stash { return $_[0]->{ STASH }; } #------------------------------------------------------------------------ # debugging($command, @args, \%params) # # Method for controlling the debugging status of the context. The first # argument can be 'on' or 'off' to enable/disable debugging, 'format' # to define the format of the debug message, or 'msg' to generate a # debugging message reporting the file, line, message text, etc., # according to the current debug format. #------------------------------------------------------------------------ sub debugging { my $self = shift; my $hash = ref $_[-1] eq 'HASH' ? pop : { }; my @args = @_; if (@args) { if ($args[0] eq '1' || lc($args[0]) eq 'on' ) { $self->{ DEBUG_DIRS } = 1; shift(@args); } elsif ($args[0] eq '0' || lc($args[0]) eq 'off') { $self->{ DEBUG_DIRS } = 0; shift(@args); } } if (@args) { if (lc($args[0]) eq 'msg') { return unless $self->{ DEBUG_DIRS }; my $format = $self->{ DEBUG_FORMAT }; $format = $DEBUG_FORMAT unless defined $format; $format =~ s/\$(\w+)/$hash->{ $1 }/ge; return $format; } elsif ( lc($args[0]) eq 'format' ) { $self->{ DEBUG_FORMAT } = $args[1]; } # else ignore } return ''; } #------------------------------------------------------------------------ # AUTOLOAD # # Provides pseudo-methods for read-only access to various internal # members. For example, templates(), plugins(), filters(), # eval_perl(), load_perl(), etc. These aren't called very often, or # may never be called at all. #------------------------------------------------------------------------ sub AUTOLOAD { my $self = shift; my $method = $AUTOLOAD; my $result; $method =~ s/.*:://; return if $method eq 'DESTROY'; warn "no such context method/member: $method\n" unless defined ($result = $self->{ uc $method }); return $result; } #------------------------------------------------------------------------ # DESTROY # # Stash may contain references back to the Context via macro closures, # etc. This breaks the circular references. #------------------------------------------------------------------------ sub DESTROY { my $self = shift; undef $self->{ STASH }; } #======================================================================== # -- PRIVATE METHODS -- #======================================================================== #------------------------------------------------------------------------ # _init(\%config) # # Initialisation method called by Template::Base::new() #------------------------------------------------------------------------ sub _init { my ($self, $config) = @_; my ($name, $item, $method, $block, $blocks); my @itemlut = ( LOAD_TEMPLATES => 'provider', LOAD_PLUGINS => 'plugins', LOAD_FILTERS => 'filters' ); # LOAD_TEMPLATE, LOAD_PLUGINS, LOAD_FILTERS - lists of providers while (($name, $method) = splice(@itemlut, 0, 2)) { $item = $config->{ $name } || Template::Config->$method($config) || return $self->error($Template::Config::ERROR); $self->{ $name } = ref $item eq 'ARRAY' ? $item : [ $item ]; } my $providers = $self->{ LOAD_TEMPLATES }; my $prefix_map = $self->{ PREFIX_MAP } = $config->{ PREFIX_MAP } || { }; while (my ($key, $val) = each %$prefix_map) { $prefix_map->{ $key } = [ ref $val ? $val : map { $providers->[$_] } split(/\D+/, $val) ] unless ref $val eq 'ARRAY'; } # STASH $self->{ STASH } = $config->{ STASH } || do { my $predefs = $config->{ VARIABLES } || $config->{ PRE_DEFINE } || { }; # hack to get stash to know about debug mode $predefs->{ _DEBUG } = ( ($config->{ DEBUG } || 0) & &Template::Constants::DEBUG_UNDEF ) ? 1 : 0 unless defined $predefs->{ _DEBUG }; $predefs->{ _STRICT } = $config->{ STRICT }; Template::Config->stash($predefs) || return $self->error($Template::Config::ERROR); }; # compile any template BLOCKS specified as text $blocks = $config->{ BLOCKS } || { }; $self->{ INIT_BLOCKS } = $self->{ BLOCKS } = { map { $block = $blocks->{ $_ }; $block = $self->template(\$block) || return undef unless ref $block; ($_ => $block); } keys %$blocks }; # define any VIEWS $self->define_views( $config->{ VIEWS } ) if $config->{ VIEWS }; # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - # RECURSION - flag indicating is recursion into templates is supported # EVAL_PERL - flag indicating if PERL blocks should be processed # TRIM - flag to remove leading and trailing whitespace from output # BLKSTACK - list of hashes of BLOCKs defined in current template(s) # CONFIG - original configuration hash # EXPOSE_BLOCKS - make blocks visible as pseudo-files # DEBUG_FORMAT - format for generating template runtime debugging messages # DEBUG - format for generating template runtime debugging messages $self->{ RECURSION } = $config->{ RECURSION } || 0; $self->{ EVAL_PERL } = $config->{ EVAL_PERL } || 0; $self->{ TRIM } = $config->{ TRIM } || 0; $self->{ BLKSTACK } = [ ]; $self->{ CONFIG } = $config; $self->{ EXPOSE_BLOCKS } = defined $config->{ EXPOSE_BLOCKS } ? $config->{ EXPOSE_BLOCKS } : 0; $self->{ DEBUG_FORMAT } = $config->{ DEBUG_FORMAT }; $self->{ DEBUG_DIRS } = ($config->{ DEBUG } || 0) & Template::Constants::DEBUG_DIRS; $self->{ DEBUG } = defined $config->{ DEBUG } ? $config->{ DEBUG } & ( Template::Constants::DEBUG_CONTEXT | Template::Constants::DEBUG_FLAGS ) : $DEBUG; return $self; } 1; __END__ =head1 NAME Template::Context - Runtime context in which templates are processed =head1 SYNOPSIS use Template::Context; # constructor $context = Template::Context->new(\%config) || die $Template::Context::ERROR; # fetch (load and compile) a template $template = $context->template($template_name); # fetch (load and instantiate) a plugin object $plugin = $context->plugin($name, \@args); # fetch (return or create) a filter subroutine $filter = $context->filter($name, \@args, $alias); # process/include a template, errors are thrown via die() $output = $context->process($template, \%vars); $output = $context->include($template, \%vars); # raise an exception via die() $context->throw($error_type, $error_message, \$output_buffer); # catch an exception, clean it up and fix output buffer $exception = $context->catch($exception, \$output_buffer); # save/restore the stash to effect variable localisation $new_stash = $context->localise(\%vars); $old_stash = $context->delocalise(); # add new BLOCK or FILTER definitions $context->define_block($name, $block); $context->define_filter($name, \&filtersub, $is_dynamic); # reset context, clearing any imported BLOCK definitions $context->reset(); # methods for accessing internal items $stash = $context->stash(); $tflag = $context->trim(); $epflag = $context->eval_perl(); $providers = $context->templates(); $providers = $context->plugins(); $providers = $context->filters(); ... =head1 DESCRIPTION The C<Template::Context> module defines an object class for representing a runtime context in which templates are processed. It provides an interface to the fundamental operations of the Template Toolkit processing engine through which compiled templates (i.e. Perl code constructed from the template source) can process templates, load plugins and filters, raise exceptions and so on. A default C<Template::Context> object is created by the L<Template> module. Any C<Template::Context> options may be passed to the L<Template> L<new()|Template#new()> constructor method and will be forwarded to the C<Template::Context> constructor. use Template; my $template = Template->new({ TRIM => 1, EVAL_PERL => 1, BLOCKS => { header => 'This is the header', footer => 'This is the footer', }, }); Similarly, the C<Template::Context> constructor will forward all configuration parameters onto other default objects (e.g. L<Template::Provider>, L<Template::Plugins>, L<Template::Filters>, etc.) that it may need to instantiate. $context = Template::Context->new({ INCLUDE_PATH => '/home/abw/templates', # provider option TAG_STYLE => 'html', # parser option }); A C<Template::Context> object (or subclass) can be explicitly instantiated and passed to the L<Template> L<new()|Template#new()> constructor method as the C<CONTEXT> configuration item. use Template; use Template::Context; my $context = Template::Context->new({ TRIM => 1 }); my $template = Template->new({ CONTEXT => $context }); The L<Template> module uses the L<Template::Config> L<context()|Template::Config#context()> factory method to create a default context object when required. The C<$Template::Config::CONTEXT> package variable may be set to specify an alternate context module. This will be loaded automatically and its L<new()> constructor method called by the L<context()|Template::Config#context()> factory method when a default context object is required. use Template; $Template::Config::CONTEXT = 'MyOrg::Template::Context'; my $template = Template->new({ EVAL_PERL => 1, EXTRA_MAGIC => 'red hot', # your extra config items ... }); =head1 METHODS =head2 new(\%params) The C<new()> constructor method is called to instantiate a C<Template::Context> object. Configuration parameters may be specified as a HASH reference or as a list of C<name =E<gt> value> pairs. my $context = Template::Context->new({ INCLUDE_PATH => 'header', POST_PROCESS => 'footer', }); my $context = Template::Context->new( EVAL_PERL => 1 ); The C<new()> method returns a C<Template::Context> object or C<undef> on error. In the latter case, a relevant error message can be retrieved by the L<error()|Template::Base#error()> class method or directly from the C<$Template::Context::ERROR> package variable. my $context = Template::Context->new(\%config) || die Template::Context->error(); my $context = Template::Context->new(\%config) || die $Template::Context::ERROR; The following configuration items may be specified. Please see L<Template::Manual::Config> for further details. =head3 VARIABLES The L<VARIABLES|Template::Manual::Config#VARIABLES> option can be used to specify a hash array of template variables. my $context = Template::Context->new({ VARIABLES => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; =head3 BLOCKS The L<BLOCKS|Template::Manual::Config#BLOCKS> option can be used to pre-define a default set of template blocks. my $context = Template::Context->new({ BLOCKS => { header => 'The Header. [% title %]', footer => sub { return $some_output_text }, another => Template::Document->new({ ... }), }, }); =head3 VIEWS The L<VIEWS|Template::Manual::Config#VIEWS> option can be used to pre-define one or more L<Template::View> objects. my $context = Template::Context->new({ VIEWS => [ bottom => { prefix => 'bottom/' }, middle => { prefix => 'middle/', base => 'bottom' }, top => { prefix => 'top/', base => 'middle' }, ], }); =head3 TRIM The L<TRIM|Template::Manual::Config#TRIM> option can be set to have any leading and trailing whitespace automatically removed from the output of all template files and C<BLOCK>s. example: [% BLOCK foo %] Line 1 of foo [% END %] before [% INCLUDE foo %] after output: before Line 1 of foo after =head3 EVAL_PERL The L<EVAL_PERL|Template::Manual::Config#EVAL_PERL> is used to indicate if C<PERL> and/or C<RAWPERL> blocks should be evaluated. It is disabled by default. =head3 RECURSION The L<RECURSION|Template::Manual::Config#RECURSION> can be set to allow templates to recursively process themselves, either directly (e.g. template C<foo> calls C<INCLUDE foo>) or indirectly (e.g. C<foo> calls C<INCLUDE bar> which calls C<INCLUDE foo>). =head3 LOAD_TEMPLATES The L<LOAD_TEMPLATES|Template::Manual::Config#LOAD_TEMPLATES> option can be used to provide a reference to a list of L<Template::Provider> objects or sub-classes thereof which will take responsibility for loading and compiling templates. my $context = Template::Context->new({ LOAD_TEMPLATES => [ MyOrg::Template::Provider->new({ ... }), Template::Provider->new({ ... }), ], }); =head3 LOAD_PLUGINS The L<LOAD_PLUGINS|Template::Manual::Config#LOAD_PLUGINS> options can be used to specify a list of provider objects responsible for loading and instantiating template plugin objects. my $context = Template::Context->new({ LOAD_PLUGINS => [ MyOrg::Template::Plugins->new({ ... }), Template::Plugins->new({ ... }), ], }); =head3 LOAD_FILTERS The L<LOAD_FILTERS|Template::Manual::Config#LOAD_FILTERS> option can be used to specify a list of provider objects for returning and/or creating filter subroutines. my $context = Template::Context->new({ LOAD_FILTERS => [ MyTemplate::Filters->new(), Template::Filters->new(), ], }); =head3 STASH The L<STASH|Template::Manual::Config#STASH> option can be used to specify a L<Template::Stash> object or sub-class which will take responsibility for managing template variables. my $stash = MyOrg::Template::Stash->new({ ... }); my $context = Template::Context->new({ STASH => $stash, }); =head3 DEBUG The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable various debugging features of the L<Template::Context> module. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_CONTEXT | DEBUG_DIRS, }); =head2 template($name) Returns a compiled template by querying each of the L<LOAD_TEMPLATES> providers (instances of L<Template::Provider>, or sub-class) in turn. $template = $context->template('header'); On error, a L<Template::Exception> object of type 'C<file>' is thrown via C<die()>. This can be caught by enclosing the call to C<template()> in an C<eval> block and examining C<$@>. eval { $template = $context->template('header') }; if ($@) { print "failed to fetch template: $@\n"; } =head2 plugin($name, \@args) Instantiates a plugin object by querying each of the L<LOAD_PLUGINS> providers. The default L<LOAD_PLUGINS> provider is a L<Template::Plugins> object which attempts to load plugin modules, according the various configuration items such as L<PLUGIN_BASE|Template::Plugins#PLUGIN_BASE>, L<LOAD_PERL|Template::Plugins#LOAD_PERL>, etc., and then instantiate an object via L<new()|Template::Plugin#new()>. A reference to a list of constructor arguments may be passed as the second parameter. These are forwarded to the plugin constructor. Returns a reference to a plugin (which is generally an object, but doesn't have to be). Errors are thrown as L<Template::Exception> objects with the type set to 'C<plugin>'. $plugin = $context->plugin('DBI', 'dbi:msql:mydbname'); =head2 filter($name, \@args, $alias) Instantiates a filter subroutine by querying the L<LOAD_FILTERS> providers. The default L<LOAD_FILTERS> provider is a L<Template::Filters> object. Additional arguments may be passed by list reference along with an optional alias under which the filter will be cached for subsequent use. The filter is cached under its own C<$name> if C<$alias> is undefined. Subsequent calls to C<filter($name)> will return the cached entry, if defined. Specifying arguments bypasses the caching mechanism and always creates a new filter. Errors are thrown as L<Template::Exception> objects with the type set to 'C<filter>'. # static filter (no args) $filter = $context->filter('html'); # dynamic filter (args) aliased to 'padright' $filter = $context->filter('format', '%60s', 'padright'); # retrieve previous filter via 'padright' alias $filter = $context->filter('padright'); =head2 process($template, \%vars) Processes a template named or referenced by the first parameter and returns the output generated. An optional reference to a hash array may be passed as the second parameter, containing variable definitions which will be set before the template is processed. The template is processed in the current context, with no localisation of variables performed. Errors are thrown as L<Template::Exception> objects via C<die()>. $output = $context->process('header', { title => 'Hello World' }); =head2 include($template, \%vars) Similar to L<process()>, but using localised variables. Changes made to any variables will only persist until the C<include()> method completes. $output = $context->include('header', { title => 'Hello World' }); =head2 insert($template) This method returns the source content of a template file without performing any evaluation. It is used to implement the C<INSERT> directive. =head2 throw($error_type, $error_message, \$output) Raises an exception in the form of a L<Template::Exception> object by calling C<die()>. This method may be passed a reference to an existing L<Template::Exception> object; a single value containing an error message which is used to instantiate a L<Template::Exception> of type 'C<undef>'; or a pair of values representing the exception C<type> and C<info> from which a L<Template::Exception> object is instantiated. e.g. $context->throw($exception); $context->throw("I'm sorry Dave, I can't do that"); $context->throw('denied', "I'm sorry Dave, I can't do that"); The optional third parameter may be a reference to the current output buffer. This is then stored in the exception object when created, allowing the catcher to examine and use the output up to the point at which the exception was raised. $output .= 'blah blah blah'; $output .= 'more rhubarb'; $context->throw('yack', 'Too much yacking', \$output); =head2 catch($exception, \$output) Catches an exception thrown, either as a reference to a L<Template::Exception> object or some other value. In the latter case, the error string is promoted to a L<Template::Exception> object of 'C<undef>' type. This method also accepts a reference to the current output buffer which is passed to the L<Template::Exception> constructor, or is appended to the output buffer stored in an existing L<Template::Exception> object, if unique (i.e. not the same reference). By this process, the correct state of the output buffer can be reconstructed for simple or nested throws. =head2 define_block($name, $block) Adds a new block definition to the internal L<BLOCKS> cache. The first argument should contain the name of the block and the second a reference to a L<Template::Document> object or template sub-routine, or template text which is automatically compiled into a template sub-routine. Returns a true value (the sub-routine or L<Template::Document> reference) on success or undef on failure. The relevant error message can be retrieved by calling the L<error()|Template::Base#error()> method. =head2 define_filter($name, \&filter, $is_dynamic) Adds a new filter definition by calling the L<store()|Template::Filters#store()> method on each of the L<LOAD_FILTERS> providers until accepted (in the usual case, this is accepted straight away by the one and only L<Template::Filters> provider). The first argument should contain the name of the filter and the second a reference to a filter subroutine. The optional third argument can be set to any true value to indicate that the subroutine is a dynamic filter factory. Returns a true value or throws a 'C<filter>' exception on error. =head2 define_vmethod($type, $name, $code) This method is a wrapper around the L<Template::Stash> L<define_vmethod()|Template::Stash#define_vmethod()> method. It can be used to define new virtual methods. # define a new scalar (item) virtual method $context->define_vmethod( item => ucfirst => sub { my $text = shift; return ucfirst $text; } ) =head2 define_view($name, \%params) This method allows you to define a named L<view|Template::View>. $context->define_view( my_view => { prefix => 'my_templates/' } ); The view is then accessible as a template variable. [% my_view.print(some_data) %] =head2 define_views($views) This method allows you to define multiple named L<views|Template::View>. A reference to a hash array or list reference should be passed as an argument. $context->define_view({ # hash reference my_view_one => { prefix => 'my_templates_one/' }, my_view_two => { prefix => 'my_templates_two/' } }); If you're defining multiple views of which one or more are based on other views in the same definition then you should pass them as a list reference. This ensures that they get created in the right order (Perl does not preserve the order of items defined in a hash reference so you can't guarantee that your base class view will be defined before your subclass view). $context->define_view([ # list referenence my_view_one => { prefix => 'my_templates_one/' }, my_view_two => { prefix => 'my_templates_two/' , base => 'my_view_one', } ]); The views are then accessible as template variables. [% my_view_one.print(some_data) %] [% my_view_two.print(some_data) %] See also the L<VIEWS> option. =head2 stash() This method returns the L<Template::Stash> object used internally to manage template variables. =head2 localise(\%vars) Clones the stash to create a context with localised variables. Returns a reference to the newly cloned stash object which is also stored internally. $stash = $context->localise(); =head2 delocalise() Restore the stash to its state prior to localisation. $stash = $context->delocalise(); =head2 visit(\%blocks) This method is called by L<Template::Document> objects immediately before they process their content. It is called to register any local C<BLOCK> definitions with the context object so that they may be subsequently delivered on request. =head2 leave() Compliment to the L<visit()> method. Called by L<Template::Document> objects immediately after they process their content. =head2 view() This method creates a L<Template::View> object bound to the context. =head2 reset() Clears the local L<BLOCKS> cache of any C<BLOCK> definitions. Any initial set of L<BLOCKS> specified as a configuration item to the constructor will be reinstated. =head2 debugging($flag, @args) This method is used to control debugging output. It is used to implement the L<DEBUG|Template::Manual::Directives#DEBUG> directive. The first argument can be C<on> or C<off> to enable or disable debugging respectively. The numerical values C<0> and C<1> can also be used if you prefer. $context->debugging('on'); Alternately, the first argument can be C<format> to define a new debug message format. The second argument should be the format string which can contain any of the C<$file>, C<$line> or C<$text> symbols to indicate where the relevant values should be inserted. # note single quotes to prevent interpolated of variables $context->debugging( format => '## $file line $line: $text' ); The final use of this method is to generate debugging messages themselves. The first argument should be C<msg>, followed by a reference to a hash array of value to insert into the debugging format string. $context->debugging( msg => { line => 20, file => 'example.tt', text => 'Trampoline! Trampoline!', } ); =head2 AUTOLOAD An C<AUTOLOAD> method provides access to context configuration items. $stash = $context->stash(); $tflag = $context->trim(); $epflag = $context->eval_perl(); ... =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Document>, L<Template::Exception>, L<Template::Filters>, L<Template::Plugins>, L<Template::Provider>, L<Template::Service>, L<Template::Stash> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��.N� � lib/Template/Tools.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Tools # # DESCRIPTION # Index page for documentation about the command line tools # distributed with the Template Toolkit. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Tools - Command Line Tools for the Template Toolkit =head1 Template Tools The Template Toolkit includes the following command line tools for processing templates. =head2 tpage The L<tpage|Template::Tools::tpage> script can be used to process a single template using the Template Toolkit. $ tpage --define msg="Hello World" greeting.tt2 Use the C<-h> option to get a summary of options: $ tpage -h See the L<Template::Tools::tpage> documentation for further information and examples of use. =head2 ttree The L<ttree|Template::Tools::ttree> script can be used to process an entire directory of templates. $ ttree --src /path/to/templates --dest /path/to/output Use the C<-h> option to get a summary of options: $ ttree -h See the L<Template::Tools::ttree> documentation for further information and examples of use. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[TW�6h h lib/Template/Tools/tpage.podnu ��6�$ =head1 NAME Template::Tools::tpage - Process templates from command line =head1 USAGE tpage [ --define var=value ] file(s) =head1 DESCRIPTION The B<tpage> script is a simple wrapper around the Template Toolkit processor. Files specified by name on the command line are processed in turn by the template processor and the resulting output is sent to STDOUT and can be redirected accordingly. e.g. tpage myfile > myfile.out tpage header myfile footer > myfile.html If no file names are specified on the command line then B<tpage> will read STDIN for input. The C<--define> option can be used to set the values of template variables. e.g. tpage --define author="Andy Wardley" skeleton.pm > MyModule.pm =head2 The F<.tpagerc> Configuration File You can use a F<.tpagerc> file in your home directory. The purpose of this file is to set any I<global> configuration options that you want applied I<every> time F<tpage> is run. For example, you can use the C<include_path> to use template files from a generic template directory. Run C<tpage -h> for a summary of the options available. See L<Template> for general information about the Perl Template Toolkit and the template language and features. =head1 AUTHOR Andy Wardley L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2008 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<ttree|Template::Tools::ttree> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��0�H) H) lib/Template/Tools/ttree.podnu ��6�$ =head1 NAME Template::Tools::ttree - Process entire directory trees of templates =head1 SYNOPSIS ttree [options] [files] =head1 DESCRIPTION The F<ttree> script is used to process entire directory trees containing template files. The resulting output from processing each file is then written to a corresponding file in a destination directory. The script compares the modification times of source and destination files (where they already exist) and processes only those files that have been modified. In other words, it is the equivalent of 'make' for the Template Toolkit. It supports a number of options which can be used to configure behaviour, define locations and set Template Toolkit options. The script first reads the F<.ttreerc> configuration file in the HOME directory, or an alternative file specified in the TTREERC environment variable. Then, it processes any command line arguments, including any additional configuration files specified via the C<-f> (file) option. =head2 The F<.ttreerc> Configuration File When you run F<ttree> for the first time it will ask you if you want it to create a F<.ttreerc> file for you. This will be created in your home directory. $ ttree Do you want me to create a sample '.ttreerc' file for you? (file: /home/abw/.ttreerc) [y/n]: y /home/abw/.ttreerc created. Please edit accordingly and re-run ttree The purpose of this file is to set any I<global> configuration options that you want applied I<every> time F<ttree> is run. For example, you can use the C<ignore> and C<copy> option to provide regular expressions that specify which files should be ignored and which should be copied rather than being processed as templates. You may also want to set flags like C<verbose> and C<recurse> according to your preference. A minimal F<.ttreerc>: # ignore these files ignore = \b(CVS|RCS)\b ignore = ^# ignore = ~$ # copy these files copy = \.(gif|png|jpg|pdf)$ # recurse into directories recurse # provide info about what's going on verbose In most cases, you'll want to create a different F<ttree> configuration file for each project you're working on. The C<cfg> option allows you to specify a directory where F<ttree> can find further configuration files. cfg = /home/abw/.ttree The C<-f> command line option can be used to specify which configuration file should be used. You can specify a filename using an absolute or relative path: $ ttree -f /home/abw/web/example/etc/ttree.cfg $ ttree -f ./etc/ttree.cfg $ ttree -f ../etc/ttree.cfg If the configuration file does not begin with C</> or C<.> or something that looks like a MS-DOS absolute path (e.g. C<C:\\etc\\ttree.cfg>) then F<ttree> will look for it in the directory specified by the C<cfg> option. $ ttree -f test1 # /home/abw/.ttree/test1 The C<cfg> option can only be used in the F<.ttreerc> file. All the other options can be used in the F<.ttreerc> or any other F<ttree> configuration file. They can all also be specified as command line options. Remember that F<.ttreerc> is always processed I<before> any configuration file specified with the C<-f> option. Certain options like C<lib> can be used any number of times and accumulate their values. For example, consider the following configuration files: F</home/abw/.ttreerc>: cfg = /home/abw/.ttree lib = /usr/local/tt2/templates F</home/abw/.ttree/myconfig>: lib = /home/abw/web/example/templates/lib When F<ttree> is invoked as follows: $ ttree -f myconfig the C<lib> option will be set to the following directories: /usr/local/tt2/templates /home/abw/web/example/templates/lib Any templates located under F</usr/local/tt2/templates> will be used in preference to those located under F</home/abw/web/example/templates/lib>. This may be what you want, but then again, it might not. For this reason, it is good practice to keep the F<.ttreerc> as simple as possible and use different configuration files for each F<ttree> project. =head2 Directory Options The C<src> option is used to define the directory containing the source templates to be processed. It can be provided as a command line option or in a configuration file as shown here: src = /home/abw/web/example/templates/src Each template in this directory typically corresponds to a single web page or other document. The C<dest> option is used to specify the destination directory for the generated output. dest = /home/abw/web/example/html The C<lib> option is used to define one or more directories containing additional library templates. These templates are not documents in their own right and typically comprise of smaller, modular components like headers, footers and menus that are incorporated into pages templates. lib = /home/abw/web/example/templates/lib lib = /usr/local/tt2/templates The C<lib> option can be used repeatedly to add further directories to the search path. A list of templates can be passed to F<ttree> as command line arguments. $ ttree foo.html bar.html It looks for these templates in the C<src> directory and processes them through the Template Toolkit, using any additional template components from the C<lib> directories. The generated output is then written to the corresponding file in the C<dest> directory. If F<ttree> is invoked without explicitly specifying any templates to be processed then it will process every file in the C<src> directory. If the C<-r> (recurse) option is set then it will additionally iterate down through sub-directories and process and other template files it finds therein. $ ttree -r If a template has been processed previously, F<ttree> will compare the modification times of the source and destination files. If the source template (or one it is dependant on) has not been modified more recently than the generated output file then F<ttree> will not process it. The F<-a> (all) option can be used to force F<ttree> to process all files regardless of modification time. $ ttree -a Any templates explicitly named as command line argument are always processed and the modification time checking is bypassed. =head2 File Options The C<ignore>, C<copy> and C<accept> options are used to specify Perl regexen to filter file names. Files that match any of the C<ignore> options will not be processed. Remaining files that match any of the C<copy> regexen will be copied to the destination directory. Remaining files that then match any of the C<accept> criteria are then processed via the Template Toolkit. If no C<accept> parameter is specified then all files will be accepted for processing if not already copied or ignored. # ignore these files ignore = \b(CVS|RCS)\b ignore = ^# ignore = ~$ # copy these files copy = \.(gif|png|jpg|pdf)$ # accept only .tt2 templates accept = \.tt2$ The C<suffix> option is used to define mappings between the file extensions for source templates and the generated output files. The following example specifies that source templates with a C<.tt2> suffix should be output as C<.html> files: suffix tt2=html Or on the command line, --suffix tt2=html You can provide any number of different suffix mappings by repeating this option. =head2 Template Dependencies The C<depend> and C<depend_file> options allow you to specify how any given template file depends on another file or group of files. The C<depend> option is used to express a single dependency. $ ttree --depend foo=bar,baz This command line example shows the C<--depend> option being used to specify that the F<foo> file is dependant on the F<bar> and F<baz> templates. This option can be used many time on the command line: $ ttree --depend foo=bar,baz --depend crash=bang,wallop or in a configuration file: depend foo=bar,baz depend crash=bang,wallop The file appearing on the left of the C<=> is specified relative to the C<src> or C<lib> directories. The file(s) appearing on the right can be specified relative to any of these directories or as absolute file paths. For example: $ ttree --depend foo=bar,/tmp/baz To define a dependency that applies to all files, use C<*> on the left of the C<=>. $ ttree --depend *=header,footer or in a configuration file: depend *=header,footer Any templates that are defined in the C<pre_process>, C<post_process>, C<process> or C<wrapper> options will automatically be added to the list of global dependencies that apply to all templates. The C<depend_file> option can be used to specify a file that contains dependency information. $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep Here is an example of a dependency file: # This is a comment. It is ignored. index.html: header footer menubar header: titlebar hotlinks menubar: menuitem # spanning multiple lines with the backslash another.html: header footer menubar \ sidebar searchform Lines beginning with the C<#> character are comments and are ignored. Blank lines are also ignored. All other lines should provide a filename followed by a colon and then a list of dependant files separated by whitespace, commas or both. Whitespace around the colon is also optional. Lines ending in the C<\> character are continued onto the following line. Files that contain spaces can be quoted. That is only necessary for files after the colon (':'). The file before the colon may be quoted if it contains a colon. As with the command line options, the C<*> character can be used as a wildcard to specify a dependency for all templates. * : config,header =head2 Template Toolkit Options F<ttree> also provides access to the usual range of Template Toolkit options. For example, the C<--pre_chomp> and C<--post_chomp> F<ttree> options correspond to the C<PRE_CHOMP> and C<POST_CHOMP> options. Run C<ttree -h> for a summary of the options available. =head1 AUTHORS Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://www.wardley.org> With contributions from Dylan William Hardison (support for dependencies), Bryce Harrington (C<absolute> and C<relative> options), Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon Brocard who gets everywhere, it seems. =head1 COPYRIGHT Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Tools::tpage|tpage> PK � �[�����4 �4 lib/Template/Iterator.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Iterator # # DESCRIPTION # # Module defining an iterator class which is used by the FOREACH # directive for iterating through data sets. This may be # sub-classed to define more specific iterator types. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Iterator; use strict; use warnings; use base 'Template::Base'; use Template::Constants; use Template::Exception; use Scalar::Util qw(blessed); use constant ODD => 'odd'; use constant EVEN => 'even'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $AUTOLOAD; #======================================================================== # ----- CLASS METHODS ----- #======================================================================== #------------------------------------------------------------------------ # new(\@target, \%options) # # Constructor method which creates and returns a reference to a new # Template::Iterator object. A reference to the target data (array # or hash) may be passed for the object to iterate through. #------------------------------------------------------------------------ sub new { my $class = shift; my $data = shift || [ ]; my $params = shift || { }; if (ref $data eq 'HASH') { # map a hash into a list of { key => ???, value => ??? } hashes, # one for each key, sorted by keys $data = [ map { { key => $_, value => $data->{ $_ } } } sort keys %$data ]; } elsif (blessed($data) && $data->can('as_list')) { $data = $data->as_list(); } elsif (ref $data ne 'ARRAY') { # coerce any non-list data into an array reference $data = [ $data ] ; } bless { _DATA => $data, _ERROR => '', }, $class; } #======================================================================== # ----- PUBLIC OBJECT METHODS ----- #======================================================================== #------------------------------------------------------------------------ # get_first() # # Initialises the object for iterating through the target data set. The # first record is returned, if defined, along with the STATUS_OK value. # If there is no target data, or the data is an empty set, then undef # is returned with the STATUS_DONE value. #------------------------------------------------------------------------ sub get_first { my $self = shift; my $data = $self->{ _DATA }; $self->{ _DATASET } = $self->{ _DATA }; my $size = scalar @$data; my $index = 0; return (undef, Template::Constants::STATUS_DONE) unless $size; # initialise various counters, flags, etc. @$self{ qw( SIZE MAX INDEX COUNT FIRST LAST ) } = ( $size, $size - 1, $index, 1, 1, $size > 1 ? 0 : 1, undef ); @$self{ qw( PREV NEXT ) } = ( undef, $self->{ _DATASET }->[ $index + 1 ]); return $self->{ _DATASET }->[ $index ]; } #------------------------------------------------------------------------ # get_next() # # Called repeatedly to access successive elements in the data set. # Should only be called after calling get_first() or a warning will # be raised and (undef, STATUS_DONE) returned. #------------------------------------------------------------------------ sub get_next { my ( $max, $index ) = @{ $_[0] }{qw( MAX INDEX )}; # warn about incorrect usage if ( !defined $index ) { my ( $pack, $file, $line ) = caller(); warn("iterator get_next() called before get_first() at $file line $line\n"); return ( undef, Template::Constants::STATUS_DONE ); ## RETURN ## } # if there's still some data to go... elsif ( $index >= $max ) { return ( undef, Template::Constants::STATUS_DONE ); ## RETURN ## } my $self = shift; my $dataset = $self->{_DATASET}; $index++; # update counters and flags @$self{qw( INDEX COUNT FIRST LAST PREV NEXT )} = ( $index, # INDEX $index + 1, # COUNT 0, # FIRST $index == $max ? 1 : 0, # LAST @$dataset[ $index - 1, $index + 1 ] # PREV, NEXT ); return $dataset->[ $index ]; ## RETURN ## } #------------------------------------------------------------------------ # get_all() # # Method which returns all remaining items in the iterator as a Perl list # reference. May be called at any time in the life-cycle of the iterator. # The get_first() method will be called automatically if necessary, and # then subsequent get_next() calls are made, storing each returned # result until the list is exhausted. #------------------------------------------------------------------------ sub get_all { my $self = shift; my ($max, $index) = @$self{ qw( MAX INDEX ) }; my @data; # handle cases where get_first() has yet to be called. unless (defined $index) { my ($first, $status) = $self->get_first; # refresh $max and $index, after get_first updates MAX and INDEX ($max, $index) = @$self{ qw( MAX INDEX ) }; # empty lists are handled here. if ($status && $status == Template::Constants::STATUS_DONE) { return (undef, Template::Constants::STATUS_DONE); ## RETURN ## } push @data, $first; ## if there's nothing left in the iterator, return the single value. unless ($index < $max) { return \@data; } } # if there's still some data to go... if ($index < $max) { $index++; push @data, @{ $self->{ _DATASET } } [ $index..$max ]; # update counters and flags @$self{ qw( INDEX COUNT FIRST LAST ) } = ( $max, $max + 1, 0, 1 ); return \@data; ## RETURN ## } else { return (undef, Template::Constants::STATUS_DONE); ## RETURN ## } } sub odd { shift->{ COUNT } % 2 ? 1 : 0 } sub even { shift->{ COUNT } % 2 ? 0 : 1 } sub parity { shift->{ COUNT } % 2 ? ODD : EVEN; } sub index { return $_[0]->{INDEX}; } sub count { return $_[0]->{COUNT}; } sub number { # This is here for backward compatibility per sub AUTOLOAD return $_[0]->{COUNT}; } sub first { return $_[0]->{FIRST}; } sub last { return $_[0]->{LAST}; } sub size { return $_[0]->{SIZE}; } #------------------------------------------------------------------------ # AUTOLOAD # # Provides access to internal fields (e.g. prev, next, etc) #------------------------------------------------------------------------ sub AUTOLOAD { my $self = shift; my $item = $AUTOLOAD; $item =~ s/.*:://; return if $item eq 'DESTROY'; # alias NUMBER to COUNT for backwards compatibility $item = 'COUNT' if CORE::index(uc $item,'NUMBER') > -1; return $self->{ uc $item }; } 1; __END__ =head1 NAME Template::Iterator - Data iterator used by the FOREACH directive =head1 SYNOPSIS my $iter = Template::Iterator->new(\@data, \%options); =head1 DESCRIPTION The C<Template::Iterator> module defines a generic data iterator for use by the C<FOREACH> directive. It may be used as the base class for custom iterators. =head1 PUBLIC METHODS =head2 new($data) Constructor method. A reference to a list of values is passed as the first parameter. Subsequent calls to L<get_first()> and L<get_next()> calls will return each element from the list. my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]); The constructor will also accept a reference to a hash array and will expand it into a list in which each entry is a hash array containing a 'C<key>' and 'C<value>' item, sorted according to the hash keys. my $iter = Template::Iterator->new({ foo => 'Foo Item', bar => 'Bar Item', }); This is equivalent to: my $iter = Template::Iterator->new([ { key => 'bar', value => 'Bar Item' }, { key => 'foo', value => 'Foo Item' }, ]); When passed a single item which is not an array reference, the constructor will automatically create a list containing that single item. my $iter = Template::Iterator->new('foo'); This is equivalent to: my $iter = Template::Iterator->new([ 'foo' ]); Note that a single item which is an object based on a blessed ARRAY references will NOT be treated as an array and will be folded into a list containing that one object reference. my $list = bless [ 'foo', 'bar' ], 'MyListClass'; my $iter = Template::Iterator->new($list); equivalent to: my $iter = Template::Iterator->new([ $list ]); If the object provides an C<as_list()> method then the L<Template::Iterator> constructor will call that method to return the list of data. For example: package MyListObject; sub new { my $class = shift; bless [ @_ ], $class; } package main; my $list = MyListObject->new('foo', 'bar'); my $iter = Template::Iterator->new($list); This is then functionally equivalent to: my $iter = Template::Iterator->new([ $list ]); The iterator will return only one item, a reference to the C<MyListObject> object, C<$list>. By adding an C<as_list()> method to the C<MyListObject> class, we can force the C<Template::Iterator> constructor to treat the object as a list and use the data contained within. package MyListObject; ... sub as_list { my $self = shift; return $self; } package main; my $list = MyListObject->new('foo', 'bar'); my $iter = Template::Iterator->new($list); The iterator will now return the two items, 'C<foo>' and 'C<bar>', which the C<MyObjectList> encapsulates. =head2 get_first() Returns a C<($value, $error)> pair for the first item in the iterator set. The C<$error> returned may be zero or undefined to indicate a valid datum was successfully returned. Returns an error of C<STATUS_DONE> if the list is empty. =head2 get_next() Returns a C<($value, $error)> pair for the next item in the iterator set. Returns an error of C<STATUS_DONE> if all items in the list have been visited. =head2 get_all() Returns a C<(\@values, $error)> pair for all remaining items in the iterator set. Returns an error of C<STATUS_DONE> if all items in the list have been visited. =head2 size() Returns the size of the data set or undef if unknown. =head2 max() Returns the maximum index number (i.e. the index of the last element) which is equivalent to L<size()> - C<1>. =head2 index() Returns the current index number which is in the range C<0> to L<max()>. =head2 count() Returns the current iteration count in the range C<1> to L<size()>. This is equivalent to L<index()> + C<1>. =head2 first() Returns a boolean value to indicate if the iterator is currently on the first iteration of the set. =head2 last() Returns a boolean value to indicate if the iterator is currently on the last iteration of the set. =head2 prev() Returns the previous item in the data set, or C<undef> if the iterator is on the first item. =head2 next() Returns the next item in the data set or C<undef> if the iterator is on the last item. =head2 number() This is an alias to 'count' to provide backward compatibility. View L<count>. =head2 parity() Returns the text string C<even> or C<odd> to indicate the parity of the current iteration count (starting at 1). This is typically used to create striped I<zebra tables>. <table> [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%] <tr class="[% loop.parity %]"> <td>[% name %]</td> </tr> [% END %] </table> This will produce the following output: <table> <tr class="odd"> <td>Arthur</td> </tr> <tr class="even"> <td>Ford</td> </tr> <tr class="odd"> <td>Trillian</td> </tr> </table> You can then style the C<tr.odd> and C<tr.even> elements using CSS: tr.odd td { background-color: black; color: white; } tr.even td { background-color: white; color: black; } =head2 odd() Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an odd number. In other words, this will return a true value for the first iterator, the third, fifth, and so on. =head2 even() Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an even number. In other words, this will return a true value for the second iteration, the fourth, sixth, and so on. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�-G_�% �% lib/Template/Constants.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Constants.pm # # DESCRIPTION # Definition of constants for the Template Toolkit. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Constants; require Exporter; use strict; use warnings; use Exporter; use base qw( Exporter ); our ( @EXPORT_OK, %EXPORT_TAGS ); our ( $DEBUG_OPTIONS, @STATUS, @ERROR, @CHOMP, @DEBUG, @ISA ); our $VERSION = '3.100'; #======================================================================== # ----- EXPORTER ----- #======================================================================== # STATUS constants returned by directives use constant STATUS_OK => 0; # ok use constant STATUS_RETURN => 1; # ok, block ended by RETURN use constant STATUS_STOP => 2; # ok, stopped by STOP use constant STATUS_DONE => 3; # ok, iterator done use constant STATUS_DECLINED => 4; # ok, declined to service request use constant STATUS_ERROR => 255; # error condition # ERROR constants for indicating exception types use constant ERROR_RETURN => 'return'; # return a status code use constant ERROR_FILE => 'file'; # file error: I/O, parse, recursion use constant ERROR_VIEW => 'view'; # view error use constant ERROR_UNDEF => 'undef'; # undefined variable value used use constant ERROR_PERL => 'perl'; # error in [% PERL %] block use constant ERROR_FILTER => 'filter'; # filter error use constant ERROR_PLUGIN => 'plugin'; # plugin error # CHOMP constants for PRE_CHOMP and POST_CHOMP use constant CHOMP_NONE => 0; # do not remove whitespace use constant CHOMP_ALL => 1; # remove whitespace up to newline use constant CHOMP_ONE => 1; # new name for CHOMP_ALL use constant CHOMP_COLLAPSE => 2; # collapse whitespace to a single space use constant CHOMP_GREEDY => 3; # remove all whitespace including newlines # DEBUG constants to enable various debugging options use constant DEBUG_OFF => 0; # do nothing use constant DEBUG_ON => 1; # basic debugging flag use constant DEBUG_UNDEF => 2; # throw undef on undefined variables use constant DEBUG_VARS => 4; # general variable debugging use constant DEBUG_DIRS => 8; # directive debugging use constant DEBUG_STASH => 16; # general stash debugging use constant DEBUG_CONTEXT => 32; # context debugging use constant DEBUG_PARSER => 64; # parser debugging use constant DEBUG_PROVIDER => 128; # provider debugging use constant DEBUG_PLUGINS => 256; # plugins debugging use constant DEBUG_FILTERS => 512; # filters debugging use constant DEBUG_SERVICE => 1024; # context debugging use constant DEBUG_ALL => 2047; # everything # extra debugging flags use constant DEBUG_CALLER => 4096; # add caller file/line use constant DEBUG_FLAGS => 4096; # bitmask to extract flags $DEBUG_OPTIONS = { &DEBUG_OFF => off => off => &DEBUG_OFF, &DEBUG_ON => on => on => &DEBUG_ON, &DEBUG_UNDEF => undef => undef => &DEBUG_UNDEF, &DEBUG_VARS => vars => vars => &DEBUG_VARS, &DEBUG_DIRS => dirs => dirs => &DEBUG_DIRS, &DEBUG_STASH => stash => stash => &DEBUG_STASH, &DEBUG_CONTEXT => context => context => &DEBUG_CONTEXT, &DEBUG_PARSER => parser => parser => &DEBUG_PARSER, &DEBUG_PROVIDER => provider => provider => &DEBUG_PROVIDER, &DEBUG_PLUGINS => plugins => plugins => &DEBUG_PLUGINS, &DEBUG_FILTERS => filters => filters => &DEBUG_FILTERS, &DEBUG_SERVICE => service => service => &DEBUG_SERVICE, &DEBUG_ALL => all => all => &DEBUG_ALL, &DEBUG_CALLER => caller => caller => &DEBUG_CALLER, }; @STATUS = qw( STATUS_OK STATUS_RETURN STATUS_STOP STATUS_DONE STATUS_DECLINED STATUS_ERROR ); @ERROR = qw( ERROR_FILE ERROR_VIEW ERROR_UNDEF ERROR_PERL ERROR_RETURN ERROR_FILTER ERROR_PLUGIN ); @CHOMP = qw( CHOMP_NONE CHOMP_ALL CHOMP_ONE CHOMP_COLLAPSE CHOMP_GREEDY ); @DEBUG = qw( DEBUG_OFF DEBUG_ON DEBUG_UNDEF DEBUG_VARS DEBUG_DIRS DEBUG_STASH DEBUG_CONTEXT DEBUG_PARSER DEBUG_PROVIDER DEBUG_PLUGINS DEBUG_FILTERS DEBUG_SERVICE DEBUG_ALL DEBUG_CALLER DEBUG_FLAGS ); @EXPORT_OK = ( @STATUS, @ERROR, @CHOMP, @DEBUG ); %EXPORT_TAGS = ( 'all' => [ @EXPORT_OK ], 'status' => [ @STATUS ], 'error' => [ @ERROR ], 'chomp' => [ @CHOMP ], 'debug' => [ @DEBUG ], ); sub debug_flags { my ($self, $debug) = @_; my (@flags, $flag, $value); $debug = $self unless defined($debug) || ref($self); if ( $debug !~ tr{0-9}{}c) { foreach $flag (@DEBUG) { next if $flag eq 'DEBUG_OFF' || $flag eq 'DEBUG_ALL' || $flag eq 'DEBUG_FLAGS'; # don't trash the original substr($flag,0,6,'') if index($flag,'DEBUG_') == 0; $flag = lc $flag; return $self->error("no value for flag: $flag") unless defined($value = $DEBUG_OPTIONS->{ $flag }); $flag = $value; if ($debug & $flag) { $value = $DEBUG_OPTIONS->{ $flag }; return $self->error("no value for flag: $flag") unless defined $value; push(@flags, $value); } } return wantarray ? @flags : join(', ', @flags); } else { @flags = split(/\W+/, $debug); $debug = 0; foreach $flag (@flags) { $value = $DEBUG_OPTIONS->{ $flag }; return $self->error("unknown debug flag: $flag") unless defined $value; $debug |= $value; } return $debug; } } 1; __END__ =head1 NAME Template::Constants - Defines constants for the Template Toolkit =head1 SYNOPSIS use Template::Constants qw( :status :error :all ); =head1 DESCRIPTION The C<Template::Constants> modules defines, and optionally exports into the caller's namespace, a number of constants used by the L<Template> package. Constants may be used by specifying the C<Template::Constants> package explicitly: use Template::Constants; print Template::Constants::STATUS_DECLINED; Constants may be imported into the caller's namespace by naming them as options to the C<use Template::Constants> statement: use Template::Constants qw( STATUS_DECLINED ); print STATUS_DECLINED; Alternatively, one of the following tagset identifiers may be specified to import sets of constants: 'C<:status>', 'C<:error>', 'C<:all>'. use Template::Constants qw( :status ); print STATUS_DECLINED; Consult the documentation for the C<Exporter> module for more information on exporting variables. =head1 EXPORTABLE TAG SETS The following tag sets and associated constants are defined: :status STATUS_OK # no problem, continue STATUS_RETURN # ended current block then continue (ok) STATUS_STOP # controlled stop (ok) STATUS_DONE # iterator is all done (ok) STATUS_DECLINED # provider declined to service request (ok) STATUS_ERROR # general error condition (not ok) :error ERROR_RETURN # return a status code (e.g. 'stop') ERROR_FILE # file error: I/O, parse, recursion ERROR_UNDEF # undefined variable value used ERROR_PERL # error in [% PERL %] block ERROR_FILTER # filter error ERROR_PLUGIN # plugin error :chomp # for PRE_CHOMP and POST_CHOMP CHOMP_NONE # do not remove whitespace CHOMP_ONE # remove whitespace to newline CHOMP_ALL # old name for CHOMP_ONE (deprecated) CHOMP_COLLAPSE # collapse whitespace to a single space CHOMP_GREEDY # remove all whitespace including newlines :debug DEBUG_OFF # do nothing DEBUG_ON # basic debugging flag DEBUG_UNDEF # throw undef on undefined variables DEBUG_VARS # general variable debugging DEBUG_DIRS # directive debugging DEBUG_STASH # general stash debugging DEBUG_CONTEXT # context debugging DEBUG_PARSER # parser debugging DEBUG_PROVIDER # provider debugging DEBUG_PLUGINS # plugins debugging DEBUG_FILTERS # filters debugging DEBUG_SERVICE # context debugging DEBUG_ALL # everything DEBUG_CALLER # add caller file/line info DEBUG_FLAGS # bitmap used internally :all All the above constants. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, C<Exporter> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�O���" �" lib/Template/Plugin.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Plugin # # DESCRIPTION # # Module defining a base class for a plugin object which can be loaded # and instantiated via the USE directive. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it an/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Plugin; use strict; use warnings; use base 'Template::Base'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $ERROR = ''; our $AUTOLOAD; #======================================================================== # ----- CLASS METHODS ----- #======================================================================== #------------------------------------------------------------------------ # load() # # Class method called when the plugin module is first loaded. It # returns the name of a class (by default, its own class) or a prototype # object which will be used to instantiate new objects. The new() # method is then called against the class name (class method) or # prototype object (object method) to create a new instances of the # object. #------------------------------------------------------------------------ sub load { return $_[0]; } #------------------------------------------------------------------------ # new($context, $delegate, @params) # # Object constructor which is called by the Template::Context to # instantiate a new Plugin object. This base class constructor is # used as a general mechanism to load and delegate to other Perl # modules. The context is passed as the first parameter, followed by # a reference to a delegate object or the name of the module which # should be loaded and instantiated. Any additional parameters passed # to the USE directive are forwarded to the new() constructor. # # A plugin object is returned which has an AUTOLOAD method to delegate # requests to the underlying object. #------------------------------------------------------------------------ sub new { my $class = shift; bless { }, $class; } #------------------------------------------------------------------------ # fail($error) # # Version 1 error reporting function, now replaced by error() inherited # from Template::Base. Raises a "deprecated function" warning and then # calls error(). #------------------------------------------------------------------------ sub fail { my $class = shift; my ($pkg, $file, $line) = caller(); warn "Template::Plugin::fail() is deprecated at $file line $line. Please use error()\n"; $class->error(@_); } 1; __END__ =head1 NAME Template::Plugin - Base class for Template Toolkit plugins =head1 SYNOPSIS package MyOrg::Template::Plugin::MyPlugin; use base qw( Template::Plugin ); use Template::Plugin; use MyModule; sub new { my $class = shift; my $context = shift; bless { ... }, $class; } =head1 DESCRIPTION A "plugin" for the Template Toolkit is simply a Perl module which exists in a known package location (e.g. C<Template::Plugin::*>) and conforms to a regular standard, allowing it to be loaded and used automatically. The C<Template::Plugin> module defines a base class from which other plugin modules can be derived. A plugin does not have to be derived from Template::Plugin but should at least conform to its object-oriented interface. It is recommended that you create plugins in your own package namespace to avoid conflict with toolkit plugins. e.g. package MyOrg::Template::Plugin::FooBar; Use the L<PLUGIN_BASE|Template::Manual::Config#PLUGIN_BASE> option to specify the namespace that you use. e.g. use Template; my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin', }); =head1 METHODS The following methods form the basic interface between the Template Toolkit and plugin modules. =head2 load($context) This method is called by the Template Toolkit when the plugin module is first loaded. It is called as a package method and thus implicitly receives the package name as the first parameter. A reference to the L<Template::Context> object loading the plugin is also passed. The default behaviour for the C<load()> method is to simply return the class name. The calling context then uses this class name to call the C<new()> package method. package MyPlugin; sub load { # called as MyPlugin->load($context) my ($class, $context) = @_; return $class; # returns 'MyPlugin' } =head2 new($context, @params) This method is called to instantiate a new plugin object for the C<USE> directive. It is called as a package method against the class name returned by L<load()>. A reference to the L<Template::Context> object creating the plugin is passed, along with any additional parameters specified in the C<USE> directive. sub new { # called as MyPlugin->new($context) my ($class, $context, @params) = @_; bless { _CONTEXT => $context, }, $class; # returns blessed MyPlugin object } =head2 error($error) This method, inherited from the L<Template::Base> module, is used for reporting and returning errors. It can be called as a package method to set/return the C<$ERROR> package variable, or as an object method to set/return the object C<_ERROR> member. When called with an argument, it sets the relevant variable and returns C<undef.> When called without an argument, it returns the value of the variable. package MyPlugin; use base 'Template::Plugin'; sub new { my ($class, $context, $dsn) = @_; return $class->error('No data source specified') unless $dsn; bless { _DSN => $dsn, }, $class; } package main; my $something = MyPlugin->new() || die MyPlugin->error(), "\n"; $something->do_something() || die $something->error(), "\n"; =head1 DEEPER MAGIC The L<Template::Context> object that handles the loading and use of plugins calls the L<new()> and L<error()> methods against the package name returned by the L<load()> method. In pseudo-code terms looks something like this: $class = MyPlugin->load($context); # returns 'MyPlugin' $object = $class->new($context, @params) # MyPlugin->new(...) || die $class->error(); # MyPlugin->error() The L<load()> method may alternately return a blessed reference to an object instance. In this case, L<new()> and L<error()> are then called as I<object> methods against that prototype instance. package YourPlugin; sub load { my ($class, $context) = @_; bless { _CONTEXT => $context, }, $class; } sub new { my ($self, $context, @params) = @_; return $self; } In this example, we have implemented a 'Singleton' plugin. One object gets created when L<load()> is called and this simply returns itself for each call to L<new().> Another implementation might require individual objects to be created for every call to L<new(),> but with each object sharing a reference to some other object to maintain cached data, database handles, etc. This pseudo-code example demonstrates the principle. package MyServer; sub load { my ($class, $context) = @_; bless { _CONTEXT => $context, _CACHE => { }, }, $class; } sub new { my ($self, $context, @params) = @_; MyClient->new($self, @params); } sub add_to_cache { ... } sub get_from_cache { ... } package MyClient; sub new { my ($class, $server, $blah) = @_; bless { _SERVER => $server, _BLAH => $blah, }, $class; } sub get { my $self = shift; $self->{ _SERVER }->get_from_cache(@_); } sub put { my $self = shift; $self->{ _SERVER }->add_to_cache(@_); } When the plugin is loaded, a C<MyServer> instance is created. The L<new()> method is called against this object which instantiates and returns a C<MyClient> object, primed to communicate with the creating C<MyServer>. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Plugins>, L<Template::Context> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[݇�5 �5 lib/Template/Config.pmnu ��6�$ #============================================================= -*-perl-*- # # Template::Config # # DESCRIPTION # Template Toolkit configuration module. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== package Template::Config; use strict; use warnings; use base 'Template::Base'; our $VERSION = '3.100'; our $DEBUG; $DEBUG = 0 unless defined $DEBUG; our $ERROR = ''; our $CONTEXT = 'Template::Context'; our $FILTERS = 'Template::Filters'; our $ITERATOR = 'Template::Iterator'; our $PARSER = 'Template::Parser'; our $PLUGINS = 'Template::Plugins'; our $PROVIDER = 'Template::Provider'; our $SERVICE = 'Template::Service'; our $STASH; $STASH = 'Template::Stash::XS'; our $CONSTANTS = 'Template::Namespace::Constants'; our $LATEX_PATH; our $PDFLATEX_PATH; our $DVIPS_PATH; our @PRELOAD = ( $CONTEXT, $FILTERS, $ITERATOR, $PARSER, $PLUGINS, $PROVIDER, $SERVICE, $STASH ); # the following is set at installation time by the Makefile.PL our $INSTDIR = ''; #======================================================================== # --- CLASS METHODS --- #======================================================================== #------------------------------------------------------------------------ # preload($module, $module, ...) # # Preloads all the standard TT modules that are likely to be used, along # with any other passed as arguments. #------------------------------------------------------------------------ sub preload { my $class = shift; foreach my $module (@PRELOAD, @_) { $class->load($module) || return; }; return 1; } #------------------------------------------------------------------------ # load($module) # # Load a module via require(). Any occurrences of '::' in the module name # are be converted to '/' and '.pm' is appended. Returns 1 on success # or undef on error. Use $class->error() to examine the error string. #------------------------------------------------------------------------ sub load { my ($class, $module) = @_; $module =~ s[::][/]g; $module .= '.pm'; return 1 if $INC{$module}; eval { require $module; }; return $@ ? $class->error("failed to load $module: $@") : 1; } #------------------------------------------------------------------------ # parser(\%params) # # Instantiate a new parser object of the class whose name is denoted by # the package variable $PARSER (default: Template::Parser). Returns # a reference to a newly instantiated parser object or undef on error. # The class error() method can be called without arguments to examine # the error message generated by this failure. #------------------------------------------------------------------------ sub parser { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($PARSER); return $PARSER->new($params) || $class->error("failed to create parser: ", $PARSER->error); } #------------------------------------------------------------------------ # provider(\%params) # # Instantiate a new template provider object (default: Template::Provider). # Returns an object reference or undef on error, as above. #------------------------------------------------------------------------ sub provider { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($PROVIDER); return $PROVIDER->new($params) || $class->error( "failed to create template provider: ", $PROVIDER->error ); } #------------------------------------------------------------------------ # plugins(\%params) # # Instantiate a new plugins provider object (default: Template::Plugins). # Returns an object reference or undef on error, as above. #------------------------------------------------------------------------ sub plugins { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($PLUGINS); return $PLUGINS->new($params) || $class->error( "failed to create plugin provider: ", $PLUGINS->error ); } #------------------------------------------------------------------------ # filters(\%params) # # Instantiate a new filters provider object (default: Template::Filters). # Returns an object reference or undef on error, as above. #------------------------------------------------------------------------ sub filters { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($FILTERS); return $FILTERS->new($params) || $class->error( "failed to create filter provider: ", $FILTERS->error ); } #------------------------------------------------------------------------ # iterator(\@list) # # Instantiate a new Template::Iterator object (default: Template::Iterator). # Returns an object reference or undef on error, as above. #------------------------------------------------------------------------ sub iterator { my $class = shift; my $list = shift; return undef unless $class->load($ITERATOR); return $ITERATOR->new($list, @_) || $class->error("failed to create iterator: ", $ITERATOR->error); } #------------------------------------------------------------------------ # stash(\%vars) # # Instantiate a new template variable stash object (default: # Template::Stash). Returns object or undef, as above. #------------------------------------------------------------------------ sub stash { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($STASH); return $STASH->new($params) || $class->error( "failed to create stash: ", $STASH->error ); } #------------------------------------------------------------------------ # context(\%params) # # Instantiate a new template context object (default: Template::Context). # Returns object or undef, as above. #------------------------------------------------------------------------ sub context { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($CONTEXT); return $CONTEXT->new($params) || $class->error( "failed to create context: ", $CONTEXT->error ); } #------------------------------------------------------------------------ # service(\%params) # # Instantiate a new template context object (default: Template::Service). # Returns object or undef, as above. #------------------------------------------------------------------------ sub service { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($SERVICE); return $SERVICE->new($params) || $class->error( "failed to create context: ", $SERVICE->error ); } #------------------------------------------------------------------------ # constants(\%params) # # Instantiate a new namespace handler for compile time constant folding # (default: Template::Namespace::Constants). # Returns object or undef, as above. #------------------------------------------------------------------------ sub constants { my $class = shift; my $params = defined($_[0]) && ref($_[0]) eq 'HASH' ? shift : { @_ }; return undef unless $class->load($CONSTANTS); return $CONSTANTS->new($params) || $class->error( "failed to create constants namespace: ", $CONSTANTS->error ); } #------------------------------------------------------------------------ # instdir($dir) # # Returns the root installation directory appended with any local # component directory passed as an argument. #------------------------------------------------------------------------ sub instdir { my ($class, $dir) = @_; my $inst = $INSTDIR || return $class->error("no installation directory"); chop $inst while substr($inst,-1) eq '/'; $inst .= "/$dir" if $dir; return $inst; } #======================================================================== # This should probably be moved somewhere else in the long term, but for # now it ensures that Template::TieString is available even if the # Template::Directive module hasn't been loaded, as is the case when # using compiled templates and Template::Parser hasn't yet been loaded # on demand. #======================================================================== #------------------------------------------------------------------------ # simple package for tying $output variable to STDOUT, used by perl() #------------------------------------------------------------------------ package Template::TieString; sub TIEHANDLE { my ($class, $textref) = @_; bless $textref, $class; } sub PRINT { my $self = shift; $$self .= join('', @_); } 1; __END__ =head1 NAME Template::Config - Factory module for instantiating other TT2 modules =head1 SYNOPSIS use Template::Config; =head1 DESCRIPTION This module implements various methods for loading and instantiating other modules that comprise the Template Toolkit. It provides a consistent way to create toolkit components and allows custom modules to be used in place of the regular ones. Package variables such as C<$STASH>, C<$SERVICE>, C<$CONTEXT>, etc., contain the default module/package name for each component (L<Template::Stash>, L<Template::Service> and L<Template::Context>, respectively) and are used by the various factory methods (L<stash()>, L<service()> and L<context()>) to load the appropriate module. Changing these package variables will cause subsequent calls to the relevant factory method to load and instantiate an object from the new class. =head1 PUBLIC METHODS =head2 load($module) Load a module using Perl's L<require()>. Any occurrences of 'C<::>' in the module name are be converted to 'C</>', and 'C<.pm>' is appended. Returns 1 on success or undef on error. Use C<$class-E<gt>error()> to examine the error string. =head2 preload() This method preloads all the other C<Template::*> modules that are likely to be used. It is called automatically by the L<Template> module when running under mod_perl (C<$ENV{MOD_PERL}> is set). =head2 parser(\%config) Instantiate a new parser object of the class whose name is denoted by the package variable C<$PARSER> (default: L<Template::Parser>). Returns a reference to a newly instantiated parser object or undef on error. =head2 provider(\%config) Instantiate a new template provider object (default: L<Template::Provider>). Returns an object reference or undef on error, as above. =head2 plugins(\%config) Instantiate a new plugins provider object (default: L<Template::Plugins>). Returns an object reference or undef on error, as above. =head2 filters(\%config) Instantiate a new filter provider object (default: L<Template::Filters>). Returns an object reference or undef on error, as above. =head2 stash(\%vars) Instantiate a new stash object (L<Template::Stash> or L<Template::Stash::XS> depending on the default set at installation time) using the contents of the optional hash array passed by parameter as initial variable definitions. Returns an object reference or undef on error, as above. =head2 context(\%config) Instantiate a new template context object (default: L<Template::Context>). Returns an object reference or undef on error, as above. =head2 service(\%config) Instantiate a new template service object (default: L<Template::Service>). Returns an object reference or undef on error, as above. =head2 iterator(\%config) Instantiate a new template iterator object (default: L<Template::Iterator>). Returns an object reference or undef on error, as above. =head2 constants(\%config) Instantiate a new namespace handler for compile time constant folding (default: L<Template::Namespace::Constants>). Returns an object reference or undef on error, as above. =head2 instdir($dir) Returns the root directory of the Template Toolkit installation under which optional components are installed. Any relative directory specified as an argument will be appended to the returned directory. # e.g. returns '/usr/local/tt2' my $ttroot = Template::Config->instdir() || die "$Template::Config::ERROR\n"; # e.g. returns '/usr/local/tt2/templates' my $template = Template::Config->instdir('templates') || die "$Template::Config::ERROR\n"; Returns C<undef> and sets C<$Template::Config::ERROR> appropriately if the optional components of the Template Toolkit have not been installed. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��E+E +E lib/Template/Service.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Service # # DESCRIPTION # Module implementing a template processing service which wraps a # template within PRE_PROCESS and POST_PROCESS templates and offers # ERROR recovery. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Service; use strict; use warnings; use base 'Template::Base'; use Template::Config; use Template::Exception; use Template::Constants; use Scalar::Util 'blessed'; use constant EXCEPTION => 'Template::Exception'; our $VERSION = '3.100'; our $DEBUG = 0 unless defined $DEBUG; our $ERROR = ''; #======================================================================== # ----- PUBLIC METHODS ----- #======================================================================== #------------------------------------------------------------------------ # process($template, \%params) # # Process a template within a service framework. A service may encompass # PRE_PROCESS and POST_PROCESS templates and an ERROR hash which names # templates to be substituted for the main template document in case of # error. Each service invocation begins by resetting the state of the # context object via a call to reset(). The AUTO_RESET option may be set # to 0 (default: 1) to bypass this step. #------------------------------------------------------------------------ sub process { my ($self, $template, $params) = @_; my $context = $self->{ CONTEXT }; my ($name, $output, $procout, $error); $output = ''; $self->debug( "process($template, ", defined $params ? $params : '<no params>', ')' ) if $self->{ DEBUG }; $context->reset() if $self->{ AUTO_RESET }; # pre-request compiled template from context so that we can alias it # in the stash for pre-processed templates to reference eval { $template = $context->template($template) }; return $self->error($@) if $@; # localise the variable stash with any parameters passed # and set the 'template' variable $params ||= { }; # TODO: change this to C<||=> so we can use a template parameter $params->{ template } = $template unless ref $template eq 'CODE'; $context->localise($params); SERVICE: { # PRE_PROCESS eval { foreach $name (@{ $self->{ PRE_PROCESS } }) { $self->debug("PRE_PROCESS: $name") if $self->{ DEBUG }; $output .= $context->process($name); } }; last SERVICE if ($error = $@); # PROCESS eval { foreach $name (@{ $self->{ PROCESS } || [ $template ] }) { $self->debug("PROCESS: $name") if $self->{ DEBUG }; $procout .= $context->process($name); } }; if ($error = $@) { last SERVICE unless defined ($procout = $self->_recover(\$error)); } if (defined $procout) { # WRAPPER eval { foreach $name (reverse @{ $self->{ WRAPPER } }) { $self->debug("WRAPPER: $name") if $self->{ DEBUG }; $procout = $context->process($name, { content => $procout }); } }; last SERVICE if ($error = $@); $output .= $procout; } # POST_PROCESS eval { foreach $name (@{ $self->{ POST_PROCESS } }) { $self->debug("POST_PROCESS: $name") if $self->{ DEBUG }; $output .= $context->process($name); } }; last SERVICE if ($error = $@); } $context->delocalise(); delete $params->{ template }; if ($error) { # $error = $error->as_string if ref $error; return $self->error($error); } return $output; } #------------------------------------------------------------------------ # context() # # Returns the internal CONTEXT reference. #------------------------------------------------------------------------ sub context { return $_[0]->{ CONTEXT }; } #======================================================================== # -- PRIVATE METHODS -- #======================================================================== sub _init { my ($self, $config) = @_; my ($item, $data, $context, $block, $blocks); my $delim = $config->{ DELIMITER }; $delim = ':' unless defined $delim; # coerce PRE_PROCESS, PROCESS and POST_PROCESS to arrays if necessary, # by splitting on non-word characters foreach $item (qw( PRE_PROCESS PROCESS POST_PROCESS WRAPPER )) { $data = $config->{ $item }; $self->{ $item } = [ ], next unless (defined $data); $data = [ split($delim, $data || '') ] unless ref $data eq 'ARRAY'; $self->{ $item } = $data; } # unset PROCESS option unless explicitly specified in config $self->{ PROCESS } = undef unless defined $config->{ PROCESS }; $self->{ ERROR } = $config->{ ERROR } || $config->{ ERRORS }; $self->{ AUTO_RESET } = defined $config->{ AUTO_RESET } ? $config->{ AUTO_RESET } : 1; $self->{ DEBUG } = ( $config->{ DEBUG } || 0 ) & Template::Constants::DEBUG_SERVICE; $context = $self->{ CONTEXT } = $config->{ CONTEXT } || Template::Config->context($config) || return $self->error(Template::Config->error); return $self; } #------------------------------------------------------------------------ # _recover(\$exception) # # Examines the internal ERROR hash array to find a handler suitable # for the exception object passed by reference. Selecting the handler # is done by delegation to the exception's select_handler() method, # passing the set of handler keys as arguments. A 'default' handler # may also be provided. The handler value represents the name of a # template which should be processed. #------------------------------------------------------------------------ sub _recover { my ($self, $error) = @_; my $context = $self->{ CONTEXT }; my ($hkey, $handler, $output); # there shouldn't ever be a non-exception object received at this # point... unless a module like CGI::Carp messes around with the # DIE handler. return undef unless blessed($$error) && $$error->isa(EXCEPTION); # a 'stop' exception is thrown by [% STOP %] - we return the output # buffer stored in the exception object return $$error->text() if $$error->type() eq 'stop'; my $handlers = $self->{ ERROR } || return undef; ## RETURN if (ref $handlers eq 'HASH') { if ($hkey = $$error->select_handler(keys %$handlers)) { $handler = $handlers->{ $hkey }; $self->debug("using error handler for $hkey") if $self->{ DEBUG }; } elsif ($handler = $handlers->{ default }) { # use default handler $self->debug("using default error handler") if $self->{ DEBUG }; } else { return undef; ## RETURN } } else { $handler = $handlers; $self->debug("using default error handler") if $self->{ DEBUG }; } eval { $handler = $context->template($handler) }; if ($@) { $$error = $@; return undef; ## RETURN }; $context->stash->set('error', $$error); eval { $output .= $context->process($handler); }; if ($@) { $$error = $@; return undef; ## RETURN } return $output; } 1; __END__ =head1 NAME Template::Service - General purpose template processing service =head1 SYNOPSIS use Template::Service; my $service = Template::Service->new({ PRE_PROCESS => [ 'config', 'header' ], POST_PROCESS => 'footer', ERROR => { user => 'user/index.html', dbi => 'error/database', default => 'error/default', }, }); my $output = $service->process($template_name, \%replace) || die $service->error(), "\n"; =head1 DESCRIPTION The C<Template::Service> module implements an object class for providing a consistent template processing service. Standard header (L<PRE_PROCESS|PRE_PROCESS_POST_PROCESS>) and footer (L<POST_PROCESS|PRE_PROCESS_POST_PROCESS>) templates may be specified which are prepended and appended to all templates processed by the service (but not any other templates or blocks C<INCLUDE>d or C<PROCESS>ed from within). An L<ERROR> hash may be specified which redirects the service to an alternate template file in the case of uncaught exceptions being thrown. This allows errors to be automatically handled by the service and a guaranteed valid response to be generated regardless of any processing problems encountered. A default C<Template::Service> object is created by the L<Template> module. Any C<Template::Service> options may be passed to the L<Template> L<new()|Template#new()> constructor method and will be forwarded to the L<Template::Service> constructor. use Template; my $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }); Similarly, the C<Template::Service> constructor will forward all configuration parameters onto other default objects (e.g. L<Template::Context>) that it may need to instantiate. A C<Template::Service> object (or subclass) can be explicitly instantiated and passed to the L<Template> L<new()|Template#new()> constructor method as the L<SERVICE> item. use Template; use Template::Service; my $service = Template::Service->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }); my $template = Template->new({ SERVICE => $service, }); The C<Template::Service> module can be sub-classed to create custom service handlers. use Template; use MyOrg::Template::Service; my $service = MyOrg::Template::Service->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', COOL_OPTION => 'enabled in spades', }); my $template = Template->new({ SERVICE => $service, }); The L<Template> module uses the L<Template::Config> L<service()|Template::Config#service()> factory method to create a default service object when required. The C<$Template::Config::SERVICE> package variable may be set to specify an alternate service module. This will be loaded automatically and its L<new()> constructor method called by the L<service()|Template::Config#service()> factory method when a default service object is required. Thus the previous example could be written as: use Template; $Template::Config::SERVICE = 'MyOrg::Template::Service'; my $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', COOL_OPTION => 'enabled in spades', }); =head1 METHODS =head2 new(\%config) The C<new()> constructor method is called to instantiate a C<Template::Service> object. Configuration parameters may be specified as a HASH reference or as a list of C<name =E<gt> value> pairs. my $service1 = Template::Service->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }); my $service2 = Template::Service->new( ERROR => 'error.html' ); The C<new()> method returns a C<Template::Service> object or C<undef> on error. In the latter case, a relevant error message can be retrieved by the L<error()|Template::Base#error()> class method or directly from the C<$Template::Service::ERROR> package variable. my $service = Template::Service->new(\%config) || die Template::Service->error(); my $service = Template::Service->new(\%config) || die $Template::Service::ERROR; =head2 process($input, \%replace) The C<process()> method is called to process a template specified as the first parameter, C<$input>. This may be a file name, file handle (e.g. C<GLOB> or C<IO::Handle>) or a reference to a text string containing the template text. An additional hash reference may be passed containing template variable definitions. The method processes the template, adding any L<PRE_PROCESS|PRE_PROCESS_POST_PROCESS> or L<POST_PROCESS|PRE_PROCESS_POST_PROCESS> templates defined, and returns the output text. An uncaught exception thrown by the template will be handled by a relevant L<ERROR> handler if defined. Errors that occur in the L<PRE_PROCESS|PRE_PROCESS_POST_PROCESS> or L<POST_PROCESS|PRE_PROCESS_POST_PROCESS> templates, or those that occur in the main input template and aren't handled, cause the method to return C<undef> to indicate failure. The appropriate error message can be retrieved via the L<error()|Template::Base#error()> method. $service->process('myfile.html', { title => 'My Test File' }) || die $service->error(); =head2 context() Returns a reference to the internal context object which is, by default, an instance of the L<Template::Context> class. =head1 CONFIGURATION OPTIONS The following list summarises the configuration options that can be provided to the C<Template::Service> L<new()> constructor. Please consult L<Template::Manual::Config> for further details and examples of each configuration option in use. =head2 PRE_PROCESS, POST_PROCESS The L<PRE_PROCESS|Template::Manual::Config#PRE_PROCESS_POST_PROCESS> and L<POST_PROCESS|Template::Manual::Config#PRE_PROCESS_POST_PROCESS> options may be set to contain the name(s) of template files which should be processed immediately before and/or after each template. These do not get added to templates processed into a document via directives such as C<INCLUDE> C<PROCESS>, C<WRAPPER>, etc. my $service = Template::Service->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }; Multiple templates may be specified as a reference to a list. Each is processed in the order defined. my $service = Template::Service->new({ PRE_PROCESS => [ 'config', 'header' ], POST_PROCESS => 'footer', }; =head2 PROCESS The L<PROCESS|Template::Manual::Config#PROCESS> option may be set to contain the name(s) of template files which should be processed instead of the main template passed to the C<Template::Service> L<process()> method. This can be used to apply consistent wrappers around all templates, similar to the use of L<PRE_PROCESS|PRE_PROCESS_POST_PROCESS> and L<POST_PROCESS|PRE_PROCESS_POST_PROCESS> templates. my $service = Template::Service->new({ PROCESS => 'content', }; # processes 'content' instead of 'foo.html' $service->process('foo.html'); A reference to the original template is available in the C<template> variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by 'C<$>') to an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive. Example C<PROCESS> template: <html> <head> <title>[% template.title %]</title> </head> <body> [% PROCESS $template %] </body> </html> =head2 ERROR The L<ERROR|Template::Manual::Config#ERROR> (or C<ERRORS> if you prefer) configuration item can be used to name a single template or specify a hash array mapping exception types to templates which should be used for error handling. If an uncaught exception is raised from within a template then the appropriate error template will instead be processed. If specified as a single value then that template will be processed for all uncaught exceptions. my $service = Template::Service->new({ ERROR => 'error.html' }); If the L<ERROR or ERRORS|Template::Manual::Config#ERROR> item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A C<default> template may be provided for the general case. my $service = Template::Service->new({ ERRORS => { user => 'user/index.html', dbi => 'error/database', default => 'error/default', }, }); =head2 AUTO_RESET The L<AUTO_RESET|Template::Manual::Config#AUTO_RESET> option is set by default and causes the local C<BLOCKS> cache for the L<Template::Context> object to be reset on each call to the L<Template> L<process()|Template#process()> method. This ensures that any C<BLOCK>s defined within a template will only persist until that template is finished processing. =head2 DEBUG The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable debugging messages from the C<Template::Service> module by setting it to include the C<DEBUG_SERVICE> value. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_SERVICE, }); =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template>, L<Template::Context> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[Zcjy y lib/Template/Modules.podnu ��6�$ #============================================================= -*-perl-*- # # Template::Modules # # DESCRIPTION # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Modules - Template Toolkit Modules =head1 Template Toolkit Modules This documentation provides an overview of the different modules that comprise the Template Toolkit. =head2 Template The L<Template> module is the front-end to the Template Toolkit for Perl programmers. use Template; my $tt = Template->new(); $tt->process('hello.html', message => 'Hello World'); =head2 Template::Base The L<Template::Base> module implements a base class from which the other Template Toolkit modules are derived. It implements common functionality for creating objects, error reporting, debugging, and so on. =head2 Template::Config The L<Template::Config> module defines the configuration of the Template Toolkit for your system. It is an example of a I<factory module> which is responsible for instantiating the various other modules used in the Template Toolkit. For example, the L<Template::Config> module defines the C<$STASH> package variable which indicates which version of the L<Template::Stash> you are using by default. If you elected to use the faster L<XS|Template::Stash::XS> stash when you installed the Template Toolkit, then this will be set as: $STASH = 'Template::Stash::XS'; Otherwise you'll get the regular L<Perl|Template::Stash> stash: $STASH = 'Template::Stash'; This approach means that other parts of the Template Toolkit don't have to worry about which stash you're using. They just ask the L<Template::Config> module to create a stash of the right kind. =head2 Template::Constants The L<Template::Constants> defines a number of constants that are used by the Template Toolkit. For example, the C<:chomp> tagset defines the C<CHOMP_???> constants that can be used with the C<PRE_CHOMP> and C<POST_CHOMP> configuration options. use Template::Constants ':chomp'; my $tt = Template->new({ PRE_CHOMP => CHOMP_COLLAPSE, }); =head2 Template::Context The L<Template::Context> module defines a runtime context in which templates are processed. A context keeps track of all the templates, variables, plugins, and other resources that are available (either directly or through delegate objects) and provides methods to fetch, store, and perform various operations on them. =head2 Template::Document The L<Template::Document> module implements a compiled template document object. This is generated by the L<Template::Parser> module. =head2 Template::Exception The L<Template::Exception> module implements an exception object which is used for runtime error reporting. =head2 Template::Filters The L<Template::Filters> module implements a filter provider. It includes the core collection of filters that can be used via the C<FILTER> directive. =head2 Template::Iterator The L<Template::Iterator> module implements a data iterator which steps through each item in a list in turn. It is used by the C<FOREACH> directive. Within a C<FOREACH> block, the C<loop> variable always references the current iterator object. [% FOREACH item IN list; IF loop.first; # first item in loop ELSIF loop.last; # last item in loop ELSE; # any other item in loop END; END %] =head2 Template::Namespace::Constants The L<Template::Namespace::Constants> module is used internally to represent constants. These can be resolved immediately at the point that a template is compiled. =head2 Template::Parser The L<Template::Parser> module is used to parse a source template and turn it into Perl code which can be executed. =head2 Template::Plugin The L<Template::Plugin> module is a base class for Template Toolkit plugins that can be loaded on demand from within a template using the C<USE> directive. =head2 Template::Plugins The L<Template::Plugins> module is the plugins provider. It loads and prepares plugins as and when they are requested from within a template. =head2 Template::Provider The L<Template::Provider> module is responsible for loading, compiling and caching templates. =head2 Template::Service The L<Template::Service> module implements a service layer that sits just behind the L<Template> module, and just in front of a L<Template::Context>. It handles each request to process a template (forwarded from the L<Template> module). It adds any headers and/or footers (specified via the C<PRE_PROCESS> and C<POST_PROCESS> options), applies any wrapper (the C<WRAPPER> option) and catches any errors returned (the C<ERRORS> option). =head2 Template::Stash The L<Template::Stash> module is used to fetch and store template variables. It implements all of the magic associated with the dot operator. =head2 Template::Stash::XS The L<Template::Stash::XS> module is a high-speed implementation of L<Template::Stash> written in C. =head2 Template::Test The L<Template::Test> module is used to automate the Template Toolkit test scripts. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��H�V �V lib/Template/Test.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Test # # DESCRIPTION # Module defining a test harness which processes template input and # then compares the output against pre-define expected output. # Generates test output compatible with Test::Harness. This was # originally the t/texpect.pl script. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #============================================================================ package Template::Test; use strict; use warnings; use Template; use Exporter; use constant MSWin32 => $^O eq 'MSWin32'; our $VERSION = '3.100'; our $DEBUG = 0; our @ISA = qw( Exporter ); our @EXPORT = qw( ntests ok is match flush skip_all test_expect callsign banner ); our @EXPORT_OK = ( 'assert' ); our %EXPORT_TAGS = ( all => [ @EXPORT_OK, @EXPORT ] ); $| = 1; our $REASON = 'not applicable on this platform'; our $NO_FLUSH = 0; our $EXTRA = 0; # any extra tests to come after test_expect() our $PRESERVE = 0 # don't mangle newlines in output/expect unless defined $PRESERVE; our ($loaded, %callsign); # always set binmode on Win32 machines so that any output generated # is true to what we expect $Template::BINMODE = (MSWin32) ? 1 : 0; my @results = (); my ($ntests, $ok_count); *is = \&match; END { # ensure flush() is called to print any cached results flush(); } #------------------------------------------------------------------------ # ntests($n) # # Declare how many (more) tests are expected to come. If ok() is called # before ntests() then the results are cached instead of being printed # to STDOUT. When ntests() is called, the total number of tests # (including any cached) is known and the "1..$ntests" line can be # printed along with the cached results. After that, calls to ok() # generated printed output immediately. #------------------------------------------------------------------------ sub ntests { $ntests = shift; # add any pre-declared extra tests, or pre-stored test @results, to # the grand total of tests $ntests += $EXTRA + scalar @results; $ok_count = 1; print $ntests ? "1..$ntests\n" : "1..$ntests # skip $REASON\n"; # flush cached results foreach my $pre_test (@results) { ok(@$pre_test); } } #------------------------------------------------------------------------ # ok($truth, $msg) # # Tests the value passed for truth and generates an "ok $n" or "not ok $n" # line accordingly. If ntests() hasn't been called then we cached # results for later, instead. #------------------------------------------------------------------------ sub ok { my ($ok, $msg) = @_; # cache results if ntests() not yet called unless ($ok_count) { push(@results, [ $ok, $msg ]); return $ok; } $msg = defined $msg ? " - $msg" : ''; if ($ok) { print "ok ", $ok_count++, "$msg\n"; } else { print STDERR "FAILED $ok_count: $msg\n" if defined $msg; print "not ok ", $ok_count++, "$msg\n"; } } #------------------------------------------------------------------------ # assert($truth, $error) # # Test value for truth, die if false. #------------------------------------------------------------------------ sub assert { my ($ok, $err) = @_; return ok(1) if $ok; # failed my ($pkg, $file, $line) = caller(); $err ||= "assert failed"; $err .= " at $file line $line\n"; ok(0); die $err; } #------------------------------------------------------------------------ # match( $result, $expect ) #------------------------------------------------------------------------ sub match { my ($result, $expect, $msg) = @_; my $count = $ok_count ? $ok_count : scalar @results + 1; # force stringification of $result to avoid 'no eq method' overload errors $result = "$result" if ref $result; if ($result eq $expect) { return ok(1, $msg); } else { print STDERR "FAILED $count:\n expect: [$expect]\n result: [$result]\n"; return ok(0, $msg); } } #------------------------------------------------------------------------ # flush() # # Flush any tests results. #------------------------------------------------------------------------ sub flush { ntests(0) unless $ok_count || $NO_FLUSH; } #------------------------------------------------------------------------ # skip_all($reason) # # Skip all tests, setting $REASON to contain any message passed. Calls # exit(0) which triggers flush() which generates a "1..0 # $REASON" # string to keep to test harness happy. #------------------------------------------------------------------------ sub skip_all { $REASON = join('', @_); exit(0); } #------------------------------------------------------------------------ # test_expect($input, $template, \%replace) # # This is the main testing sub-routine. The $input parameter should be a # text string or a filehandle reference (e.g. GLOB or IO::Handle) from # which the input text can be read. The input should contain a number # of tests which are split up and processed individually, comparing the # generated output against the expected output. Tests should be defined # as follows: # # -- test -- # test input # -- expect -- # expected output # # -- test -- # etc... # # The number of tests is determined and ntests() is called to generate # the "0..$n" line compatible with Test::Harness. Each test input is # then processed by the Template object passed as the second parameter, # $template. This may also be a hash reference containing configuration # which are used to instantiate a Template object, or may be left # undefined in which case a default Template object will be instantiated. # The third parameter, also optional, may be a reference to a hash array # defining template variables. This is passed to the template process() # method. #------------------------------------------------------------------------ sub test_expect { my ($src, $tproc, $params) = @_; my ($input, @tests); my ($output, $expect, $match); my $count = 0; my $ttprocs; # read input text eval { local $/ = undef; $input = ref $src ? <$src> : $src; }; if ($@) { ntests(1); ok(0); warn "Cannot read input text from $src\n"; return undef; } # remove any comment lines $input =~ s/^#.*?\n//gm; # remove anything before '-- start --' and/or after '-- stop --' $input = $' if $input =~ /\s*--\s*start\s*--\s*/; $input = $` if $input =~ /\s*--\s*stop\s*--\s*/; @tests = split(/^\s*--\s*test\s*--\s*\n/im, $input); # if the first line of the file was '--test--' (optional) then the # first test will be empty and can be discarded shift(@tests) if $tests[0] =~ /^\s*$/; ntests(3 + scalar(@tests) * 2); # first test is that Template loaded OK, which it did ok(1, 'running test_expect()'); # optional second param may contain a Template reference or a HASH ref # of constructor options, or may be undefined if (ref($tproc) eq 'HASH') { # create Template object using hash of config items $tproc = Template->new($tproc) || die Template->error(), "\n"; } elsif (ref($tproc) eq 'ARRAY') { # list of [ name => $tproc, name => $tproc ], use first $tproc $ttprocs = { @$tproc }; $tproc = $tproc->[1]; } elsif (! ref $tproc) { $tproc = Template->new() || die Template->error(), "\n"; } # otherwise, we assume it's a Template reference # test: template processor created OK ok($tproc, 'template processor is engaged'); # third test is that the input read ok, which it did ok(1, 'input read and split into ' . scalar @tests . ' tests'); # the remaining tests are defined in @tests... foreach $input (@tests) { $count++; my $name = ''; if ($input =~ s/^\s*-- name:? (.*?) --\s*\n//im) { $name = $1; } else { $name = "template text $count"; } # Configure a test as TODO my $todo = ''; if ($input =~ s/^\s*-- todo:? (.*?) --\s*\n//im) { $todo = ( $1 eq '' ) ? 'No reason given' : $1; } # split input by a line like "-- expect --" ($input, $expect) = split(/^\s*--\s*expect\s*--\s*\n/im, $input); $expect = '' unless defined $expect; $output = ''; # input text may be prefixed with "-- use name --" to indicate a # Template object in the $ttproc hash which we should use if ($input =~ s/^\s*--\s*use\s+(\S+)\s*--\s*\n//im) { my $ttname = $1; my $ttlookup; if ($ttlookup = $ttprocs->{ $ttname }) { $tproc = $ttlookup; } else { warn "no such template object to use: $ttname\n"; } } # process input text $tproc->process(\$input, $params, \$output) || do { warn "Template process failed: ", $tproc->error(), "\n"; # report failure and automatically fail the expect match ok(0, "$name process FAILED: " . subtext($input)); ok(0, '(obviously did not match expected)'); next; }; # processed OK ok(1, "$name processed OK: " . subtext($input)); # another hack: if the '-- expect --' section starts with # '-- process --' then we process the expected output # before comparing it with the generated output. This is # slightly twisted but it makes it possible to run tests # where the expected output isn't static. See t/date.t for # an example. if ($expect =~ s/^\s*--+\s*process\s*--+\s*\n//im) { my $out; $tproc->process(\$expect, $params, \$out) || do { warn( "Template process failed (expect): ", $tproc->error(), "\n" ); # report failure and automatically fail the expect match ok( 0, "failed to process expected output [" . subtext($expect) . ']' ); next; }; $expect = $out; }; # strip any trailing blank lines from expected and real output foreach ($expect, $output) { s/[\n\r]*\Z//mg; } $match = ($expect eq $output) ? 1 : 0; if (! $match || $DEBUG) { print "MATCH FAILED\n" unless $match; my ($copyi, $copye, $copyo) = ($input, $expect, $output); unless ($PRESERVE) { foreach ($copyi, $copye, $copyo) { s/\n/\\n/g; } } printf( " input: [%s]\nexpect: [%s]\noutput: [%s]\n", $copyi, $copye, $copyo ); } my $testprefix = $name; if ( $todo ) { $testprefix = "# TODO $todo - $name"; } ok($match, $match ? "$testprefix matched expected" : "$testprefix did not match expected"); }; } #------------------------------------------------------------------------ # callsign() # # Returns a hash array mapping lower a..z to their phonetic alphabet # equivalent. #------------------------------------------------------------------------ sub callsign { my %callsign; @callsign{ 'a'..'z' } = qw( alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima mike november oscar papa quebec romeo sierra tango umbrella victor whisky x-ray yankee zulu ); return \%callsign; } #------------------------------------------------------------------------ # banner($text) # # Prints a banner with the specified text if $DEBUG is set. #------------------------------------------------------------------------ sub banner { return unless $DEBUG; my $text = join('', @_); my $count = $ok_count ? $ok_count - 1 : scalar @results; print "-" x 72, "\n$text ($count tests completed)\n", "-" x 72, "\n"; } sub subtext { my $text = shift; $text =~ s/\s*$//sg; $text = substr($text, 0, 32) . '...' if length $text > 32; $text =~ s/\n/\\n/g; return $text; } 1; __END__ =head1 NAME Template::Test - Module for automating TT2 test scripts =head1 SYNOPSIS use Template::Test; $Template::Test::DEBUG = 0; # set this true to see each test running $Template::Test::EXTRA = 2; # 2 extra tests follow test_expect()... # ok() can be called any number of times before test_expect ok( $true_or_false ) # test_expect() splits $input into individual tests, processes each # and compares generated output against expected output test_expect($input, $template, \%replace ); # $input is text or filehandle (e.g. DATA section after __END__) test_expect( $text ); test_expect( \*DATA ); # $template is a Template object or configuration hash my $template_cfg = { ... }; test_expect( $input, $template_cfg ); my $template_obj = Template->new($template_cfg); test_expect( $input, $template_obj ); # $replace is a hash reference of template variables my $replace = { a => 'alpha', b => 'bravo' }; test_expect( $input, $template, $replace ); # ok() called after test_expect should be declared in $EXTRA (2) ok( $true_or_false ) ok( $true_or_false ) =head1 DESCRIPTION The C<Template::Test> module defines the L<test_expect()> and other related subroutines which can be used to automate test scripts for the Template Toolkit. See the numerous tests in the F<t> sub-directory of the distribution for examples of use. =head1 PACKAGE SUBROUTINES =head2 text_expect() The C<test_expect()> subroutine splits an input document into a number of separate tests, processes each one using the Template Toolkit and then compares the generated output against an expected output, also specified in the input document. It generates the familiar C<ok>/C<not ok> output compatible with C<Test::Harness>. The test input should be specified as a text string or a reference to a filehandle (e.g. C<GLOB> or C<IO::Handle>) from which it can be read. In particular, this allows the test input to be placed after the C<__END__> marker and read via the C<DATA> filehandle. use Template::Test; test_expect(\*DATA); __END__ # this is the first test (this is a comment) -- test -- blah blah blah [% foo %] -- expect -- blah blah blah value_of_foo # here's the second test (no surprise, so is this) -- test -- more blah blah [% bar %] -- expect -- more blah blah value_of_bar Blank lines between test sections are generally ignored. Any line starting with C<#> is treated as a comment and is ignored. The second and third parameters to C<test_expect()> are optional. The second may be either a reference to a Template object which should be used to process the template fragments, or a reference to a hash array containing configuration values which should be used to instantiate a new Template object. # pass reference to config hash my $config = { INCLUDE_PATH => '/here/there:/every/where', POST_CHOMP => 1, }; test_expect(\*DATA, $config); # or create Template object explicitly my $template = Template->new($config); test_expect(\*DATA, $template); The third parameter may be used to reference a hash array of template variable which should be defined when processing the tests. This is passed to the L<Template> L<process()|Template#process()> method. my $replace = { a => 'alpha', b => 'bravo', }; test_expect(\*DATA, $config, $replace); The second parameter may be left undefined to specify a default L<Template> configuration. test_expect(\*DATA, undef, $replace); For testing the output of different L<Template> configurations, a reference to a list of named L<Template> objects also may be passed as the second parameter. my $tt1 = Template->new({ ... }); my $tt2 = Template->new({ ... }); my @tts = [ one => $tt1, two => $tt1 ]; The first object in the list is used by default. Other objects may be switched in with a 'C<-- use $name -->' marker. This should immediately follow a 'C<-- test -->' line. That object will then be used for the rest of the test, or until a different object is selected. -- test -- -- use one -- [% blah %] -- expect -- blah, blah -- test -- still using one... -- expect -- ... -- test -- -- use two -- [% blah %] -- expect -- blah, blah, more blah The C<test_expect()> sub counts the number of tests, and then calls L<ntests()> to generate the familiar "C<1..$ntests\n>" test harness line. Each test defined generates two test numbers. The first indicates that the input was processed without error, and the second that the output matches that expected. Additional test may be run before C<test_expect()> by calling L<ok()>. These test results are cached until L<ntests()> is called and the final number of tests can be calculated. Then, the "C<1..$ntests>" line is output, along with "C<ok $n>" / "C<not ok $n>" lines for each of the cached test result. Subsequent calls to L<ok()> then generate an output line immediately. my $something = SomeObject->new(); ok( $something ); my $other = AnotherThing->new(); ok( $other ); test_expect(\*DATA); If any tests are to follow after C<test_expect()> is called then these should be pre-declared by setting the C<$EXTRA> package variable. This value (default: C<0>) is added to the grand total calculated by L<ntests()>. The results of the additional tests are also registered by calling L<ok()>. $Template::Test::EXTRA = 2; # can call ok() any number of times before test_expect() ok( $did_that_work ); ok( $make_sure ); ok( $dead_certain ); # <some> number of tests... test_expect(\*DATA, $config, $replace); # here's those $EXTRA tests ok( defined $some_result && ref $some_result eq 'ARRAY' ); ok( $some_result->[0] eq 'some expected value' ); If you don't want to call C<test_expect()> at all then you can call C<ntests($n)> to declare the number of tests and generate the test header line. After that, simply call L<ok()> for each test passing a true or false values to indicate that the test passed or failed. ntests(2); ok(1); ok(0); If you're really lazy, you can just call L<ok()> and not bother declaring the number of tests at all. All tests results will be cached until the end of the script and then printed in one go before the program exits. ok( $x ); ok( $y ); You can identify only a specific part of the input file for testing using the 'C<-- start -->' and 'C<-- stop -->' markers. Anything before the first 'C<-- start -->' is ignored, along with anything after the next 'C<-- stop -->' marker. -- test -- this is test 1 (not performed) -- expect -- this is test 1 (not performed) -- start -- -- test -- this is test 2 -- expect -- this is test 2 -- stop -- ... =head2 ntests() Subroutine used to specify how many tests you're expecting to run. =head2 ok($test) Generates an "C<ok $n>" or "C<not ok $n>" message if C<$test> is true or false. =head2 not_ok($test) The logical inverse of L<ok()>. Prints an "C<ok $n>" message is C<$test> is I<false> and vice-versa. =head2 callsign() For historical reasons and general utility, the module also defines a C<callsign()> subroutine which returns a hash mapping the letters C<a> to C<z> to their phonetic alphabet equivalent (e.g. radio callsigns). This is used by many of the test scripts as a known source of variable values. test_expect(\*DATA, $config, callsign()); =head2 banner() This subroutine prints a simple banner including any text passed as parameters. The C<$DEBUG> variable must be set for it to generate any output. banner('Testing something-or-other'); example output: #------------------------------------------------------------ # Testing something-or-other (27 tests completed) #------------------------------------------------------------ =head1 PACKAGE VARIABLES =head2 $DEBUG The $DEBUG package variable can be set to enable debugging mode. =head2 $PRESERVE The $PRESERVE package variable can be set to stop the test_expect() from converting newlines in the output and expected output into the literal strings '\n'. =head1 HISTORY This module started its butt-ugly life as the C<t/texpect.pl> script. It was cleaned up to became the C<Template::Test> module some time around version 0.29. It underwent further cosmetic surgery for version 2.00 but still retains some remarkable rear-end resemblances. Since then the C<Test::More> and related modules have appeared on CPAN making this module mostly, but not entirely, redundant. =head1 BUGS / KNOWN "FEATURES" Imports all methods by default. This is generally a Bad Thing, but this module is only used in test scripts (i.e. at build time) so a) we don't really care and b) it saves typing. The line splitter may be a bit dumb, especially if it sees lines like C<-- this --> that aren't supposed to be special markers. So don't do that. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[¬�jx" x" lib/Template/FAQ.podnu ��6�$ #============================================================= -*-perl-*- # # Template::FAQ # # DESCRIPTION # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. #======================================================================== =head1 NAME Template::FAQ - Frequently Asked Questions about the Template Toolkit =head1 Template Toolkit Language =head2 Why doesn't [% a = b IF c %] work as expected? There's a limitation in the TT2 parser which means that the following code doesn't work as you might expect: [% a = b IF c %] The parser interprets it as an attempt to set C<a> to the result of C<b IF c>, like this: [% a = (b IF c) %] If you want to set C<a = b> only if C<c> is true, then do this instead: [% SET a = b IF c %] The explicit C<SET> keyword gives the parser the clue it needs to do the right thing. NOTE: this will be fixed in TT3 =head2 If I'm using TT to write out a TT template, is there a good way to escape [% and %]? You can do something like this: [% stag = "[\%" etag = "%\]" %] and then: [% stag; 'hello'; etag %] Or you can use the C<TAGS> directive, like so: [% TAGS [- -] %] [- INCLUDE foo -] # is a directive [% INCLUDE foo %] # not a directive =head2 How do I iterate over a hash? This is covered in the L<Template::Manual::VMethods> section of the manual. A list of all the keys that are in the hash can be obtained with the C<keys> virtual method. You can then iterate over that list and by looking up each key in turn get the value. [% FOREACH key = product.keys %] [% key %] => [% product.$key %] [% END %] =head1 Plugins =head2 How do I get the Table plugin to order data across rather than down? Order the data into rows: Steve Karen Jeff Brooklyn Nantucket Fairfax NY MA VA [% USE table(data, rows=3) %] Then ask for each column [% FOREACH column = table.cols %] And then print each item in the column going across the output rows [% FOREACH item = column %] <td>[% item %]</td> [% END %] =head2 Accessing Cookies Jeff Boes E<lt>jboes@nexcerpt.comE<gt> asks: Does anyone have a quick-n-dirty approach to accessing cookies from templates? Jonas Liljegren answers: [% USE CGI %] <p>The value is [% CGI.cookie('cookie_name') | html %] You will need to have L<Template::Plugin::CGI> installed. =head1 Extending the Template Toolkit =head2 Can I serve templates from a database? Short answer: yes, Chris Nandor has done this for Slash. You need to subclass L<Template::Provider>. See the mailing list archives for further info. =head2 Can I fetch templates via http? To do the job properly, you should subclass L<Template::Provider> to C<Template::Provider::HTTP> and use a C<PREFIX_MAP> option to bind the C<http> template prefix to that particular provider (you may want to go digging around in the F<Changes> file around version 2.01 for more info on C<PREFIX_MAP> - it may not be properly documented anywhere else...yet!). e.g. use Template::Provider::HTTP; my $file = Template::Provider( INCLUDE_PATH => [...] ); my $http = Template::Provider::HTTP->new(...); my $tt2 = Template->new({ LOAD_TEMPLATES => [ $file, $http ], PREFIX_MAP => { file => '0', # file:foo.html http => '1', # http:foo.html default => '0', # foo.html => file:foo.html } }); Now a template specified as: [% INCLUDE foo %] will be served by the 'file' provider (the default). Otherwise you can explicitly add a prefix: [% INCLUDE file:foo.html %] [% INCLUDE http:foo.html %] [% INCLUDE http://www.xyz.com/tt2/header.tt2 %] This same principal can be used to create a DBI template provider. e.g. [% INCLUDE dbi:foo.html %] Alas, we don't yet have a DBI provider as part of the Template Toolkit. There has been some talk on the mailing list about efforts to develop DBI and/or HTTP providers but as yet no-one has stepped forward to take up the challenge... In the mean time, Craig Barrat's post from the mailing list has some useful pointers on how to achieve this using existing modules. See L<http://tt2.org/pipermail/templates/2001-May/000954.html> =head1 Miscellaneous =head2 How can I find out the name of the main template being processed? The C<template> variable contains a reference to the Template::Document object for the main template you're processing (i.e. the one provided as the first argument to the Template process() method). The C<name> method returns its name. [% template.name %] # e.g. index.html =head2 How can I find out the name of the current template being processed? The C<template> variable always references the I<main> template being processed. So even if you call [% INCLUDE header %], and that calls [% INCLUDE menu %], the C<template> variable will be unchanged. index.html: [% template.name %] # index.html [% INCLUDE header %] header: [% template.name %] # index.html [% INCLUDE menu %] menu: [% template.name %] # index.html In contrast, the C<component> variable always references the I<current> template being processed. index.html [% component.name %] # index.html [% INCLUDE header %] header: [% component.name %] # header [% INCLUDE menu %] menu: [% component.name %] # menu =head2 How do I print the modification time of the template or component? The C<template> and C<component> variables reference the main template and the current template being processed (see previous questions). The C<modtime> method returns the modification time of the corresponding template file as a number of seconds since the Unix epoch (00:00:00 GMT 1st January 1970). This number doesn't mean much to anyone (except perhaps serious Unix geeks) so you'll probably want to use the Date plugin to format it for human consumption. [% USE Date %] [% template.name %] last modified [% Date.format(template.modtime) %] =head2 How can I configure variables on a per-request basis? One easy way to achieve this is to define a single C<PRE_PROCESS> template which loads in other configuration files based on variables defined or other conditions. For example, my setup usually looks something like this: PRE_PROCESS => 'config/main' config/main: [% DEFAULT style = 'text' section = template.section or 'home'; PROCESS config/site + config/urls + config/macros + "config/style/$style" + "config/section/$section" + ... %] This allows me to set a single 'style' variable to control which config file gets pre-processed to set my various style options (colours, img paths, etc). For example: config/style/basic: [% style = { name = style # save existing 'style' var as 'style.name' # define various other style variables.... col = { back => '#ffffff' text => '#000000' # ...etc... } logo = { # ...etc... } # ...etc... } %] Each source template can declare which section it's in via a META directive: [% META title = 'General Information' section = 'info' %] ... This controls which section configuration file gets loaded to set various other variables for defining the section title, menu, etc. config/section/info: [% section = { name = section # save 'section' var as 'section.name' title = 'Information' menu = [ ... ] # ...etc... } %] This illustrates the basic principal but you can extend it to perform pretty much any kind of per-document initialisation that you require. =head2 Why do I get rubbish for my utf-8 templates? First of all, make sure that your template files define a Byte Order Mark L<http://en.wikipedia.org/wiki/Byte_Order_Mark> If you for some reason don't want to add BOM to your templates, you can force Template to use a particular encoding (e.g. C<utf8>) for your templates with the C<ENCODING> option. my $template = Template->new({ ENCODING => 'utf8' }); =head1 Questions About This FAQ =head2 Why is this FAQ so short? Because we don't have anyone maintaining it. =head2 Can I help? Yes please :-) =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[��`1h h lib/Template/Base.pmnu ��6�$ #============================================================= -*-perl-*- # # Template::Base # # DESCRIPTION # Base class module implementing common functionality for various other # Template Toolkit modules. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== package Template::Base; use strict; use warnings; use Template::Constants; our $VERSION = '3.100'; #------------------------------------------------------------------------ # new(\%params) # # General purpose constructor method which expects a hash reference of # configuration parameters, or a list of name => value pairs which are # folded into a hash. Blesses a hash into an object and calls its # _init() method, passing the parameter hash reference. Returns a new # object derived from Template::Base, or undef on error. #------------------------------------------------------------------------ sub new { my $class = shift; my ($argnames, @args, $arg, $cfg); # $class->error(''); # always clear package $ERROR var? { no strict 'refs'; no warnings 'once'; $argnames = \@{"$class\::BASEARGS"} || [ ]; } # shift off all mandatory args, returning error if undefined or null foreach $arg (@$argnames) { return $class->error("no $arg specified") unless ($cfg = shift); push(@args, $cfg); } # fold all remaining args into a hash, or use provided hash ref $cfg = defined $_[0] && ref($_[0]) eq 'HASH' ? shift : { @_ }; my $self = bless { (map { ($_ => shift @args) } @$argnames), _ERROR => '', DEBUG => 0, }, $class; return $self->_init($cfg) ? $self : $class->error($self->error); } #------------------------------------------------------------------------ # error() # error($msg, ...) # # May be called as a class or object method to set or retrieve the # package variable $ERROR (class method) or internal member # $self->{ _ERROR } (object method). The presence of parameters indicates # that the error value should be set. Undef is then returned. In the # absence of parameters, the current error value is returned. #------------------------------------------------------------------------ sub error { my $self = shift; my $errvar; { no strict qw( refs ); $errvar = ref $self ? \$self->{ _ERROR } : \${"$self\::ERROR"}; } if (@_) { $$errvar = ref($_[0]) ? shift : join('', @_); return undef; } else { return $$errvar; } } #------------------------------------------------------------------------ # _init() # # Initialisation method called by the new() constructor and passing a # reference to a hash array containing any configuration items specified # as constructor arguments. Should return $self on success or undef on # error, via a call to the error() method to set the error message. #------------------------------------------------------------------------ sub _init { my ($self, $config) = @_; return $self; } sub debug { my $self = shift; my $msg = join('', @_); my ($pkg, $file, $line) = caller(); unless (substr($msg,-1) eq "\n") { $msg .= ($self->{ DEBUG } & Template::Constants::DEBUG_CALLER) ? " at $file line $line\n" : "\n"; } print STDERR "[$pkg] $msg"; } #------------------------------------------------------------------------ # module_version() # # Returns the current version number. #------------------------------------------------------------------------ sub module_version { my $self = shift; my $class = ref $self || $self; no strict 'refs'; return ${"${class}::VERSION"}; } sub DESTROY { 1 } # noop 1; __END__ =head1 NAME Template::Base - Base class module implementing common functionality =head1 SYNOPSIS package My::Module; use base qw( Template::Base ); sub _init { my ($self, $config) = @_; $self->{ doodah } = $config->{ doodah } || return $self->error("No 'doodah' specified"); return $self; } package main; my $object = My::Module->new({ doodah => 'foobar' }) || die My::Module->error(); =head1 DESCRIPTION Base class module which implements a constructor and error reporting functionality for various Template Toolkit modules. =head1 PUBLIC METHODS =head2 new(\%config) Constructor method which accepts a reference to a hash array or a list of C<name =E<gt> value> parameters which are folded into a hash. The C<_init()> method is then called, passing the configuration hash and should return true/false to indicate success or failure. A new object reference is returned, or undef on error. Any error message raised can be examined via the L<error()> class method or directly via the C<$ERROR> package variable in the derived class. my $module = My::Module->new({ ... }) || die My::Module->error(), "\n"; my $module = My::Module->new({ ... }) || die "constructor error: $My::Module::ERROR\n"; =head2 error($msg, ...) May be called as an object method to get/set the internal C<_ERROR> member or as a class method to get/set the C<$ERROR> variable in the derived class's package. my $module = My::Module->new({ ... }) || die My::Module->error(), "\n"; $module->do_something() || die $module->error(), "\n"; When called with parameters (multiple params are concatenated), this method will set the relevant variable and return undef. This is most often used within object methods to report errors to the caller. package My::Module; sub foobar { my $self = shift; # some other code... return $self->error('some kind of error...') if $some_condition; } =head2 debug($msg, ...) Generates a debugging message by concatenating all arguments passed into a string and printing it to C<STDERR>. A prefix is added to indicate the module of the caller. package My::Module; sub foobar { my $self = shift; $self->debug('called foobar()'); # some other code... } When the C<foobar()> method is called, the following message is sent to C<STDERR>: [My::Module] called foobar() Objects can set an internal C<DEBUG> value which the C<debug()> method will examine. If this value sets the relevant bits to indicate C<DEBUG_CALLER> then the file and line number of the caller will be append to the message. use Template::Constants qw( :debug ); my $module = My::Module->new({ DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER, }); $module->foobar(); This generates an error message such as: [My::Module] called foobar() at My/Module.pm line 6 =head2 module_version() Returns the version number for a module, as defined by the C<$VERSION> package variable. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[�@�� � lib/Template/Grammar.pmnu ��6�$ #============================================================= -*-Perl-*- # # Template::Grammar # # DESCRIPTION # Grammar file for the Template Toolkit language containing token # definitions and parser state/rules tables generated by Parse::Yapp. # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. # Copyright (C) 1998-2000 Canon Research Centre Europe Ltd. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # IMPORTANT NOTE # This module is constructed from the parser/Grammar.pm.skel file by # running the parser/yc script. You only need to do this if # you # have modified the grammar in the parser/Parser.yp file and need # # to-recompile it. See the README in the 'parser' directory for # more information (sub-directory of the Template distribution). # #======================================================================== package Template::Grammar; use strict; use warnings; our $VERSION = '3.100'; my (@RESERVED, %CMPOP, $LEXTABLE, $RULES, $STATES); my ($factory, $rawstart); #======================================================================== # Reserved words, comparison and binary operators #======================================================================== BEGIN { @RESERVED = qw( GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER BLOCK END USE PLUGIN FILTER MACRO PERL RAWPERL TO STEP AND OR NOT DIV MOD IF UNLESS ELSE ELSIF FOR NEXT WHILE SWITCH CASE META IN TRY THROW CATCH FINAL LAST RETURN STOP CLEAR VIEW DEBUG ); # for historical reasons, != and == are converted to ne and eq to perform # stringwise comparison (mainly because it doesn't generate "non-numerical # comparison" warnings which != and == can) but the others (e.g. < > <= >=) # are not converted to their stringwise equivalents. I added 'gt' et al, # briefly for v2.04d and then took them out again in 2.04e. %CMPOP = qw( != ne == eq < < > > >= >= <= <= ); # eq eq # add these lines to the above to # lt lt # enable the eq, lt and gt operators # gt gt #======================================================================== # Lexer Token Table #======================================================================== # lookup table used by lexer is initialised with special-cases $LEXTABLE = { 'FOREACH' => 'FOR', 'BREAK' => 'LAST', '&&' => 'AND', '||' => 'OR', '!' => 'NOT', '|' => 'FILTER', '.' => 'DOT', '_' => 'CAT', '..' => 'TO', # ':' => 'MACRO', '=' => 'ASSIGN', '=>' => 'ASSIGN', # '->' => 'ARROW', ',' => 'COMMA', '\\' => 'REF', 'and' => 'AND', # explicitly specified so that qw( and or 'or' => 'OR', # not ) can always be used in lower case, 'not' => 'NOT', # regardless of ANYCASE flag 'mod' => 'MOD', 'div' => 'DIV', }; # localise the temporary variables needed to complete lexer table { my @tokens = qw< ( ) [ ] { } ${ $ + / ; : ? >; my @cmpop = keys %CMPOP; my @binop = qw( - * % ); # '+' and '/' above, in @tokens # fill lexer table, slice by slice, with reserved words and operators @$LEXTABLE{ @RESERVED, @cmpop, @binop, @tokens } = ( @RESERVED, ('CMPOP') x @cmpop, ('BINOP') x @binop, @tokens ); } } # --- END BEGIN #======================================================================== # CLASS METHODS #======================================================================== sub new { my $class = shift; bless { LEXTABLE => $LEXTABLE, STATES => $STATES, RULES => $RULES, }, $class; } # update method to set package-scoped $factory lexical sub install_factory { my ($self, $new_factory) = @_; $factory = $new_factory; } BEGIN { #======================================================================== # States #======================================================================== $STATES = [ {#State 0 ACTIONS => { 'INSERT' => 66, 'TRY' => 67, 'FILTER' => 68, 'WHILE' => 60, 'USE' => 59, "(" => 61, "{" => 62, 'PERL' => 46, "\"" => 47, "\$" => 48, 'SET' => 52, 'META' => 53, 'NEXT' => 49, 'IF' => 34, 'INCLUDE' => 43, 'RAWPERL' => 44, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'GET' => 27, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17, 'NOT' => 12, 'IDENT' => 13, 'WRAPPER' => 19, 'CLEAR' => 20, 'RETURN' => 22, "\${" => 21, ";" => -18, 'TEXT' => 7, 'CALL' => 8, 'MACRO' => 10, 'UNLESS' => 9, 'DEFAULT' => 2, 'PROCESS' => 4 }, DEFAULT => -3, GOTOS => { 'loop' => 45, 'statement' => 11, 'template' => 54, 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'atomexpr' => 35, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'block' => 1, 'lterm' => 42, 'try' => 5, 'view' => 40, 'ident' => 24, 'condition' => 33, 'perl' => 73, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'node' => 57, 'term' => 15, 'wrapper' => 56, 'capture' => 55, 'assign' => 18, 'expr' => 58, 'chunks' => 63, 'defblock' => 65, 'switch' => 64 } }, {#State 1 DEFAULT => -1 }, {#State 2 ACTIONS => { 'IDENT' => 13, 'LITERAL' => 75, "\${" => 21, "\$" => 48 }, GOTOS => { 'item' => 29, 'ident' => 74, 'assign' => 18, 'node' => 57, 'setlist' => 76 } }, {#State 3 DEFAULT => -15 }, {#State 4 ACTIONS => { "\$" => 79, "\"" => 80, 'LITERAL' => 82, 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83 }, GOTOS => { 'names' => 78, 'name' => 86, 'filename' => 87, 'filepart' => 77, 'nameargs' => 85 } }, {#State 5 DEFAULT => -24 }, {#State 6 ACTIONS => { ";" => -20 }, DEFAULT => -27 }, {#State 7 DEFAULT => -6 }, {#State 8 ACTIONS => { 'REF' => 17, 'NOT' => 12, 'IDENT' => 13, "\${" => 21, "[" => 41, "{" => 62, "(" => 61, "\$" => 48, "\"" => 47, 'NUMBER' => 23, 'LITERAL' => 89 }, GOTOS => { 'ident' => 88, 'node' => 57, 'term' => 15, 'sterm' => 36, 'item' => 29, 'expr' => 90, 'lterm' => 42 } }, {#State 9 ACTIONS => { 'LITERAL' => 89, "\${" => 21, "(" => 61, "{" => 62, "[" => 41, "\"" => 47, "\$" => 48, 'REF' => 17, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13 }, GOTOS => { 'expr' => 91, 'ident' => 88, 'item' => 29, 'lterm' => 42, 'term' => 15, 'sterm' => 36, 'node' => 57 } }, {#State 10 ACTIONS => { 'IDENT' => 92 } }, {#State 11 ACTIONS => { ";" => 93 } }, {#State 12 ACTIONS => { "(" => 61, "{" => 62, "[" => 41, 'LITERAL' => 89, "\${" => 21, 'NUMBER' => 23, 'IDENT' => 13, 'NOT' => 12, "\"" => 47, 'REF' => 17, "\$" => 48 }, GOTOS => { 'lterm' => 42, 'sterm' => 36, 'term' => 15, 'node' => 57, 'expr' => 94, 'ident' => 88, 'item' => 29 } }, {#State 13 DEFAULT => -130 }, {#State 14 DEFAULT => -39 }, {#State 15 DEFAULT => -146 }, {#State 16 ACTIONS => { "\$" => 79, "\"" => 80, 'LITERAL' => 82, 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83 }, GOTOS => { 'names' => 78, 'filename' => 87, 'name' => 86, 'filepart' => 77, 'nameargs' => 95 } }, {#State 17 ACTIONS => { 'IDENT' => 13, "\${" => 21, "\$" => 48 }, GOTOS => { 'item' => 29, 'ident' => 96, 'node' => 57 } }, {#State 18 DEFAULT => -149 }, {#State 19 ACTIONS => { 'LITERAL' => 82, "\$" => 79, "\"" => 80, 'IDENT' => 84, 'NUMBER' => 83, 'FILENAME' => 81 }, GOTOS => { 'filename' => 87, 'name' => 86, 'names' => 78, 'nameargs' => 97, 'filepart' => 77 } }, {#State 20 DEFAULT => -38 }, {#State 21 ACTIONS => { 'NUMBER' => 23, 'IDENT' => 13, "\"" => 47, "\$" => 48, 'REF' => 17, 'LITERAL' => 89, "\${" => 21 }, GOTOS => { 'ident' => 88, 'item' => 29, 'sterm' => 98, 'node' => 57 } }, {#State 22 DEFAULT => -36 }, {#State 23 DEFAULT => -113 }, {#State 24 ACTIONS => { 'ASSIGN' => 99, 'DOT' => 100 }, DEFAULT => -109 }, {#State 25 ACTIONS => { 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83, "\$" => 79, "\"" => 80, 'LITERAL' => 82 }, GOTOS => { 'name' => 86, 'filename' => 87, 'names' => 78, 'nameargs' => 101, 'filepart' => 77 } }, {#State 26 ACTIONS => { 'IDENT' => 13, 'NOT' => 12, 'REF' => 17, "{" => 62, "[" => 41, "(" => 61, "\${" => 21, 'NUMBER' => 23, "\$" => 48, "\"" => 47, 'LITERAL' => 89 }, GOTOS => { 'lterm' => 42, 'node' => 57, 'term' => 15, 'sterm' => 36, 'ident' => 88, 'expr' => 102, 'item' => 29 } }, {#State 27 ACTIONS => { 'LITERAL' => 89, "\"" => 47, "\$" => 48, 'NUMBER' => 23, "\${" => 21, "(" => 61, "{" => 62, "[" => 41, 'REF' => 17, 'NOT' => 12, 'IDENT' => 13 }, GOTOS => { 'sterm' => 36, 'term' => 15, 'node' => 57, 'lterm' => 42, 'item' => 29, 'expr' => 103, 'ident' => 88 } }, {#State 28 DEFAULT => -10 }, {#State 29 ACTIONS => { "(" => 104 }, DEFAULT => -128 }, {#State 30 ACTIONS => { 'NUMBER' => 23, 'IDENT' => 107, "\"" => 47, "\$" => 48, 'REF' => 17, "[" => 41, "{" => 62, 'LITERAL' => 89, "\${" => 21 }, GOTOS => { 'sterm' => 36, 'term' => 106, 'node' => 57, 'loopvar' => 105, 'lterm' => 42, 'item' => 29, 'ident' => 88 } }, {#State 31 ACTIONS => { 'ASSIGN' => 108 }, DEFAULT => -112 }, {#State 32 ACTIONS => { 'LITERAL' => 110, 'NUMBER' => 83, 'IDENT' => 109, 'FILENAME' => 81 }, DEFAULT => -87, GOTOS => { 'blockname' => 112, 'filepart' => 77, 'filename' => 114, 'blockargs' => 111, 'meta' => 113, 'metadata' => 115 } }, {#State 33 DEFAULT => -21 }, {#State 34 ACTIONS => { 'LITERAL' => 89, "\${" => 21, "(" => 61, "[" => 41, "{" => 62, "\"" => 47, "\$" => 48, 'REF' => 17, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13 }, GOTOS => { 'lterm' => 42, 'sterm' => 36, 'term' => 15, 'node' => 57, 'expr' => 116, 'ident' => 88, 'item' => 29 } }, {#State 35 ACTIONS => { 'IF' => 122, 'WRAPPER' => 117, 'FOR' => 118, 'UNLESS' => 119, 'FILTER' => 121, 'WHILE' => 120 } }, {#State 36 DEFAULT => -104 }, {#State 37 ACTIONS => { "\$" => 48, 'IDENT' => 13, 'COMMA' => 124, 'LITERAL' => 75, "\${" => 21 }, DEFAULT => -19, GOTOS => { 'node' => 57, 'assign' => 123, 'ident' => 74, 'item' => 29 } }, {#State 38 ACTIONS => { 'LITERAL' => 82, "\$" => 79, "\"" => 80, 'IDENT' => 84, 'NUMBER' => 83, 'FILENAME' => 81 }, GOTOS => { 'names' => 78, 'filename' => 87, 'name' => 86, 'filepart' => 77, 'nameargs' => 125 } }, {#State 39 DEFAULT => -37 }, {#State 40 DEFAULT => -14 }, {#State 41 ACTIONS => { "\${" => 21, 'LITERAL' => 89, "{" => 62, "[" => 41, "\$" => 48, 'REF' => 17, "\"" => 47, 'IDENT' => 13, 'NUMBER' => 23, "]" => 126 }, GOTOS => { 'term' => 127, 'sterm' => 128, 'node' => 57, 'ident' => 88, 'lterm' => 42, 'range' => 130, 'list' => 129, 'item' => 29 } }, {#State 42 DEFAULT => -103 }, {#State 43 ACTIONS => { 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83, "\$" => 79, "\"" => 80, 'LITERAL' => 82 }, GOTOS => { 'nameargs' => 131, 'filepart' => 77, 'name' => 86, 'filename' => 87, 'names' => 78 } }, {#State 44 DEFAULT => -78, GOTOS => { '@5-1' => 132 } }, {#State 45 DEFAULT => -23 }, {#State 46 ACTIONS => { ";" => 133 } }, {#State 47 DEFAULT => -176, GOTOS => { 'quoted' => 134 } }, {#State 48 ACTIONS => { 'IDENT' => 135 } }, {#State 49 DEFAULT => -40 }, {#State 50 ACTIONS => { 'IDENT' => 136 }, DEFAULT => -87, GOTOS => { 'metadata' => 115, 'blockargs' => 137, 'meta' => 113 } }, {#State 51 DEFAULT => -8 }, {#State 52 ACTIONS => { 'LITERAL' => 75, "\${" => 21, "\$" => 48, 'IDENT' => 13 }, GOTOS => { 'node' => 57, 'setlist' => 138, 'item' => 29, 'assign' => 18, 'ident' => 74 } }, {#State 53 ACTIONS => { 'IDENT' => 136 }, GOTOS => { 'meta' => 113, 'metadata' => 139 } }, {#State 54 ACTIONS => { '' => 140 } }, {#State 55 DEFAULT => -11 }, {#State 56 DEFAULT => -42 }, {#State 57 DEFAULT => -127 }, {#State 58 ACTIONS => { 'CAT' => 147, 'AND' => 149, 'CMPOP' => 148, "+" => 150, 'MOD' => 141, 'BINOP' => 145, "/" => 144, ";" => -16, "?" => 142, 'OR' => 143, 'DIV' => 146 }, DEFAULT => -26 }, {#State 59 ACTIONS => { "\$" => 151, "\"" => 152, "\${" => 21, 'LITERAL' => 155, 'FILENAME' => 81, 'IDENT' => 157, 'NUMBER' => 83 }, GOTOS => { 'item' => 156, 'filepart' => 77, 'names' => 78, 'nameargs' => 158, 'lvalue' => 154, 'lnameargs' => 153, 'name' => 86, 'filename' => 87 } }, {#State 60 ACTIONS => { "(" => 61, "[" => 41, "{" => 62, 'LITERAL' => 89, "\${" => 21, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13, "\"" => 47, 'REF' => 17, "\$" => 48 }, GOTOS => { 'item' => 29, 'ident' => 88, 'expr' => 159, 'node' => 57, 'term' => 15, 'sterm' => 36, 'lterm' => 42 } }, {#State 61 ACTIONS => { "\"" => 47, "\$" => 48, 'REF' => 17, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13, 'LITERAL' => 31, "\${" => 21, "(" => 61, "[" => 41, "{" => 62 }, GOTOS => { 'item' => 29, 'assign' => 161, 'expr' => 160, 'lterm' => 42, 'ident' => 162, 'node' => 57, 'sterm' => 36, 'term' => 15 } }, {#State 62 ACTIONS => { "\$" => 48, 'LITERAL' => 163, "\${" => 21, 'IDENT' => 13 }, DEFAULT => -119, GOTOS => { 'item' => 165, 'params' => 167, 'param' => 164, 'hash' => 166 } }, {#State 63 ACTIONS => { "\"" => 47, "\$" => 48, 'PERL' => 46, 'META' => 53, 'SET' => 52, 'NEXT' => 49, 'IF' => 34, 'INCLUDE' => 43, 'RAWPERL' => 44, "[" => 41, 'THROW' => 38, 'STOP' => 39, 'INSERT' => 66, 'TRY' => 67, 'FILTER' => 68, "(" => 61, "{" => 62, 'WHILE' => 60, 'USE' => 59, ";" => -18, 'CALL' => 8, 'TEXT' => 7, 'UNLESS' => 9, 'MACRO' => 10, 'DEFAULT' => 2, 'PROCESS' => 4, 'GET' => 27, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'REF' => 17, 'DEBUG' => 16, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13, 'WRAPPER' => 19, "\${" => 21, 'RETURN' => 22, 'CLEAR' => 20 }, DEFAULT => -2, GOTOS => { 'term' => 15, 'node' => 57, 'wrapper' => 56, 'capture' => 55, 'expr' => 58, 'assign' => 18, 'switch' => 64, 'defblock' => 65, 'ident' => 24, 'condition' => 33, 'perl' => 73, 'filter' => 69, 'anonblock' => 28, 'macro' => 70, 'item' => 29, 'chunk' => 168, 'use' => 72, 'atomexpr' => 35, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'lterm' => 42, 'view' => 40, 'try' => 5, 'loop' => 45, 'statement' => 11, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51 } }, {#State 64 DEFAULT => -22 }, {#State 65 DEFAULT => -9 }, {#State 66 ACTIONS => { 'FILENAME' => 81, 'NUMBER' => 83, 'IDENT' => 84, "\"" => 80, "\$" => 79, 'LITERAL' => 82 }, GOTOS => { 'nameargs' => 169, 'filepart' => 77, 'filename' => 87, 'name' => 86, 'names' => 78 } }, {#State 67 ACTIONS => { ";" => 170 } }, {#State 68 ACTIONS => { "\$" => 151, "\"" => 152, "\${" => 21, 'LITERAL' => 155, 'FILENAME' => 81, 'IDENT' => 157, 'NUMBER' => 83 }, GOTOS => { 'filename' => 87, 'name' => 86, 'lnameargs' => 171, 'lvalue' => 154, 'nameargs' => 158, 'names' => 78, 'filepart' => 77, 'item' => 156 } }, {#State 69 DEFAULT => -43 }, {#State 70 DEFAULT => -12 }, {#State 71 DEFAULT => -5 }, {#State 72 DEFAULT => -13 }, {#State 73 DEFAULT => -25 }, {#State 74 ACTIONS => { 'ASSIGN' => 172, 'DOT' => 100 } }, {#State 75 ACTIONS => { 'ASSIGN' => 108 } }, {#State 76 ACTIONS => { "\$" => 48, 'COMMA' => 124, 'LITERAL' => 75, 'IDENT' => 13, "\${" => 21 }, DEFAULT => -31, GOTOS => { 'node' => 57, 'ident' => 74, 'assign' => 123, 'item' => 29 } }, {#State 77 DEFAULT => -171 }, {#State 78 ACTIONS => { "(" => 173, "+" => 175 }, DEFAULT => -156, GOTOS => { 'args' => 174 } }, {#State 79 ACTIONS => { 'IDENT' => 13, "\${" => 21, "\$" => 48 }, GOTOS => { 'node' => 57, 'ident' => 176, 'item' => 29 } }, {#State 80 DEFAULT => -176, GOTOS => { 'quoted' => 177 } }, {#State 81 DEFAULT => -172 }, {#State 82 DEFAULT => -169 }, {#State 83 DEFAULT => -174 }, {#State 84 DEFAULT => -173 }, {#State 85 DEFAULT => -34 }, {#State 86 DEFAULT => -166 }, {#State 87 ACTIONS => { 'DOT' => 178 }, DEFAULT => -168 }, {#State 88 ACTIONS => { 'DOT' => 100 }, DEFAULT => -109 }, {#State 89 DEFAULT => -112 }, {#State 90 ACTIONS => { 'MOD' => 141, 'BINOP' => 145, "/" => 144, "?" => 142, 'OR' => 143, 'DIV' => 146, 'CAT' => 147, 'AND' => 149, 'CMPOP' => 148, "+" => 150 }, DEFAULT => -29 }, {#State 91 ACTIONS => { "+" => 150, 'CMPOP' => 148, 'AND' => 149, 'CAT' => 147, 'DIV' => 146, 'OR' => 143, "?" => 142, ";" => 179, "/" => 144, 'BINOP' => 145, 'MOD' => 141 } }, {#State 92 ACTIONS => { 'NEXT' => 49, 'CALL' => 8, 'UNLESS' => 9, 'SET' => 52, 'PERL' => 46, "\"" => 47, "\$" => 48, 'THROW' => 38, 'STOP' => 39, 'PROCESS' => 4, "[" => 41, 'INCLUDE' => 43, 'IF' => 34, 'DEFAULT' => 2, 'FILTER' => 68, 'FOR' => 30, 'BLOCK' => 180, 'LITERAL' => 31, 'NUMBER' => 23, 'INSERT' => 66, 'TRY' => 67, 'SWITCH' => 26, 'GET' => 27, 'WHILE' => 60, "(" => 183, "{" => 62, 'WRAPPER' => 19, 'RETURN' => 22, 'CLEAR' => 20, "\${" => 21, 'IDENT' => 13, 'NOT' => 12, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17 }, GOTOS => { 'atomexpr' => 35, 'node' => 57, 'setlist' => 37, 'term' => 15, 'sterm' => 36, 'wrapper' => 56, 'lterm' => 42, 'assign' => 18, 'expr' => 182, 'try' => 5, 'switch' => 64, 'ident' => 162, 'mdir' => 181, 'loop' => 45, 'perl' => 73, 'condition' => 33, 'atomdir' => 6, 'filter' => 69, 'directive' => 184, 'item' => 29 } }, {#State 93 DEFAULT => -7 }, {#State 94 ACTIONS => { 'MOD' => 141, "/" => 144, 'BINOP' => 145, 'DIV' => 146, 'CMPOP' => 148, 'CAT' => 147, "+" => 150 }, DEFAULT => -142 }, {#State 95 DEFAULT => -41 }, {#State 96 ACTIONS => { 'DOT' => 100 }, DEFAULT => -110 }, {#State 97 ACTIONS => { ";" => 185 } }, {#State 98 ACTIONS => { "}" => 186 } }, {#State 99 ACTIONS => { 'INSERT' => 66, 'NUMBER' => 23, 'TRY' => 67, 'SWITCH' => 26, 'GET' => 27, 'FILTER' => 68, 'FOR' => 30, 'BLOCK' => 180, 'LITERAL' => 31, 'NOT' => 12, 'IDENT' => 13, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'WHILE' => 60, "(" => 61, "{" => 62, 'WRAPPER' => 19, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'PERL' => 46, "\"" => 47, "\$" => 48, 'NEXT' => 49, 'CALL' => 8, 'UNLESS' => 9, 'SET' => 52, 'IF' => 34, 'DEFAULT' => 2, 'THROW' => 38, 'STOP' => 39, 'PROCESS' => 4, "[" => 41, 'INCLUDE' => 43 }, GOTOS => { 'ident' => 162, 'mdir' => 188, 'loop' => 45, 'condition' => 33, 'perl' => 73, 'filter' => 69, 'atomdir' => 6, 'item' => 29, 'directive' => 184, 'atomexpr' => 35, 'sterm' => 36, 'term' => 15, 'setlist' => 37, 'node' => 57, 'wrapper' => 56, 'lterm' => 42, 'expr' => 187, 'assign' => 18, 'try' => 5, 'switch' => 64 } }, {#State 100 ACTIONS => { "\${" => 21, "\$" => 48, 'NUMBER' => 190, 'IDENT' => 13 }, GOTOS => { 'node' => 189, 'item' => 29 } }, {#State 101 ACTIONS => { ";" => 191 } }, {#State 102 ACTIONS => { "/" => 144, 'CMPOP' => 148, 'BINOP' => 145, 'AND' => 149, 'MOD' => 141, 'CAT' => 147, 'DIV' => 146, 'OR' => 143, "+" => 150, "?" => 142, ";" => 192 } }, {#State 103 ACTIONS => { 'BINOP' => 145, "/" => 144, 'MOD' => 141, 'OR' => 143, 'DIV' => 146, "?" => 142, 'AND' => 149, 'CMPOP' => 148, 'CAT' => 147, "+" => 150 }, DEFAULT => -28 }, {#State 104 DEFAULT => -156, GOTOS => { 'args' => 193 } }, {#State 105 ACTIONS => { ";" => 194 } }, {#State 106 DEFAULT => -156, GOTOS => { 'args' => 195 } }, {#State 107 ACTIONS => { 'IN' => 197, 'ASSIGN' => 196 }, DEFAULT => -130 }, {#State 108 ACTIONS => { 'IDENT' => 13, 'NOT' => 12, 'NUMBER' => 23, "\$" => 48, 'REF' => 17, "\"" => 47, "[" => 41, "{" => 62, "(" => 61, "\${" => 21, 'LITERAL' => 89 }, GOTOS => { 'item' => 29, 'ident' => 88, 'expr' => 198, 'node' => 57, 'sterm' => 36, 'term' => 15, 'lterm' => 42 } }, {#State 109 ACTIONS => { 'ASSIGN' => 199 }, DEFAULT => -173 }, {#State 110 DEFAULT => -85 }, {#State 111 ACTIONS => { ";" => 200 } }, {#State 112 DEFAULT => -83 }, {#State 113 DEFAULT => -99 }, {#State 114 ACTIONS => { 'DOT' => 178 }, DEFAULT => -84 }, {#State 115 ACTIONS => { 'IDENT' => 136, 'COMMA' => 201 }, DEFAULT => -86, GOTOS => { 'meta' => 202 } }, {#State 116 ACTIONS => { 'BINOP' => 145, "/" => 144, 'MOD' => 141, 'OR' => 143, 'DIV' => 146, ";" => 203, "?" => 142, 'AND' => 149, 'CMPOP' => 148, 'CAT' => 147, "+" => 150 } }, {#State 117 ACTIONS => { 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83, "\$" => 79, "\"" => 80, 'LITERAL' => 82 }, GOTOS => { 'filepart' => 77, 'nameargs' => 204, 'names' => 78, 'name' => 86, 'filename' => 87 } }, {#State 118 ACTIONS => { "\"" => 47, "\$" => 48, 'REF' => 17, 'NUMBER' => 23, 'IDENT' => 107, 'LITERAL' => 89, "\${" => 21, "{" => 62, "[" => 41 }, GOTOS => { 'loopvar' => 205, 'lterm' => 42, 'term' => 106, 'sterm' => 36, 'node' => 57, 'ident' => 88, 'item' => 29 } }, {#State 119 ACTIONS => { "\"" => 47, "\$" => 48, 'NUMBER' => 23, 'LITERAL' => 89, 'REF' => 17, 'NOT' => 12, 'IDENT' => 13, "\${" => 21, "(" => 61, "{" => 62, "[" => 41 }, GOTOS => { 'lterm' => 42, 'expr' => 206, 'item' => 29, 'node' => 57, 'term' => 15, 'sterm' => 36, 'ident' => 88 } }, {#State 120 ACTIONS => { "(" => 61, "{" => 62, "[" => 41, 'LITERAL' => 89, "\${" => 21, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13, "\"" => 47, "\$" => 48, 'REF' => 17 }, GOTOS => { 'item' => 29, 'expr' => 207, 'ident' => 88, 'sterm' => 36, 'term' => 15, 'node' => 57, 'lterm' => 42 } }, {#State 121 ACTIONS => { "\"" => 152, "\$" => 151, 'LITERAL' => 155, "\${" => 21, 'FILENAME' => 81, 'NUMBER' => 83, 'IDENT' => 157 }, GOTOS => { 'lvalue' => 154, 'lnameargs' => 208, 'nameargs' => 158, 'filename' => 87, 'name' => 86, 'filepart' => 77, 'item' => 156, 'names' => 78 } }, {#State 122 ACTIONS => { "[" => 41, "{" => 62, "(" => 61, "\${" => 21, 'LITERAL' => 89, 'IDENT' => 13, 'NOT' => 12, 'NUMBER' => 23, 'REF' => 17, "\$" => 48, "\"" => 47 }, GOTOS => { 'lterm' => 42, 'item' => 29, 'expr' => 209, 'term' => 15, 'sterm' => 36, 'node' => 57, 'ident' => 88 } }, {#State 123 DEFAULT => -147 }, {#State 124 DEFAULT => -148 }, {#State 125 DEFAULT => -35 }, {#State 126 DEFAULT => -107 }, {#State 127 DEFAULT => -116 }, {#State 128 ACTIONS => { 'TO' => 210 }, DEFAULT => -104 }, {#State 129 ACTIONS => { 'COMMA' => 211, 'LITERAL' => 89, "\"" => 47, "\$" => 48, 'NUMBER' => 23, "\${" => 21, "{" => 62, "[" => 41, 'REF' => 17, "]" => 212, 'IDENT' => 13 }, GOTOS => { 'ident' => 88, 'item' => 29, 'lterm' => 42, 'sterm' => 36, 'term' => 213, 'node' => 57 } }, {#State 130 ACTIONS => { "]" => 214 } }, {#State 131 DEFAULT => -33 }, {#State 132 ACTIONS => { ";" => 215 } }, {#State 133 DEFAULT => -76, GOTOS => { '@4-2' => 216 } }, {#State 134 ACTIONS => { "\$" => 48, "\"" => 221, ";" => 220, "\${" => 21, 'TEXT' => 219, 'IDENT' => 13 }, GOTOS => { 'node' => 57, 'quotable' => 218, 'item' => 29, 'ident' => 217 } }, {#State 135 DEFAULT => -132 }, {#State 136 ACTIONS => { 'ASSIGN' => 199 } }, {#State 137 ACTIONS => { ";" => 222 } }, {#State 138 ACTIONS => { 'LITERAL' => 75, 'COMMA' => 124, "\$" => 48, "\${" => 21, 'IDENT' => 13 }, DEFAULT => -30, GOTOS => { 'node' => 57, 'ident' => 74, 'assign' => 123, 'item' => 29 } }, {#State 139 ACTIONS => { 'IDENT' => 136, 'COMMA' => 201 }, DEFAULT => -17, GOTOS => { 'meta' => 202 } }, {#State 140 DEFAULT => 0 }, {#State 141 ACTIONS => { 'NOT' => 12, 'IDENT' => 13, 'NUMBER' => 23, "\$" => 48, 'REF' => 17, "\"" => 47, "[" => 41, "{" => 62, "(" => 61, "\${" => 21, 'LITERAL' => 89 }, GOTOS => { 'item' => 29, 'expr' => 223, 'ident' => 88, 'sterm' => 36, 'term' => 15, 'node' => 57, 'lterm' => 42 } }, {#State 142 ACTIONS => { 'LITERAL' => 89, 'NUMBER' => 23, "\$" => 48, "\"" => 47, "[" => 41, "{" => 62, "(" => 61, "\${" => 21, 'IDENT' => 13, 'NOT' => 12, 'REF' => 17 }, GOTOS => { 'node' => 57, 'term' => 15, 'sterm' => 36, 'ident' => 88, 'lterm' => 42, 'item' => 29, 'expr' => 224 } }, {#State 143 ACTIONS => { 'NOT' => 12, 'IDENT' => 13, 'REF' => 17, "(" => 61, "[" => 41, "{" => 62, "\${" => 21, 'NUMBER' => 23, "\"" => 47, "\$" => 48, 'LITERAL' => 89 }, GOTOS => { 'lterm' => 42, 'expr' => 225, 'item' => 29, 'node' => 57, 'term' => 15, 'sterm' => 36, 'ident' => 88 } }, {#State 144 ACTIONS => { "\$" => 48, 'REF' => 17, "\"" => 47, 'IDENT' => 13, 'NOT' => 12, 'NUMBER' => 23, "\${" => 21, 'LITERAL' => 89, "[" => 41, "{" => 62, "(" => 61 }, GOTOS => { 'ident' => 88, 'node' => 57, 'term' => 15, 'sterm' => 36, 'expr' => 226, 'item' => 29, 'lterm' => 42 } }, {#State 145 ACTIONS => { "\$" => 48, "\"" => 47, 'NUMBER' => 23, 'LITERAL' => 89, 'REF' => 17, 'IDENT' => 13, 'NOT' => 12, "\${" => 21, "[" => 41, "{" => 62, "(" => 61 }, GOTOS => { 'item' => 29, 'ident' => 88, 'expr' => 227, 'node' => 57, 'term' => 15, 'sterm' => 36, 'lterm' => 42 } }, {#State 146 ACTIONS => { 'LITERAL' => 89, 'NUMBER' => 23, "\$" => 48, "\"" => 47, "{" => 62, "[" => 41, "(" => 61, "\${" => 21, 'NOT' => 12, 'IDENT' => 13, 'REF' => 17 }, GOTOS => { 'node' => 57, 'sterm' => 36, 'term' => 15, 'lterm' => 42, 'item' => 29, 'ident' => 88, 'expr' => 228 } }, {#State 147 ACTIONS => { 'REF' => 17, "\$" => 48, "\"" => 47, 'IDENT' => 13, 'NOT' => 12, 'NUMBER' => 23, "\${" => 21, 'LITERAL' => 89, "[" => 41, "{" => 62, "(" => 61 }, GOTOS => { 'expr' => 229, 'item' => 29, 'lterm' => 42, 'ident' => 88, 'node' => 57, 'sterm' => 36, 'term' => 15 } }, {#State 148 ACTIONS => { 'NUMBER' => 23, "\$" => 48, "\"" => 47, 'LITERAL' => 89, 'NOT' => 12, 'IDENT' => 13, 'REF' => 17, "{" => 62, "[" => 41, "(" => 61, "\${" => 21 }, GOTOS => { 'ident' => 88, 'node' => 57, 'term' => 15, 'sterm' => 36, 'expr' => 230, 'item' => 29, 'lterm' => 42 } }, {#State 149 ACTIONS => { 'LITERAL' => 89, 'NUMBER' => 23, "\"" => 47, "\$" => 48, "(" => 61, "{" => 62, "[" => 41, "\${" => 21, 'IDENT' => 13, 'NOT' => 12, 'REF' => 17 }, GOTOS => { 'lterm' => 42, 'item' => 29, 'expr' => 231, 'node' => 57, 'sterm' => 36, 'term' => 15, 'ident' => 88 } }, {#State 150 ACTIONS => { "\${" => 21, "(" => 61, "{" => 62, "[" => 41, 'REF' => 17, 'IDENT' => 13, 'NOT' => 12, 'LITERAL' => 89, "\"" => 47, "\$" => 48, 'NUMBER' => 23 }, GOTOS => { 'lterm' => 42, 'sterm' => 36, 'term' => 15, 'node' => 57, 'expr' => 232, 'ident' => 88, 'item' => 29 } }, {#State 151 ACTIONS => { "\${" => 21, "\$" => 48, 'IDENT' => 233 }, GOTOS => { 'ident' => 176, 'item' => 29, 'node' => 57 } }, {#State 152 DEFAULT => -176, GOTOS => { 'quoted' => 234 } }, {#State 153 DEFAULT => -73 }, {#State 154 ACTIONS => { 'ASSIGN' => 235 } }, {#State 155 ACTIONS => { 'ASSIGN' => -161 }, DEFAULT => -169 }, {#State 156 DEFAULT => -159 }, {#State 157 ACTIONS => { 'ASSIGN' => -130 }, DEFAULT => -173 }, {#State 158 DEFAULT => -158 }, {#State 159 ACTIONS => { ";" => 236, "?" => 142, "+" => 150, 'OR' => 143, 'DIV' => 146, 'CAT' => 147, 'MOD' => 141, 'AND' => 149, 'BINOP' => 145, 'CMPOP' => 148, "/" => 144 } }, {#State 160 ACTIONS => { 'OR' => 143, 'DIV' => 146, ")" => 237, "?" => 142, 'BINOP' => 145, "/" => 144, 'MOD' => 141, "+" => 150, 'AND' => 149, 'CMPOP' => 148, 'CAT' => 147 } }, {#State 161 ACTIONS => { ")" => 238 } }, {#State 162 ACTIONS => { 'DOT' => 100, 'ASSIGN' => 172 }, DEFAULT => -109 }, {#State 163 ACTIONS => { 'ASSIGN' => 239 } }, {#State 164 DEFAULT => -122 }, {#State 165 ACTIONS => { 'ASSIGN' => 240 } }, {#State 166 ACTIONS => { "}" => 241 } }, {#State 167 ACTIONS => { "\${" => 21, 'LITERAL' => 163, 'COMMA' => 243, 'IDENT' => 13, "\$" => 48 }, DEFAULT => -118, GOTOS => { 'param' => 242, 'item' => 165 } }, {#State 168 DEFAULT => -4 }, {#State 169 DEFAULT => -32 }, {#State 170 ACTIONS => { "\"" => 47, "\$" => 48, 'PERL' => 46, 'META' => 53, 'SET' => 52, 'NEXT' => 49, 'IF' => 34, 'INCLUDE' => 43, 'RAWPERL' => 44, "[" => 41, 'THROW' => 38, 'STOP' => 39, 'INSERT' => 66, 'TRY' => 67, 'FILTER' => 68, "(" => 61, "{" => 62, 'WHILE' => 60, 'USE' => 59, ";" => -18, 'TEXT' => 7, 'CALL' => 8, 'UNLESS' => 9, 'MACRO' => 10, 'DEFAULT' => 2, 'PROCESS' => 4, 'GET' => 27, 'NUMBER' => 23, 'SWITCH' => 26, 'VIEW' => 25, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13, 'WRAPPER' => 19, 'CLEAR' => 20, 'RETURN' => 22, "\${" => 21 }, DEFAULT => -3, GOTOS => { 'expr' => 58, 'assign' => 18, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'capture' => 55, 'wrapper' => 56, 'term' => 15, 'node' => 57, 'filter' => 69, 'macro' => 70, 'anonblock' => 28, 'item' => 29, 'chunk' => 71, 'use' => 72, 'perl' => 73, 'condition' => 33, 'ident' => 24, 'view' => 40, 'try' => 5, 'lterm' => 42, 'block' => 244, 'atomexpr' => 35, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51, 'statement' => 11, 'loop' => 45 } }, {#State 171 ACTIONS => { ";" => 245 } }, {#State 172 ACTIONS => { "\"" => 47, 'REF' => 17, "\$" => 48, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13, 'LITERAL' => 89, "\${" => 21, "(" => 61, "{" => 62, "[" => 41 }, GOTOS => { 'term' => 15, 'sterm' => 36, 'node' => 57, 'lterm' => 42, 'item' => 29, 'expr' => 246, 'ident' => 88 } }, {#State 173 DEFAULT => -156, GOTOS => { 'args' => 247 } }, {#State 174 ACTIONS => { "\${" => 21, "[" => 41, "{" => 62, "(" => 61, 'REF' => 17, 'IDENT' => 13, 'NOT' => 12, 'COMMA' => 253, 'LITERAL' => 249, "\$" => 48, "\"" => 47, 'NUMBER' => 23 }, DEFAULT => -163, GOTOS => { 'node' => 57, 'term' => 15, 'sterm' => 36, 'ident' => 252, 'lterm' => 42, 'item' => 250, 'param' => 251, 'expr' => 248 } }, {#State 175 ACTIONS => { 'NUMBER' => 83, 'IDENT' => 84, 'FILENAME' => 81, 'LITERAL' => 82, "\"" => 80 }, GOTOS => { 'filepart' => 77, 'name' => 254, 'filename' => 87 } }, {#State 176 ACTIONS => { 'DOT' => 100 }, DEFAULT => -156, GOTOS => { 'args' => 255 } }, {#State 177 ACTIONS => { "\$" => 48, ";" => 220, "\"" => 256, 'IDENT' => 13, "\${" => 21, 'TEXT' => 219 }, GOTOS => { 'quotable' => 218, 'node' => 57, 'ident' => 217, 'item' => 29 } }, {#State 178 ACTIONS => { 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83 }, GOTOS => { 'filepart' => 257 } }, {#State 179 ACTIONS => { 'NEXT' => 49, 'SET' => 52, 'META' => 53, 'PERL' => 46, "\"" => 47, "\$" => 48, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'INCLUDE' => 43, 'RAWPERL' => 44, 'IF' => 34, 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'WHILE' => 60, 'USE' => 59, "(" => 61, "{" => 62, 'CALL' => 8, 'TEXT' => 7, 'UNLESS' => 9, 'MACRO' => 10, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2, 'FOR' => 30, 'LITERAL' => 31, 'BLOCK' => 32, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'GET' => 27, 'WRAPPER' => 19, "\${" => 21, 'RETURN' => 22, 'CLEAR' => 20, 'NOT' => 12, 'IDENT' => 13, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17 }, DEFAULT => -3, GOTOS => { 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'atomexpr' => 35, 'block' => 258, 'lterm' => 42, 'try' => 5, 'view' => 40, 'loop' => 45, 'statement' => 11, 'directive' => 51, 'defblockname' => 50, 'atomdir' => 6, 'node' => 57, 'term' => 15, 'capture' => 55, 'wrapper' => 56, 'chunks' => 63, 'switch' => 64, 'defblock' => 65, 'assign' => 18, 'expr' => 58, 'ident' => 24, 'perl' => 73, 'condition' => 33, 'use' => 72, 'item' => 29, 'chunk' => 71, 'macro' => 70, 'anonblock' => 28, 'filter' => 69 } }, {#State 180 ACTIONS => { ";" => 259 } }, {#State 181 DEFAULT => -91 }, {#State 182 ACTIONS => { "+" => 150, 'CAT' => 147, 'AND' => 149, 'CMPOP' => 148, "?" => 142, 'OR' => 143, 'DIV' => 146, 'MOD' => 141, 'BINOP' => 145, "/" => 144 }, DEFAULT => -26 }, {#State 183 ACTIONS => { 'REF' => 17, "\$" => 48, "\"" => 47, 'NOT' => 12, 'IDENT' => 260, 'NUMBER' => 23, "\${" => 21, 'LITERAL' => 31, "[" => 41, "{" => 62, "(" => 61 }, GOTOS => { 'lterm' => 42, 'item' => 29, 'expr' => 160, 'assign' => 161, 'sterm' => 36, 'term' => 15, 'node' => 57, 'margs' => 261, 'ident' => 162 } }, {#State 184 DEFAULT => -92 }, {#State 185 ACTIONS => { 'PROCESS' => 4, 'DEFAULT' => 2, 'MACRO' => 10, 'UNLESS' => 9, 'TEXT' => 7, 'CALL' => 8, ";" => -18, "\${" => 21, 'CLEAR' => 20, 'RETURN' => 22, 'WRAPPER' => 19, 'REF' => 17, 'DEBUG' => 16, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'GET' => 27, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'INCLUDE' => 43, 'RAWPERL' => 44, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'IF' => 34, 'META' => 53, 'SET' => 52, 'NEXT' => 49, "\$" => 48, "\"" => 47, 'PERL' => 46, "{" => 62, "(" => 61, 'WHILE' => 60, 'USE' => 59, 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66 }, DEFAULT => -3, GOTOS => { 'expr' => 58, 'assign' => 18, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'capture' => 55, 'wrapper' => 56, 'term' => 15, 'node' => 57, 'filter' => 69, 'macro' => 70, 'anonblock' => 28, 'item' => 29, 'chunk' => 71, 'use' => 72, 'perl' => 73, 'condition' => 33, 'ident' => 24, 'view' => 40, 'try' => 5, 'lterm' => 42, 'block' => 262, 'atomexpr' => 35, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51, 'statement' => 11, 'loop' => 45 } }, {#State 186 DEFAULT => -131 }, {#State 187 ACTIONS => { 'BINOP' => 145, "/" => 144, 'COMMA' => -150, 'MOD' => 141, 'LITERAL' => -150, 'OR' => 143, 'DIV' => 146, "\$" => -150, ";" => -150, "?" => 142, 'AND' => 149, 'CMPOP' => 148, "\${" => -150, 'CAT' => 147, 'IDENT' => -150, "+" => 150 }, DEFAULT => -26 }, {#State 188 DEFAULT => -89 }, {#State 189 DEFAULT => -125 }, {#State 190 DEFAULT => -126 }, {#State 191 DEFAULT => -74, GOTOS => { '@3-3' => 263 } }, {#State 192 ACTIONS => { ";" => -18, 'UNLESS' => 9, 'MACRO' => 10, 'CALL' => 8, 'TEXT' => 7, 'DEFAULT' => 2, 'PROCESS' => 4, 'GET' => 27, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'WRAPPER' => 19, "\$" => 48, "\"" => 47, 'PERL' => 46, 'META' => 53, 'SET' => 52, 'NEXT' => 49, 'IF' => 34, 'INCLUDE' => 43, 'RAWPERL' => 44, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'TRY' => 67, 'INSERT' => 66, 'FILTER' => 68, "{" => 62, "(" => 61, 'USE' => 59, 'WHILE' => 60 }, DEFAULT => -3, GOTOS => { 'wrapper' => 56, 'capture' => 55, 'node' => 57, 'term' => 15, 'assign' => 18, 'expr' => 58, 'switch' => 64, 'chunks' => 63, 'defblock' => 65, 'ident' => 24, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'condition' => 33, 'perl' => 73, 'block' => 264, 'atomexpr' => 35, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'try' => 5, 'view' => 40, 'lterm' => 42, 'loop' => 45, 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'statement' => 11 } }, {#State 193 ACTIONS => { "\${" => 21, "(" => 61, "[" => 41, "{" => 62, 'REF' => 17, 'NOT' => 12, 'IDENT' => 13, 'LITERAL' => 249, 'COMMA' => 253, "\"" => 47, ")" => 265, "\$" => 48, 'NUMBER' => 23 }, GOTOS => { 'lterm' => 42, 'sterm' => 36, 'term' => 15, 'node' => 57, 'expr' => 248, 'param' => 251, 'ident' => 252, 'item' => 250 } }, {#State 194 DEFAULT => -56, GOTOS => { '@1-3' => 266 } }, {#State 195 ACTIONS => { 'REF' => 17, 'IDENT' => 13, 'NOT' => 12, "\${" => 21, "[" => 41, "{" => 62, "(" => 61, "\$" => 48, "\"" => 47, 'NUMBER' => 23, 'LITERAL' => 249, 'COMMA' => 253 }, DEFAULT => -64, GOTOS => { 'expr' => 248, 'ident' => 252, 'param' => 251, 'item' => 250, 'lterm' => 42, 'term' => 15, 'sterm' => 36, 'node' => 57 } }, {#State 196 ACTIONS => { "{" => 62, "[" => 41, "\${" => 21, 'LITERAL' => 89, 'IDENT' => 13, 'NUMBER' => 23, 'REF' => 17, "\$" => 48, "\"" => 47 }, GOTOS => { 'sterm' => 36, 'term' => 267, 'node' => 57, 'ident' => 88, 'lterm' => 42, 'item' => 29 } }, {#State 197 ACTIONS => { "[" => 41, "{" => 62, 'LITERAL' => 89, "\${" => 21, 'NUMBER' => 23, 'IDENT' => 13, "\"" => 47, 'REF' => 17, "\$" => 48 }, GOTOS => { 'ident' => 88, 'node' => 57, 'term' => 268, 'sterm' => 36, 'item' => 29, 'lterm' => 42 } }, {#State 198 ACTIONS => { 'OR' => 143, "?" => 142, 'MOD' => 141, 'AND' => 149, 'DIV' => 146, "/" => 144, 'BINOP' => 145, "+" => 150, 'CMPOP' => 148, 'CAT' => 147 }, DEFAULT => -151 }, {#State 199 ACTIONS => { "\"" => 269, 'LITERAL' => 270, 'NUMBER' => 271 } }, {#State 200 ACTIONS => { 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66, "{" => 62, "(" => 61, 'USE' => 59, 'WHILE' => 60, 'NEXT' => 49, 'META' => 53, 'SET' => 52, "\$" => 48, "\"" => 47, 'PERL' => 46, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'RAWPERL' => 44, 'INCLUDE' => 43, 'IF' => 34, 'FOR' => 30, 'LITERAL' => 31, 'BLOCK' => 32, 'GET' => 27, 'SWITCH' => 26, 'VIEW' => 25, 'NUMBER' => 23, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'WRAPPER' => 19, 'IDENT' => 13, 'NOT' => 12, 'REF' => 17, 'DEBUG' => 16, 'LAST' => 14, 'UNLESS' => 9, 'MACRO' => 10, 'TEXT' => 7, 'CALL' => 8, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2 }, DEFAULT => -3, GOTOS => { 'perl' => 73, 'condition' => 33, 'use' => 72, 'chunk' => 71, 'item' => 29, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'ident' => 24, 'defblock' => 65, 'chunks' => 63, 'switch' => 64, 'assign' => 18, 'expr' => 58, 'node' => 57, 'term' => 15, 'wrapper' => 56, 'capture' => 55, 'statement' => 11, 'directive' => 51, 'defblockname' => 50, 'atomdir' => 6, 'loop' => 45, 'lterm' => 42, 'try' => 5, 'view' => 40, 'rawperl' => 3, 'setlist' => 37, 'sterm' => 36, 'atomexpr' => 35, 'block' => 272 } }, {#State 201 DEFAULT => -98 }, {#State 202 DEFAULT => -97 }, {#State 203 ACTIONS => { "{" => 62, "(" => 61, 'WHILE' => 60, 'USE' => 59, 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66, 'RAWPERL' => 44, 'INCLUDE' => 43, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'IF' => 34, 'META' => 53, 'SET' => 52, 'NEXT' => 49, "\$" => 48, "\"" => 47, 'PERL' => 46, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'WRAPPER' => 19, 'REF' => 17, 'DEBUG' => 16, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'GET' => 27, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'PROCESS' => 4, 'DEFAULT' => 2, 'UNLESS' => 9, 'MACRO' => 10, 'TEXT' => 7, 'CALL' => 8, ";" => -18 }, DEFAULT => -3, GOTOS => { 'loop' => 45, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51, 'statement' => 11, 'block' => 273, 'atomexpr' => 35, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'view' => 40, 'try' => 5, 'lterm' => 42, 'ident' => 24, 'filter' => 69, 'macro' => 70, 'anonblock' => 28, 'item' => 29, 'chunk' => 71, 'use' => 72, 'condition' => 33, 'perl' => 73, 'capture' => 55, 'wrapper' => 56, 'term' => 15, 'node' => 57, 'expr' => 58, 'assign' => 18, 'switch' => 64, 'chunks' => 63, 'defblock' => 65 } }, {#State 204 DEFAULT => -66 }, {#State 205 DEFAULT => -58 }, {#State 206 ACTIONS => { 'OR' => 143, 'DIV' => 146, "+" => 150, "?" => 142, 'BINOP' => 145, 'AND' => 149, "/" => 144, 'CMPOP' => 148, 'CAT' => 147, 'MOD' => 141 }, DEFAULT => -47 }, {#State 207 ACTIONS => { "?" => 142, "+" => 150, 'DIV' => 146, 'OR' => 143, 'CAT' => 147, 'MOD' => 141, 'CMPOP' => 148, "/" => 144, 'AND' => 149, 'BINOP' => 145 }, DEFAULT => -61 }, {#State 208 DEFAULT => -81 }, {#State 209 ACTIONS => { "?" => 142, "+" => 150, 'OR' => 143, 'DIV' => 146, 'MOD' => 141, 'CAT' => 147, 'AND' => 149, 'BINOP' => 145, 'CMPOP' => 148, "/" => 144 }, DEFAULT => -45 }, {#State 210 ACTIONS => { "\"" => 47, 'REF' => 17, "\$" => 48, 'NUMBER' => 23, 'IDENT' => 13, 'LITERAL' => 89, "\${" => 21 }, GOTOS => { 'ident' => 88, 'item' => 29, 'sterm' => 274, 'node' => 57 } }, {#State 211 DEFAULT => -115 }, {#State 212 DEFAULT => -105 }, {#State 213 DEFAULT => -114 }, {#State 214 DEFAULT => -106 }, {#State 215 ACTIONS => { 'TEXT' => 275 } }, {#State 216 ACTIONS => { 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'GET' => 27, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'NOT' => 12, 'IDENT' => 13, 'WRAPPER' => 19, 'RETURN' => 22, "\${" => 21, 'CLEAR' => 20, ";" => -18, 'CALL' => 8, 'TEXT' => 7, 'MACRO' => 10, 'UNLESS' => 9, 'DEFAULT' => 2, 'PROCESS' => 4, 'INSERT' => 66, 'TRY' => 67, 'FILTER' => 68, 'USE' => 59, 'WHILE' => 60, "(" => 61, "{" => 62, 'PERL' => 46, "\"" => 47, "\$" => 48, 'SET' => 52, 'META' => 53, 'NEXT' => 49, 'IF' => 34, 'RAWPERL' => 44, 'INCLUDE' => 43, 'THROW' => 38, 'STOP' => 39, "[" => 41 }, DEFAULT => -3, GOTOS => { 'condition' => 33, 'perl' => 73, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'ident' => 24, 'assign' => 18, 'expr' => 58, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'node' => 57, 'term' => 15, 'capture' => 55, 'wrapper' => 56, 'statement' => 11, 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'loop' => 45, 'lterm' => 42, 'try' => 5, 'view' => 40, 'atomexpr' => 35, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'block' => 276 } }, {#State 217 ACTIONS => { 'DOT' => 100 }, DEFAULT => -177 }, {#State 218 DEFAULT => -175 }, {#State 219 DEFAULT => -178 }, {#State 220 DEFAULT => -179 }, {#State 221 DEFAULT => -111 }, {#State 222 ACTIONS => { 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66, "{" => 62, "(" => 61, 'WHILE' => 60, 'USE' => 59, 'META' => 53, 'SET' => 52, 'NEXT' => 49, "\$" => 48, "\"" => 47, 'PERL' => 46, 'RAWPERL' => 44, 'INCLUDE' => 43, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'IF' => 34, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'GET' => 27, 'SWITCH' => 26, 'VIEW' => 25, 'NUMBER' => 23, 'CLEAR' => 20, 'RETURN' => 22, "\${" => 21, 'WRAPPER' => 19, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'IDENT' => 13, 'NOT' => 12, 'MACRO' => 10, 'UNLESS' => 9, 'TEXT' => 7, 'CALL' => 8, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2 }, DEFAULT => -3, GOTOS => { 'try' => 5, 'view' => 40, 'lterm' => 42, 'block' => 1, 'atomexpr' => 35, 'rawperl' => 3, 'setlist' => 37, 'sterm' => 36, 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'statement' => 11, 'template' => 277, 'loop' => 45, 'assign' => 18, 'expr' => 58, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'wrapper' => 56, 'capture' => 55, 'node' => 57, 'term' => 15, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'use' => 72, 'item' => 29, 'chunk' => 71, 'perl' => 73, 'condition' => 33, 'ident' => 24 } }, {#State 223 DEFAULT => -137 }, {#State 224 ACTIONS => { 'OR' => 143, ":" => 278, 'DIV' => 146, "+" => 150, "?" => 142, 'BINOP' => 145, 'AND' => 149, "/" => 144, 'CMPOP' => 148, 'MOD' => 141, 'CAT' => 147 } }, {#State 225 ACTIONS => { 'DIV' => 146, "/" => 144, 'BINOP' => 145, "+" => 150, 'CAT' => 147, 'CMPOP' => 148, 'MOD' => 141 }, DEFAULT => -141 }, {#State 226 ACTIONS => { 'DIV' => 146, 'MOD' => 141 }, DEFAULT => -134 }, {#State 227 ACTIONS => { 'MOD' => 141, "/" => 144, 'DIV' => 146, "+" => 150 }, DEFAULT => -133 }, {#State 228 ACTIONS => { 'MOD' => 141 }, DEFAULT => -136 }, {#State 229 ACTIONS => { 'MOD' => 141, "+" => 150, 'CMPOP' => 148, 'DIV' => 146, 'BINOP' => 145, "/" => 144 }, DEFAULT => -139 }, {#State 230 ACTIONS => { 'MOD' => 141, "+" => 150, 'DIV' => 146, 'BINOP' => 145, "/" => 144 }, DEFAULT => -138 }, {#State 231 ACTIONS => { "+" => 150, 'CMPOP' => 148, 'CAT' => 147, 'DIV' => 146, "/" => 144, 'BINOP' => 145, 'MOD' => 141 }, DEFAULT => -140 }, {#State 232 ACTIONS => { 'MOD' => 141, "/" => 144, 'DIV' => 146 }, DEFAULT => -135 }, {#State 233 ACTIONS => { 'ASSIGN' => -132 }, DEFAULT => -130 }, {#State 234 ACTIONS => { "\$" => 48, "\"" => 279, ";" => 220, 'IDENT' => 13, "\${" => 21, 'TEXT' => 219 }, GOTOS => { 'node' => 57, 'quotable' => 218, 'item' => 29, 'ident' => 217 } }, {#State 235 ACTIONS => { "\"" => 80, "\$" => 79, 'LITERAL' => 82, 'FILENAME' => 81, 'NUMBER' => 83, 'IDENT' => 84 }, GOTOS => { 'filepart' => 77, 'nameargs' => 280, 'names' => 78, 'filename' => 87, 'name' => 86 } }, {#State 236 DEFAULT => -59, GOTOS => { '@2-3' => 281 } }, {#State 237 DEFAULT => -145 }, {#State 238 DEFAULT => -144 }, {#State 239 ACTIONS => { "(" => 61, "[" => 41, "{" => 62, 'LITERAL' => 89, "\${" => 21, 'NUMBER' => 23, 'NOT' => 12, 'IDENT' => 13, "\"" => 47, "\$" => 48, 'REF' => 17 }, GOTOS => { 'ident' => 88, 'node' => 57, 'sterm' => 36, 'term' => 15, 'item' => 29, 'expr' => 282, 'lterm' => 42 } }, {#State 240 ACTIONS => { 'IDENT' => 13, 'NOT' => 12, 'NUMBER' => 23, "\$" => 48, 'REF' => 17, "\"" => 47, "{" => 62, "[" => 41, "(" => 61, "\${" => 21, 'LITERAL' => 89 }, GOTOS => { 'term' => 15, 'sterm' => 36, 'node' => 57, 'lterm' => 42, 'item' => 29, 'expr' => 283, 'ident' => 88 } }, {#State 241 DEFAULT => -108 }, {#State 242 DEFAULT => -120 }, {#State 243 DEFAULT => -121 }, {#State 244 ACTIONS => { 'FINAL' => 284, 'CATCH' => 285 }, DEFAULT => -72, GOTOS => { 'final' => 286 } }, {#State 245 ACTIONS => { 'GET' => 27, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'FOR' => 30, 'BLOCK' => 32, 'LITERAL' => 31, 'IDENT' => 13, 'NOT' => 12, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'CLEAR' => 20, 'RETURN' => 22, "\${" => 21, 'WRAPPER' => 19, ";" => -18, 'UNLESS' => 9, 'MACRO' => 10, 'CALL' => 8, 'TEXT' => 7, 'DEFAULT' => 2, 'PROCESS' => 4, 'TRY' => 67, 'INSERT' => 66, 'FILTER' => 68, "{" => 62, "(" => 61, 'WHILE' => 60, 'USE' => 59, "\$" => 48, "\"" => 47, 'PERL' => 46, 'NEXT' => 49, 'META' => 53, 'SET' => 52, 'IF' => 34, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'RAWPERL' => 44, 'INCLUDE' => 43 }, DEFAULT => -3, GOTOS => { 'lterm' => 42, 'view' => 40, 'try' => 5, 'sterm' => 36, 'setlist' => 37, 'rawperl' => 3, 'atomexpr' => 35, 'block' => 287, 'statement' => 11, 'defblockname' => 50, 'directive' => 51, 'atomdir' => 6, 'loop' => 45, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'expr' => 58, 'assign' => 18, 'term' => 15, 'node' => 57, 'capture' => 55, 'wrapper' => 56, 'condition' => 33, 'perl' => 73, 'chunk' => 71, 'item' => 29, 'use' => 72, 'filter' => 69, 'macro' => 70, 'anonblock' => 28, 'ident' => 24 } }, {#State 246 ACTIONS => { 'AND' => 149, 'OR' => 143, "?" => 142, 'MOD' => 141, "+" => 150, 'CMPOP' => 148, 'CAT' => 147, 'DIV' => 146, 'BINOP' => 145, "/" => 144 }, DEFAULT => -150 }, {#State 247 ACTIONS => { 'IDENT' => 13, 'NOT' => 12, 'REF' => 17, "(" => 61, "{" => 62, "[" => 41, "\${" => 21, 'NUMBER' => 23, "\"" => 47, ")" => 288, "\$" => 48, 'LITERAL' => 249, 'COMMA' => 253 }, GOTOS => { 'ident' => 252, 'node' => 57, 'sterm' => 36, 'term' => 15, 'item' => 250, 'param' => 251, 'expr' => 248, 'lterm' => 42 } }, {#State 248 ACTIONS => { 'MOD' => 141, 'OR' => 143, "?" => 142, 'AND' => 149, "/" => 144, 'BINOP' => 145, 'DIV' => 146, 'CMPOP' => 148, 'CAT' => 147, "+" => 150 }, DEFAULT => -152 }, {#State 249 ACTIONS => { 'ASSIGN' => 239 }, DEFAULT => -112 }, {#State 250 ACTIONS => { 'ASSIGN' => 240, "(" => 104 }, DEFAULT => -128 }, {#State 251 DEFAULT => -153 }, {#State 252 ACTIONS => { 'DOT' => 100, 'ASSIGN' => 289 }, DEFAULT => -109 }, {#State 253 DEFAULT => -155 }, {#State 254 DEFAULT => -165 }, {#State 255 ACTIONS => { 'LITERAL' => 249, 'COMMA' => 253, "\$" => 48, "\"" => 47, 'NUMBER' => 23, "\${" => 21, "{" => 62, "[" => 41, "(" => 61, 'REF' => 17, 'NOT' => 12, 'IDENT' => 13 }, DEFAULT => -162, GOTOS => { 'lterm' => 42, 'expr' => 248, 'param' => 251, 'item' => 250, 'term' => 15, 'sterm' => 36, 'node' => 57, 'ident' => 252 } }, {#State 256 DEFAULT => -167 }, {#State 257 DEFAULT => -170 }, {#State 258 ACTIONS => { 'ELSE' => 292, 'ELSIF' => 290 }, DEFAULT => -50, GOTOS => { 'else' => 291 } }, {#State 259 ACTIONS => { "(" => 61, "{" => 62, 'WHILE' => 60, 'USE' => 59, 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'INCLUDE' => 43, 'RAWPERL' => 44, "[" => 41, 'THROW' => 38, 'STOP' => 39, 'IF' => 34, 'META' => 53, 'SET' => 52, 'NEXT' => 49, "\"" => 47, "\$" => 48, 'PERL' => 46, 'WRAPPER' => 19, 'CLEAR' => 20, 'RETURN' => 22, "\${" => 21, 'REF' => 17, 'DEBUG' => 16, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'GET' => 27, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'PROCESS' => 4, 'DEFAULT' => 2, 'CALL' => 8, 'TEXT' => 7, 'MACRO' => 10, 'UNLESS' => 9, ";" => -18 }, DEFAULT => -3, GOTOS => { 'block' => 293, 'atomexpr' => 35, 'rawperl' => 3, 'setlist' => 37, 'sterm' => 36, 'try' => 5, 'view' => 40, 'lterm' => 42, 'loop' => 45, 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'statement' => 11, 'capture' => 55, 'wrapper' => 56, 'node' => 57, 'term' => 15, 'assign' => 18, 'expr' => 58, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'ident' => 24, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'condition' => 33, 'perl' => 73 } }, {#State 260 ACTIONS => { 'IDENT' => -96, 'COMMA' => -96, ")" => -96 }, DEFAULT => -130 }, {#State 261 ACTIONS => { 'IDENT' => 295, 'COMMA' => 294, ")" => 296 } }, {#State 262 ACTIONS => { 'END' => 297 } }, {#State 263 ACTIONS => { 'WHILE' => 60, 'USE' => 59, "{" => 62, "(" => 61, 'TRY' => 67, 'INSERT' => 66, 'FILTER' => 68, 'IF' => 34, 'INCLUDE' => 43, 'RAWPERL' => 44, 'STOP' => 39, 'THROW' => 38, "[" => 41, 'PERL' => 46, "\$" => 48, "\"" => 47, 'SET' => 52, 'META' => 53, 'NEXT' => 49, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'NOT' => 12, 'IDENT' => 13, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'WRAPPER' => 19, 'SWITCH' => 26, 'VIEW' => 25, 'NUMBER' => 23, 'GET' => 27, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'DEFAULT' => 2, 'PROCESS' => 4, ";" => -18, 'MACRO' => 10, 'UNLESS' => 9, 'CALL' => 8, 'TEXT' => 7 }, DEFAULT => -3, GOTOS => { 'try' => 5, 'view' => 40, 'lterm' => 42, 'block' => 298, 'rawperl' => 3, 'setlist' => 37, 'sterm' => 36, 'atomexpr' => 35, 'directive' => 51, 'defblockname' => 50, 'atomdir' => 6, 'statement' => 11, 'loop' => 45, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'assign' => 18, 'expr' => 58, 'wrapper' => 56, 'capture' => 55, 'node' => 57, 'term' => 15, 'use' => 72, 'item' => 29, 'chunk' => 71, 'macro' => 70, 'anonblock' => 28, 'filter' => 69, 'condition' => 33, 'perl' => 73, 'ident' => 24 } }, {#State 264 ACTIONS => { 'CASE' => 299 }, DEFAULT => -55, GOTOS => { 'case' => 300 } }, {#State 265 DEFAULT => -129 }, {#State 266 ACTIONS => { 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'USE' => 59, 'WHILE' => 60, "(" => 61, "{" => 62, 'SET' => 52, 'META' => 53, 'NEXT' => 49, 'PERL' => 46, "\"" => 47, "\$" => 48, 'INCLUDE' => 43, 'RAWPERL' => 44, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'IF' => 34, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'NUMBER' => 23, 'SWITCH' => 26, 'VIEW' => 25, 'GET' => 27, 'WRAPPER' => 19, "\${" => 21, 'CLEAR' => 20, 'RETURN' => 22, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'NOT' => 12, 'IDENT' => 13, 'TEXT' => 7, 'CALL' => 8, 'MACRO' => 10, 'UNLESS' => 9, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2 }, DEFAULT => -3, GOTOS => { 'expr' => 58, 'assign' => 18, 'defblock' => 65, 'switch' => 64, 'chunks' => 63, 'wrapper' => 56, 'capture' => 55, 'term' => 15, 'node' => 57, 'filter' => 69, 'macro' => 70, 'anonblock' => 28, 'chunk' => 71, 'item' => 29, 'use' => 72, 'perl' => 73, 'condition' => 33, 'ident' => 24, 'view' => 40, 'try' => 5, 'lterm' => 42, 'block' => 301, 'atomexpr' => 35, 'sterm' => 36, 'setlist' => 37, 'rawperl' => 3, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51, 'statement' => 11, 'loop' => 45 } }, {#State 267 DEFAULT => -156, GOTOS => { 'args' => 302 } }, {#State 268 DEFAULT => -156, GOTOS => { 'args' => 303 } }, {#State 269 ACTIONS => { 'TEXT' => 304 } }, {#State 270 DEFAULT => -100 }, {#State 271 DEFAULT => -102 }, {#State 272 ACTIONS => { 'END' => 305 } }, {#State 273 ACTIONS => { 'ELSE' => 292, 'ELSIF' => 290 }, DEFAULT => -50, GOTOS => { 'else' => 306 } }, {#State 274 DEFAULT => -117 }, {#State 275 ACTIONS => { 'END' => 307 } }, {#State 276 ACTIONS => { 'END' => 308 } }, {#State 277 ACTIONS => { 'END' => 309 } }, {#State 278 ACTIONS => { 'NOT' => 12, 'IDENT' => 13, 'NUMBER' => 23, 'REF' => 17, "\$" => 48, "\"" => 47, "[" => 41, "{" => 62, "(" => 61, "\${" => 21, 'LITERAL' => 89 }, GOTOS => { 'item' => 29, 'expr' => 310, 'lterm' => 42, 'ident' => 88, 'node' => 57, 'term' => 15, 'sterm' => 36 } }, {#State 279 ACTIONS => { 'ASSIGN' => -160 }, DEFAULT => -167 }, {#State 280 DEFAULT => -157 }, {#State 281 ACTIONS => { 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'IDENT' => 13, 'NOT' => 12, 'WRAPPER' => 19, 'RETURN' => 22, 'CLEAR' => 20, "\${" => 21, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'GET' => 27, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'DEFAULT' => 2, 'PROCESS' => 4, ";" => -18, 'CALL' => 8, 'TEXT' => 7, 'UNLESS' => 9, 'MACRO' => 10, 'WHILE' => 60, 'USE' => 59, "(" => 61, "{" => 62, 'INSERT' => 66, 'TRY' => 67, 'FILTER' => 68, 'IF' => 34, 'RAWPERL' => 44, 'INCLUDE' => 43, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'PERL' => 46, "\"" => 47, "\$" => 48, 'SET' => 52, 'META' => 53, 'NEXT' => 49 }, DEFAULT => -3, GOTOS => { 'ident' => 24, 'perl' => 73, 'condition' => 33, 'filter' => 69, 'anonblock' => 28, 'macro' => 70, 'item' => 29, 'chunk' => 71, 'use' => 72, 'term' => 15, 'node' => 57, 'wrapper' => 56, 'capture' => 55, 'expr' => 58, 'assign' => 18, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'loop' => 45, 'statement' => 11, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51, 'atomexpr' => 35, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'block' => 311, 'lterm' => 42, 'view' => 40, 'try' => 5 } }, {#State 282 ACTIONS => { 'CMPOP' => 148, 'CAT' => 147, "+" => 150, "/" => 144, 'BINOP' => 145, 'DIV' => 146, 'AND' => 149, 'MOD' => 141, 'OR' => 143, "?" => 142 }, DEFAULT => -123 }, {#State 283 ACTIONS => { "/" => 144, 'BINOP' => 145, 'DIV' => 146, 'CAT' => 147, 'CMPOP' => 148, "+" => 150, 'MOD' => 141, "?" => 142, 'OR' => 143, 'AND' => 149 }, DEFAULT => -124 }, {#State 284 ACTIONS => { ";" => 312 } }, {#State 285 ACTIONS => { 'FILENAME' => 81, 'IDENT' => 84, 'NUMBER' => 83, ";" => 315, 'DEFAULT' => 313 }, GOTOS => { 'filepart' => 77, 'filename' => 314 } }, {#State 286 ACTIONS => { 'END' => 316 } }, {#State 287 ACTIONS => { 'END' => 317 } }, {#State 288 DEFAULT => -164 }, {#State 289 ACTIONS => { "\"" => 47, "\$" => 48, 'REF' => 17, 'NUMBER' => 23, 'IDENT' => 13, 'NOT' => 12, 'LITERAL' => 89, "\${" => 21, "(" => 61, "[" => 41, "{" => 62 }, GOTOS => { 'lterm' => 42, 'sterm' => 36, 'term' => 15, 'node' => 57, 'expr' => 318, 'ident' => 88, 'item' => 29 } }, {#State 290 ACTIONS => { 'LITERAL' => 89, 'NUMBER' => 23, "\$" => 48, "\"" => 47, "[" => 41, "{" => 62, "(" => 61, "\${" => 21, 'IDENT' => 13, 'NOT' => 12, 'REF' => 17 }, GOTOS => { 'ident' => 88, 'term' => 15, 'sterm' => 36, 'node' => 57, 'expr' => 319, 'item' => 29, 'lterm' => 42 } }, {#State 291 ACTIONS => { 'END' => 320 } }, {#State 292 ACTIONS => { ";" => 321 } }, {#State 293 ACTIONS => { 'END' => 322 } }, {#State 294 DEFAULT => -95 }, {#State 295 DEFAULT => -94 }, {#State 296 ACTIONS => { 'PERL' => 46, "\"" => 47, "\$" => 48, 'NEXT' => 49, 'CALL' => 8, 'UNLESS' => 9, 'SET' => 52, 'IF' => 34, 'DEFAULT' => 2, 'THROW' => 38, 'STOP' => 39, 'PROCESS' => 4, "[" => 41, 'INCLUDE' => 43, 'INSERT' => 66, 'NUMBER' => 23, 'TRY' => 67, 'SWITCH' => 26, 'GET' => 27, 'FILTER' => 68, 'FOR' => 30, 'LITERAL' => 31, 'BLOCK' => 180, 'NOT' => 12, 'IDENT' => 13, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17, 'WHILE' => 60, "(" => 61, "{" => 62, 'WRAPPER' => 19, "\${" => 21, 'CLEAR' => 20, 'RETURN' => 22 }, GOTOS => { 'node' => 57, 'setlist' => 37, 'sterm' => 36, 'term' => 15, 'atomexpr' => 35, 'wrapper' => 56, 'lterm' => 42, 'try' => 5, 'switch' => 64, 'assign' => 18, 'expr' => 182, 'loop' => 45, 'ident' => 162, 'mdir' => 323, 'perl' => 73, 'condition' => 33, 'directive' => 184, 'item' => 29, 'atomdir' => 6, 'filter' => 69 } }, {#State 297 DEFAULT => -65 }, {#State 298 ACTIONS => { 'END' => 324 } }, {#State 299 ACTIONS => { 'REF' => 17, "\$" => 48, "\"" => 47, ";" => 326, 'DEFAULT' => 327, 'IDENT' => 13, 'NUMBER' => 23, "\${" => 21, 'LITERAL' => 89, "[" => 41, "{" => 62 }, GOTOS => { 'item' => 29, 'lterm' => 42, 'ident' => 88, 'node' => 57, 'sterm' => 36, 'term' => 325 } }, {#State 300 ACTIONS => { 'END' => 328 } }, {#State 301 ACTIONS => { 'END' => 329 } }, {#State 302 ACTIONS => { 'COMMA' => 253, 'LITERAL' => 249, "\$" => 48, "\"" => 47, 'NUMBER' => 23, "\${" => 21, "{" => 62, "[" => 41, "(" => 61, 'REF' => 17, 'IDENT' => 13, 'NOT' => 12 }, DEFAULT => -62, GOTOS => { 'lterm' => 42, 'item' => 250, 'expr' => 248, 'param' => 251, 'term' => 15, 'sterm' => 36, 'node' => 57, 'ident' => 252 } }, {#State 303 ACTIONS => { "(" => 61, "{" => 62, "[" => 41, "\${" => 21, 'IDENT' => 13, 'NOT' => 12, 'REF' => 17, 'COMMA' => 253, 'LITERAL' => 249, 'NUMBER' => 23, "\"" => 47, "\$" => 48 }, DEFAULT => -63, GOTOS => { 'ident' => 252, 'node' => 57, 'sterm' => 36, 'term' => 15, 'item' => 250, 'param' => 251, 'expr' => 248, 'lterm' => 42 } }, {#State 304 ACTIONS => { "\"" => 330 } }, {#State 305 DEFAULT => -88 }, {#State 306 ACTIONS => { 'END' => 331 } }, {#State 307 DEFAULT => -79 }, {#State 308 DEFAULT => -77 }, {#State 309 DEFAULT => -82 }, {#State 310 ACTIONS => { 'CMPOP' => 148, 'CAT' => 147, "+" => 150, 'BINOP' => 145, "/" => 144, 'DIV' => 146, 'AND' => 149, 'MOD' => 141, 'OR' => 143, "?" => 142 }, DEFAULT => -143 }, {#State 311 ACTIONS => { 'END' => 332 } }, {#State 312 ACTIONS => { 'USE' => 59, 'WHILE' => 60, "(" => 61, "{" => 62, 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'RAWPERL' => 44, 'INCLUDE' => 43, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'IF' => 34, 'SET' => 52, 'META' => 53, 'NEXT' => 49, 'PERL' => 46, "\"" => 47, "\$" => 48, 'WRAPPER' => 19, "\${" => 21, 'CLEAR' => 20, 'RETURN' => 22, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'NOT' => 12, 'IDENT' => 13, 'BLOCK' => 32, 'LITERAL' => 31, 'FOR' => 30, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'GET' => 27, 'PROCESS' => 4, 'DEFAULT' => 2, 'TEXT' => 7, 'CALL' => 8, 'UNLESS' => 9, 'MACRO' => 10, ";" => -18 }, DEFAULT => -3, GOTOS => { 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'statement' => 11, 'loop' => 45, 'try' => 5, 'view' => 40, 'lterm' => 42, 'block' => 333, 'atomexpr' => 35, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'macro' => 70, 'anonblock' => 28, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'condition' => 33, 'perl' => 73, 'ident' => 24, 'assign' => 18, 'expr' => 58, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'capture' => 55, 'wrapper' => 56, 'node' => 57, 'term' => 15 } }, {#State 313 ACTIONS => { ";" => 334 } }, {#State 314 ACTIONS => { ";" => 335, 'DOT' => 178 } }, {#State 315 ACTIONS => { 'STOP' => 39, 'THROW' => 38, "[" => 41, 'RAWPERL' => 44, 'INCLUDE' => 43, 'IF' => 34, 'NEXT' => 49, 'SET' => 52, 'META' => 53, 'PERL' => 46, "\$" => 48, "\"" => 47, 'WHILE' => 60, 'USE' => 59, "{" => 62, "(" => 61, 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66, 'PROCESS' => 4, 'DEFAULT' => 2, 'MACRO' => 10, 'UNLESS' => 9, 'CALL' => 8, 'TEXT' => 7, ";" => -18, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'WRAPPER' => 19, 'IDENT' => 13, 'NOT' => 12, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17, 'FOR' => 30, 'LITERAL' => 31, 'BLOCK' => 32, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'GET' => 27 }, DEFAULT => -3, GOTOS => { 'lterm' => 42, 'view' => 40, 'try' => 5, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'atomexpr' => 35, 'block' => 336, 'statement' => 11, 'defblockname' => 50, 'directive' => 51, 'atomdir' => 6, 'loop' => 45, 'chunks' => 63, 'switch' => 64, 'defblock' => 65, 'expr' => 58, 'assign' => 18, 'term' => 15, 'node' => 57, 'wrapper' => 56, 'capture' => 55, 'condition' => 33, 'perl' => 73, 'chunk' => 71, 'item' => 29, 'use' => 72, 'filter' => 69, 'anonblock' => 28, 'macro' => 70, 'ident' => 24 } }, {#State 316 DEFAULT => -67 }, {#State 317 DEFAULT => -80 }, {#State 318 ACTIONS => { 'AND' => 149, 'MOD' => 141, "?" => 142, 'OR' => 143, 'CAT' => 147, 'CMPOP' => 148, "+" => 150, "/" => 144, 'BINOP' => 145, 'DIV' => 146 }, DEFAULT => -154 }, {#State 319 ACTIONS => { 'CAT' => 147, 'MOD' => 141, 'BINOP' => 145, 'AND' => 149, "/" => 144, 'CMPOP' => 148, ";" => 337, "+" => 150, "?" => 142, 'OR' => 143, 'DIV' => 146 } }, {#State 320 DEFAULT => -46 }, {#State 321 ACTIONS => { 'TRY' => 67, 'INSERT' => 66, 'FILTER' => 68, 'WHILE' => 60, 'USE' => 59, "{" => 62, "(" => 61, 'PERL' => 46, "\$" => 48, "\"" => 47, 'NEXT' => 49, 'SET' => 52, 'META' => 53, 'IF' => 34, 'STOP' => 39, 'THROW' => 38, "[" => 41, 'RAWPERL' => 44, 'INCLUDE' => 43, 'SWITCH' => 26, 'VIEW' => 25, 'NUMBER' => 23, 'GET' => 27, 'FOR' => 30, 'BLOCK' => 32, 'LITERAL' => 31, 'NOT' => 12, 'IDENT' => 13, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, "\${" => 21, 'RETURN' => 22, 'CLEAR' => 20, 'WRAPPER' => 19, ";" => -18, 'UNLESS' => 9, 'MACRO' => 10, 'CALL' => 8, 'TEXT' => 7, 'DEFAULT' => 2, 'PROCESS' => 4 }, DEFAULT => -3, GOTOS => { 'term' => 15, 'node' => 57, 'wrapper' => 56, 'capture' => 55, 'expr' => 58, 'assign' => 18, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'ident' => 24, 'condition' => 33, 'perl' => 73, 'filter' => 69, 'anonblock' => 28, 'macro' => 70, 'chunk' => 71, 'item' => 29, 'use' => 72, 'atomexpr' => 35, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'block' => 338, 'lterm' => 42, 'view' => 40, 'try' => 5, 'loop' => 45, 'statement' => 11, 'atomdir' => 6, 'defblockname' => 50, 'directive' => 51 } }, {#State 322 DEFAULT => -93 }, {#State 323 DEFAULT => -90 }, {#State 324 DEFAULT => -75 }, {#State 325 ACTIONS => { ";" => 339 } }, {#State 326 ACTIONS => { 'FOR' => 30, 'BLOCK' => 32, 'LITERAL' => 31, 'NUMBER' => 23, 'SWITCH' => 26, 'VIEW' => 25, 'GET' => 27, 'WRAPPER' => 19, "\${" => 21, 'RETURN' => 22, 'CLEAR' => 20, 'IDENT' => 13, 'NOT' => 12, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17, 'TEXT' => 7, 'CALL' => 8, 'MACRO' => 10, 'UNLESS' => 9, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2, 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'USE' => 59, 'WHILE' => 60, "(" => 61, "{" => 62, 'NEXT' => 49, 'SET' => 52, 'META' => 53, 'PERL' => 46, "\"" => 47, "\$" => 48, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'INCLUDE' => 43, 'RAWPERL' => 44, 'IF' => 34 }, DEFAULT => -3, GOTOS => { 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50, 'statement' => 11, 'loop' => 45, 'try' => 5, 'view' => 40, 'lterm' => 42, 'block' => 340, 'atomexpr' => 35, 'rawperl' => 3, 'setlist' => 37, 'sterm' => 36, 'macro' => 70, 'anonblock' => 28, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'condition' => 33, 'perl' => 73, 'ident' => 24, 'assign' => 18, 'expr' => 58, 'switch' => 64, 'defblock' => 65, 'chunks' => 63, 'capture' => 55, 'wrapper' => 56, 'node' => 57, 'term' => 15 } }, {#State 327 ACTIONS => { ";" => 341 } }, {#State 328 DEFAULT => -51 }, {#State 329 DEFAULT => -57 }, {#State 330 DEFAULT => -101 }, {#State 331 DEFAULT => -44 }, {#State 332 DEFAULT => -60 }, {#State 333 DEFAULT => -71 }, {#State 334 ACTIONS => { "[" => 41, 'THROW' => 38, 'STOP' => 39, 'INCLUDE' => 43, 'RAWPERL' => 44, 'IF' => 34, 'NEXT' => 49, 'META' => 53, 'SET' => 52, "\"" => 47, "\$" => 48, 'PERL' => 46, "(" => 61, "{" => 62, 'USE' => 59, 'WHILE' => 60, 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'PROCESS' => 4, 'DEFAULT' => 2, 'CALL' => 8, 'TEXT' => 7, 'UNLESS' => 9, 'MACRO' => 10, ";" => -18, 'WRAPPER' => 19, 'RETURN' => 22, 'CLEAR' => 20, "\${" => 21, 'NOT' => 12, 'IDENT' => 13, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'FOR' => 30, 'BLOCK' => 32, 'LITERAL' => 31, 'GET' => 27, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26 }, DEFAULT => -3, GOTOS => { 'node' => 57, 'term' => 15, 'capture' => 55, 'wrapper' => 56, 'assign' => 18, 'expr' => 58, 'defblock' => 65, 'switch' => 64, 'chunks' => 63, 'ident' => 24, 'condition' => 33, 'perl' => 73, 'anonblock' => 28, 'macro' => 70, 'filter' => 69, 'use' => 72, 'chunk' => 71, 'item' => 29, 'atomexpr' => 35, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'block' => 342, 'lterm' => 42, 'try' => 5, 'view' => 40, 'loop' => 45, 'statement' => 11, 'atomdir' => 6, 'directive' => 51, 'defblockname' => 50 } }, {#State 335 ACTIONS => { 'FOR' => 30, 'BLOCK' => 32, 'LITERAL' => 31, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'GET' => 27, 'CLEAR' => 20, "\${" => 21, 'RETURN' => 22, 'WRAPPER' => 19, 'NOT' => 12, 'IDENT' => 13, 'LAST' => 14, 'REF' => 17, 'DEBUG' => 16, 'UNLESS' => 9, 'MACRO' => 10, 'CALL' => 8, 'TEXT' => 7, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2, 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66, 'USE' => 59, 'WHILE' => 60, "{" => 62, "(" => 61, 'NEXT' => 49, 'SET' => 52, 'META' => 53, 'PERL' => 46, "\$" => 48, "\"" => 47, 'STOP' => 39, 'THROW' => 38, "[" => 41, 'RAWPERL' => 44, 'INCLUDE' => 43, 'IF' => 34 }, DEFAULT => -3, GOTOS => { 'perl' => 73, 'condition' => 33, 'chunk' => 71, 'item' => 29, 'use' => 72, 'filter' => 69, 'anonblock' => 28, 'macro' => 70, 'ident' => 24, 'defblock' => 65, 'switch' => 64, 'chunks' => 63, 'expr' => 58, 'assign' => 18, 'term' => 15, 'node' => 57, 'wrapper' => 56, 'capture' => 55, 'statement' => 11, 'defblockname' => 50, 'directive' => 51, 'atomdir' => 6, 'loop' => 45, 'lterm' => 42, 'view' => 40, 'try' => 5, 'sterm' => 36, 'rawperl' => 3, 'setlist' => 37, 'atomexpr' => 35, 'block' => 343 } }, {#State 336 ACTIONS => { 'CATCH' => 285, 'FINAL' => 284 }, DEFAULT => -72, GOTOS => { 'final' => 344 } }, {#State 337 ACTIONS => { 'WRAPPER' => 19, "\${" => 21, 'RETURN' => 22, 'CLEAR' => 20, 'NOT' => 12, 'IDENT' => 13, 'LAST' => 14, 'DEBUG' => 16, 'REF' => 17, 'FOR' => 30, 'BLOCK' => 32, 'LITERAL' => 31, 'NUMBER' => 23, 'SWITCH' => 26, 'VIEW' => 25, 'GET' => 27, 'PROCESS' => 4, 'DEFAULT' => 2, 'CALL' => 8, 'TEXT' => 7, 'UNLESS' => 9, 'MACRO' => 10, ";" => -18, 'WHILE' => 60, 'USE' => 59, "(" => 61, "{" => 62, 'FILTER' => 68, 'INSERT' => 66, 'TRY' => 67, 'THROW' => 38, 'STOP' => 39, "[" => 41, 'RAWPERL' => 44, 'INCLUDE' => 43, 'IF' => 34, 'NEXT' => 49, 'SET' => 52, 'META' => 53, 'PERL' => 46, "\"" => 47, "\$" => 48 }, DEFAULT => -3, GOTOS => { 'defblock' => 65, 'switch' => 64, 'chunks' => 63, 'assign' => 18, 'expr' => 58, 'wrapper' => 56, 'capture' => 55, 'node' => 57, 'term' => 15, 'use' => 72, 'chunk' => 71, 'item' => 29, 'macro' => 70, 'anonblock' => 28, 'filter' => 69, 'perl' => 73, 'condition' => 33, 'ident' => 24, 'try' => 5, 'view' => 40, 'lterm' => 42, 'block' => 345, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'atomexpr' => 35, 'directive' => 51, 'defblockname' => 50, 'atomdir' => 6, 'statement' => 11, 'loop' => 45 } }, {#State 338 DEFAULT => -49 }, {#State 339 ACTIONS => { 'META' => 53, 'SET' => 52, 'NEXT' => 49, "\$" => 48, "\"" => 47, 'PERL' => 46, 'INCLUDE' => 43, 'RAWPERL' => 44, "[" => 41, 'STOP' => 39, 'THROW' => 38, 'IF' => 34, 'FILTER' => 68, 'TRY' => 67, 'INSERT' => 66, "{" => 62, "(" => 61, 'USE' => 59, 'WHILE' => 60, 'UNLESS' => 9, 'MACRO' => 10, 'TEXT' => 7, 'CALL' => 8, ";" => -18, 'PROCESS' => 4, 'DEFAULT' => 2, 'LITERAL' => 31, 'BLOCK' => 32, 'FOR' => 30, 'GET' => 27, 'VIEW' => 25, 'SWITCH' => 26, 'NUMBER' => 23, 'RETURN' => 22, 'CLEAR' => 20, "\${" => 21, 'WRAPPER' => 19, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'NOT' => 12, 'IDENT' => 13 }, DEFAULT => -3, GOTOS => { 'statement' => 11, 'directive' => 51, 'defblockname' => 50, 'atomdir' => 6, 'loop' => 45, 'lterm' => 42, 'try' => 5, 'view' => 40, 'setlist' => 37, 'rawperl' => 3, 'sterm' => 36, 'atomexpr' => 35, 'block' => 346, 'condition' => 33, 'perl' => 73, 'use' => 72, 'item' => 29, 'chunk' => 71, 'macro' => 70, 'anonblock' => 28, 'filter' => 69, 'ident' => 24, 'chunks' => 63, 'defblock' => 65, 'switch' => 64, 'assign' => 18, 'expr' => 58, 'node' => 57, 'term' => 15, 'capture' => 55, 'wrapper' => 56 } }, {#State 340 DEFAULT => -54 }, {#State 341 ACTIONS => { 'IDENT' => 13, 'NOT' => 12, 'DEBUG' => 16, 'REF' => 17, 'LAST' => 14, 'WRAPPER' => 19, 'RETURN' => 22, 'CLEAR' => 20, "\${" => 21, 'GET' => 27, 'NUMBER' => 23, 'VIEW' => 25, 'SWITCH' => 26, 'FOR' => 30, 'LITERAL' => 31, 'BLOCK' => 32, 'DEFAULT' => 2, 'PROCESS' => 4, ";" => -18, 'TEXT' => 7, 'CALL' => 8, 'UNLESS' => 9, 'MACRO' => 10, "(" => 61, "{" => 62, 'WHILE' => 60, 'USE' => 59, 'INSERT' => 66, 'TRY' => 67, 'FILTER' => 68, 'IF' => 34, "[" => 41, 'THROW' => 38, 'STOP' => 39, 'INCLUDE' => 43, 'RAWPERL' => 44, "\"" => 47, "\$" => 48, 'PERL' => 46, 'NEXT' => 49, 'META' => 53, 'SET' => 52 }, DEFAULT => -3, GOTOS => { 'chunks' => 63, 'switch' => 64, 'defblock' => 65, 'assign' => 18, 'expr' => 58, 'node' => 57, 'term' => 15, 'wrapper' => 56, 'capture' => 55, 'condition' => 33, 'perl' => 73, 'use' => 72, 'item' => 29, 'chunk' => 71, 'macro' => 70, 'anonblock' => 28, 'filter' => 69, 'ident' => 24, 'lterm' => 42, 'try' => 5, 'view' => 40, 'rawperl' => 3, 'setlist' => 37, 'sterm' => 36, 'atomexpr' => 35, 'block' => 347, 'statement' => 11, 'directive' => 51, 'defblockname' => 50, 'atomdir' => 6, 'loop' => 45 } }, {#State 342 ACTIONS => { 'CATCH' => 285, 'FINAL' => 284 }, DEFAULT => -72, GOTOS => { 'final' => 348 } }, {#State 343 ACTIONS => { 'FINAL' => 284, 'CATCH' => 285 }, DEFAULT => -72, GOTOS => { 'final' => 349 } }, {#State 344 DEFAULT => -70 }, {#State 345 ACTIONS => { 'ELSE' => 292, 'ELSIF' => 290 }, DEFAULT => -50, GOTOS => { 'else' => 350 } }, {#State 346 ACTIONS => { 'CASE' => 299 }, DEFAULT => -55, GOTOS => { 'case' => 351 } }, {#State 347 DEFAULT => -53 }, {#State 348 DEFAULT => -69 }, {#State 349 DEFAULT => -68 }, {#State 350 DEFAULT => -48 }, {#State 351 DEFAULT => -52 } ]; #======================================================================== # Rules #======================================================================== $RULES = [ [#Rule 0 '$start', 2, undef ], [#Rule 1 'template', 1, sub #line 64 "Parser.yp" { $factory->template($_[1]) } ], [#Rule 2 'block', 1, sub #line 67 "Parser.yp" { $factory->block($_[1]) } ], [#Rule 3 'block', 0, sub #line 68 "Parser.yp" { $factory->block() } ], [#Rule 4 'chunks', 2, sub #line 71 "Parser.yp" { push(@{$_[1]}, $_[2]) if defined $_[2]; $_[1] } ], [#Rule 5 'chunks', 1, sub #line 73 "Parser.yp" { defined $_[1] ? [ $_[1] ] : [ ] } ], [#Rule 6 'chunk', 1, sub #line 76 "Parser.yp" { $factory->textblock($_[1]) } ], [#Rule 7 'chunk', 2, sub #line 77 "Parser.yp" { return '' unless $_[1]; $_[0]->location() . $_[1]; } ], [#Rule 8 'statement', 1, undef ], [#Rule 9 'statement', 1, undef ], [#Rule 10 'statement', 1, undef ], [#Rule 11 'statement', 1, undef ], [#Rule 12 'statement', 1, undef ], [#Rule 13 'statement', 1, undef ], [#Rule 14 'statement', 1, undef ], [#Rule 15 'statement', 1, undef ], [#Rule 16 'statement', 1, sub #line 90 "Parser.yp" { $factory->get($_[1]) } ], [#Rule 17 'statement', 2, sub #line 91 "Parser.yp" { $_[0]->add_metadata($_[2]); } ], [#Rule 18 'statement', 0, undef ], [#Rule 19 'directive', 1, sub #line 95 "Parser.yp" { $factory->set($_[1]) } ], [#Rule 20 'directive', 1, undef ], [#Rule 21 'directive', 1, undef ], [#Rule 22 'directive', 1, undef ], [#Rule 23 'directive', 1, undef ], [#Rule 24 'directive', 1, undef ], [#Rule 25 'directive', 1, undef ], [#Rule 26 'atomexpr', 1, sub #line 109 "Parser.yp" { $factory->get($_[1]) } ], [#Rule 27 'atomexpr', 1, undef ], [#Rule 28 'atomdir', 2, sub #line 113 "Parser.yp" { $factory->get($_[2]) } ], [#Rule 29 'atomdir', 2, sub #line 114 "Parser.yp" { $factory->call($_[2]) } ], [#Rule 30 'atomdir', 2, sub #line 115 "Parser.yp" { $factory->set($_[2]) } ], [#Rule 31 'atomdir', 2, sub #line 116 "Parser.yp" { $factory->default($_[2]) } ], [#Rule 32 'atomdir', 2, sub #line 117 "Parser.yp" { $factory->insert($_[2]) } ], [#Rule 33 'atomdir', 2, sub #line 118 "Parser.yp" { $factory->include($_[2]) } ], [#Rule 34 'atomdir', 2, sub #line 119 "Parser.yp" { $factory->process($_[2]) } ], [#Rule 35 'atomdir', 2, sub #line 120 "Parser.yp" { $factory->throw($_[2]) } ], [#Rule 36 'atomdir', 1, sub #line 121 "Parser.yp" { $factory->return() } ], [#Rule 37 'atomdir', 1, sub #line 122 "Parser.yp" { $factory->stop() } ], [#Rule 38 'atomdir', 1, sub #line 123 "Parser.yp" { "\$output = '';"; } ], [#Rule 39 'atomdir', 1, sub #line 124 "Parser.yp" { $_[0]->block_label('last ', ';') } ], [#Rule 40 'atomdir', 1, sub #line 125 "Parser.yp" { $_[0]->in_block('FOR') ? $factory->next($_[0]->block_label) : $_[0]->block_label('next ', ';') } ], [#Rule 41 'atomdir', 2, sub #line 128 "Parser.yp" { if ($_[2]->[0]->[0] =~ /^'(on|off)'$/) { $_[0]->{ DEBUG_DIRS } = ($1 eq 'on'); $factory->debug($_[2]); } else { $_[0]->{ DEBUG_DIRS } ? $factory->debug($_[2]) : ''; } } ], [#Rule 42 'atomdir', 1, undef ], [#Rule 43 'atomdir', 1, undef ], [#Rule 44 'condition', 6, sub #line 141 "Parser.yp" { $factory->if(@_[2, 4, 5]) } ], [#Rule 45 'condition', 3, sub #line 142 "Parser.yp" { $factory->if(@_[3, 1]) } ], [#Rule 46 'condition', 6, sub #line 144 "Parser.yp" { $factory->if("!($_[2])", @_[4, 5]) } ], [#Rule 47 'condition', 3, sub #line 145 "Parser.yp" { $factory->if("!($_[3])", $_[1]) } ], [#Rule 48 'else', 5, sub #line 149 "Parser.yp" { unshift(@{$_[5]}, [ @_[2, 4] ]); $_[5]; } ], [#Rule 49 'else', 3, sub #line 151 "Parser.yp" { [ $_[3] ] } ], [#Rule 50 'else', 0, sub #line 152 "Parser.yp" { [ undef ] } ], [#Rule 51 'switch', 6, sub #line 156 "Parser.yp" { $factory->switch(@_[2, 5]) } ], [#Rule 52 'case', 5, sub #line 160 "Parser.yp" { unshift(@{$_[5]}, [ @_[2, 4] ]); $_[5]; } ], [#Rule 53 'case', 4, sub #line 162 "Parser.yp" { [ $_[4] ] } ], [#Rule 54 'case', 3, sub #line 163 "Parser.yp" { [ $_[3] ] } ], [#Rule 55 'case', 0, sub #line 164 "Parser.yp" { [ undef ] } ], [#Rule 56 '@1-3', 0, sub #line 167 "Parser.yp" { $_[0]->enter_block('FOR') } ], [#Rule 57 'loop', 6, sub #line 168 "Parser.yp" { $factory->foreach(@{$_[2]}, $_[5], $_[0]->leave_block) } ], [#Rule 58 'loop', 3, sub #line 169 "Parser.yp" { $factory->foreach(@{$_[3]}, $_[1]) } ], [#Rule 59 '@2-3', 0, sub #line 170 "Parser.yp" { $_[0]->enter_block('WHILE') } ], [#Rule 60 'loop', 6, sub #line 171 "Parser.yp" { $factory->while(@_[2, 5], $_[0]->leave_block) } ], [#Rule 61 'loop', 3, sub #line 172 "Parser.yp" { $factory->while(@_[3, 1]) } ], [#Rule 62 'loopvar', 4, sub #line 175 "Parser.yp" { [ @_[1, 3, 4] ] } ], [#Rule 63 'loopvar', 4, sub #line 176 "Parser.yp" { [ @_[1, 3, 4] ] } ], [#Rule 64 'loopvar', 2, sub #line 177 "Parser.yp" { [ 0, @_[1, 2] ] } ], [#Rule 65 'wrapper', 5, sub #line 181 "Parser.yp" { $factory->wrapper(@_[2, 4]) } ], [#Rule 66 'wrapper', 3, sub #line 183 "Parser.yp" { $factory->wrapper(@_[3, 1]) } ], [#Rule 67 'try', 5, sub #line 187 "Parser.yp" { $factory->try(@_[3, 4]) } ], [#Rule 68 'final', 5, sub #line 191 "Parser.yp" { unshift(@{$_[5]}, [ @_[2,4] ]); $_[5]; } ], [#Rule 69 'final', 5, sub #line 194 "Parser.yp" { unshift(@{$_[5]}, [ undef, $_[4] ]); $_[5]; } ], [#Rule 70 'final', 4, sub #line 197 "Parser.yp" { unshift(@{$_[4]}, [ undef, $_[3] ]); $_[4]; } ], [#Rule 71 'final', 3, sub #line 199 "Parser.yp" { [ $_[3] ] } ], [#Rule 72 'final', 0, sub #line 200 "Parser.yp" { [ 0 ] } ], [#Rule 73 'use', 2, sub #line 203 "Parser.yp" { $factory->use($_[2]) } ], [#Rule 74 '@3-3', 0, sub #line 206 "Parser.yp" { $_[0]->push_defblock(); } ], [#Rule 75 'view', 6, sub #line 207 "Parser.yp" { $factory->view(@_[2,5], $_[0]->pop_defblock) } ], [#Rule 76 '@4-2', 0, sub #line 211 "Parser.yp" { ${$_[0]->{ INPERL }}++; } ], [#Rule 77 'perl', 5, sub #line 212 "Parser.yp" { ${$_[0]->{ INPERL }}--; $_[0]->{ EVAL_PERL } ? $factory->perl($_[4]) : $factory->no_perl(); } ], [#Rule 78 '@5-1', 0, sub #line 218 "Parser.yp" { ${$_[0]->{ INPERL }}++; $rawstart = ${$_[0]->{'LINE'}}; } ], [#Rule 79 'rawperl', 5, sub #line 220 "Parser.yp" { ${$_[0]->{ INPERL }}--; $_[0]->{ EVAL_PERL } ? $factory->rawperl($_[4], $rawstart) : $factory->no_perl(); } ], [#Rule 80 'filter', 5, sub #line 227 "Parser.yp" { $factory->filter(@_[2,4]) } ], [#Rule 81 'filter', 3, sub #line 229 "Parser.yp" { $factory->filter(@_[3,1]) } ], [#Rule 82 'defblock', 5, sub #line 234 "Parser.yp" { my $name = join('/', @{ $_[0]->{ DEFBLOCKS } }); pop(@{ $_[0]->{ DEFBLOCKS } }); $_[0]->define_block($name, $_[4]); undef } ], [#Rule 83 'defblockname', 2, sub #line 241 "Parser.yp" { push(@{ $_[0]->{ DEFBLOCKS } }, $_[2]); $_[2]; } ], [#Rule 84 'blockname', 1, undef ], [#Rule 85 'blockname', 1, sub #line 247 "Parser.yp" { $_[1] =~ s/^'(.*)'$/$1/; $_[1] } ], [#Rule 86 'blockargs', 1, undef ], [#Rule 87 'blockargs', 0, undef ], [#Rule 88 'anonblock', 5, sub #line 255 "Parser.yp" { local $" = ', '; print STDERR "experimental block args: [@{ $_[2] }]\n" if $_[2]; $factory->anon_block($_[4]) } ], [#Rule 89 'capture', 3, sub #line 261 "Parser.yp" { $factory->capture(@_[1, 3]) } ], [#Rule 90 'macro', 6, sub #line 265 "Parser.yp" { $factory->macro(@_[2, 6, 4]) } ], [#Rule 91 'macro', 3, sub #line 266 "Parser.yp" { $factory->macro(@_[2, 3]) } ], [#Rule 92 'mdir', 1, undef ], [#Rule 93 'mdir', 4, sub #line 270 "Parser.yp" { $_[3] } ], [#Rule 94 'margs', 2, sub #line 273 "Parser.yp" { push(@{$_[1]}, $_[2]); $_[1] } ], [#Rule 95 'margs', 2, sub #line 274 "Parser.yp" { $_[1] } ], [#Rule 96 'margs', 1, sub #line 275 "Parser.yp" { [ $_[1] ] } ], [#Rule 97 'metadata', 2, sub #line 278 "Parser.yp" { push(@{$_[1]}, @{$_[2]}); $_[1] } ], [#Rule 98 'metadata', 2, undef ], [#Rule 99 'metadata', 1, undef ], [#Rule 100 'meta', 3, sub #line 283 "Parser.yp" { for ($_[3]) { s/^'//; s/'$//; s/\\'/'/g }; [ @_[1,3] ] } ], [#Rule 101 'meta', 5, sub #line 286 "Parser.yp" { [ @_[1,4] ] } ], [#Rule 102 'meta', 3, sub #line 287 "Parser.yp" { [ @_[1,3] ] } ], [#Rule 103 'term', 1, undef ], [#Rule 104 'term', 1, undef ], [#Rule 105 'lterm', 3, sub #line 299 "Parser.yp" { "[ $_[2] ]" } ], [#Rule 106 'lterm', 3, sub #line 300 "Parser.yp" { "[ $_[2] ]" } ], [#Rule 107 'lterm', 2, sub #line 301 "Parser.yp" { "[ ]" } ], [#Rule 108 'lterm', 3, sub #line 302 "Parser.yp" { "{ $_[2] }" } ], [#Rule 109 'sterm', 1, sub #line 305 "Parser.yp" { $factory->ident($_[1]) } ], [#Rule 110 'sterm', 2, sub #line 306 "Parser.yp" { $factory->identref($_[2]) } ], [#Rule 111 'sterm', 3, sub #line 307 "Parser.yp" { $factory->quoted($_[2]) } ], [#Rule 112 'sterm', 1, undef ], [#Rule 113 'sterm', 1, undef ], [#Rule 114 'list', 2, sub #line 312 "Parser.yp" { "$_[1], $_[2]" } ], [#Rule 115 'list', 2, undef ], [#Rule 116 'list', 1, undef ], [#Rule 117 'range', 3, sub #line 317 "Parser.yp" { $_[1] . '..' . $_[3] } ], [#Rule 118 'hash', 1, undef ], [#Rule 119 'hash', 0, sub #line 322 "Parser.yp" { "" } ], [#Rule 120 'params', 2, sub #line 325 "Parser.yp" { "$_[1], $_[2]" } ], [#Rule 121 'params', 2, undef ], [#Rule 122 'params', 1, undef ], [#Rule 123 'param', 3, sub #line 330 "Parser.yp" { "$_[1] => $_[3]" } ], [#Rule 124 'param', 3, sub #line 331 "Parser.yp" { "$_[1] => $_[3]" } ], [#Rule 125 'ident', 3, sub #line 334 "Parser.yp" { push(@{$_[1]}, @{$_[3]}); $_[1] } ], [#Rule 126 'ident', 3, sub #line 335 "Parser.yp" { push(@{$_[1]}, map {($_, 0)} split(/\./, $_[3])); $_[1]; } ], [#Rule 127 'ident', 1, undef ], [#Rule 128 'node', 1, sub #line 341 "Parser.yp" { [ $_[1], 0 ] } ], [#Rule 129 'node', 4, sub #line 342 "Parser.yp" { [ $_[1], $factory->args($_[3]) ] } ], [#Rule 130 'item', 1, sub #line 345 "Parser.yp" { "'$_[1]'" } ], [#Rule 131 'item', 3, sub #line 346 "Parser.yp" { $_[2] } ], [#Rule 132 'item', 2, sub #line 347 "Parser.yp" { $_[0]->{ V1DOLLAR } ? "'$_[2]'" : $factory->ident(["'$_[2]'", 0]) } ], [#Rule 133 'expr', 3, sub #line 352 "Parser.yp" { "$_[1] $_[2] $_[3]" } ], [#Rule 134 'expr', 3, sub #line 353 "Parser.yp" { "$_[1] $_[2] $_[3]" } ], [#Rule 135 'expr', 3, sub #line 354 "Parser.yp" { "$_[1] $_[2] $_[3]" } ], [#Rule 136 'expr', 3, sub #line 355 "Parser.yp" { "int($_[1] / $_[3])" } ], [#Rule 137 'expr', 3, sub #line 356 "Parser.yp" { "$_[1] % $_[3]" } ], [#Rule 138 'expr', 3, sub #line 357 "Parser.yp" { "$_[1] $CMPOP{ $_[2] } $_[3]" } ], [#Rule 139 'expr', 3, sub #line 358 "Parser.yp" { "$_[1] . $_[3]" } ], [#Rule 140 'expr', 3, sub #line 359 "Parser.yp" { "$_[1] && $_[3]" } ], [#Rule 141 'expr', 3, sub #line 360 "Parser.yp" { "$_[1] || $_[3]" } ], [#Rule 142 'expr', 2, sub #line 361 "Parser.yp" { "! $_[2]" } ], [#Rule 143 'expr', 5, sub #line 362 "Parser.yp" { "$_[1] ? $_[3] : $_[5]" } ], [#Rule 144 'expr', 3, sub #line 363 "Parser.yp" { $factory->assign(@{$_[2]}) } ], [#Rule 145 'expr', 3, sub #line 364 "Parser.yp" { "($_[2])" } ], [#Rule 146 'expr', 1, undef ], [#Rule 147 'setlist', 2, sub #line 368 "Parser.yp" { push(@{$_[1]}, @{$_[2]}); $_[1] } ], [#Rule 148 'setlist', 2, undef ], [#Rule 149 'setlist', 1, undef ], [#Rule 150 'assign', 3, sub #line 374 "Parser.yp" { [ $_[1], $_[3] ] } ], [#Rule 151 'assign', 3, sub #line 375 "Parser.yp" { [ @_[1,3] ] } ], [#Rule 152 'args', 2, sub #line 382 "Parser.yp" { push(@{$_[1]}, $_[2]); $_[1] } ], [#Rule 153 'args', 2, sub #line 383 "Parser.yp" { push(@{$_[1]->[0]}, $_[2]); $_[1] } ], [#Rule 154 'args', 4, sub #line 384 "Parser.yp" { push(@{$_[1]->[0]}, "'', " . $factory->assign(@_[2,4])); $_[1] } ], [#Rule 155 'args', 2, sub #line 386 "Parser.yp" { $_[1] } ], [#Rule 156 'args', 0, sub #line 387 "Parser.yp" { [ [ ] ] } ], [#Rule 157 'lnameargs', 3, sub #line 397 "Parser.yp" { push(@{$_[3]}, $_[1]); $_[3] } ], [#Rule 158 'lnameargs', 1, undef ], [#Rule 159 'lvalue', 1, undef ], [#Rule 160 'lvalue', 3, sub #line 402 "Parser.yp" { $factory->quoted($_[2]) } ], [#Rule 161 'lvalue', 1, undef ], [#Rule 162 'nameargs', 3, sub #line 406 "Parser.yp" { [ [$factory->ident($_[2])], $_[3] ] } ], [#Rule 163 'nameargs', 2, sub #line 407 "Parser.yp" { [ @_[1,2] ] } ], [#Rule 164 'nameargs', 4, sub #line 408 "Parser.yp" { [ @_[1,3] ] } ], [#Rule 165 'names', 3, sub #line 411 "Parser.yp" { push(@{$_[1]}, $_[3]); $_[1] } ], [#Rule 166 'names', 1, sub #line 412 "Parser.yp" { [ $_[1] ] } ], [#Rule 167 'name', 3, sub #line 415 "Parser.yp" { $factory->quoted($_[2]) } ], [#Rule 168 'name', 1, sub #line 416 "Parser.yp" { "'$_[1]'" } ], [#Rule 169 'name', 1, undef ], [#Rule 170 'filename', 3, sub #line 420 "Parser.yp" { "$_[1].$_[3]" } ], [#Rule 171 'filename', 1, undef ], [#Rule 172 'filepart', 1, undef ], [#Rule 173 'filepart', 1, undef ], [#Rule 174 'filepart', 1, undef ], [#Rule 175 'quoted', 2, sub #line 434 "Parser.yp" { push(@{$_[1]}, $_[2]) if defined $_[2]; $_[1] } ], [#Rule 176 'quoted', 0, sub #line 436 "Parser.yp" { [ ] } ], [#Rule 177 'quotable', 1, sub #line 439 "Parser.yp" { $factory->ident($_[1]) } ], [#Rule 178 'quotable', 1, sub #line 440 "Parser.yp" { $factory->text($_[1]) } ], [#Rule 179 'quotable', 1, sub #line 441 "Parser.yp" { undef } ] ]; } #--- END BEGIN 1; __END__ =head1 NAME Template::Grammar - Parser state/rule tables for the TT grammar =head1 SYNOPSIS # no user serviceable parts inside =head1 DESCRIPTION This module defines the state and rule tables that the L<Template::Parser> module uses to parse templates. It is generated from a YACC-like grammar using the C<Parse::Yapp> module. The F<parser> sub-directory of the Template Toolkit source distribution contains the grammar and other files required to generate this module. But you don't need to worry about any of that unless you're planning to modify the Template Toolkit language. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L<Template::Parser> =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: PK � �[ lib/auto/Template/.existsnu �[��� PK � �[ " lib/auto/Template/Stash/XS/.existsnu �[��� PK � �[1�m �& �& man3/Devel::CheckLib.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Devel::CheckLib 3" .TH Devel::CheckLib 3 "2022-05-04" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Devel::CheckLib \- check that a library is available .SH "DESCRIPTION" .IX Header "DESCRIPTION" Devel::CheckLib is a perl module that checks whether a particular C library and its headers are available. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Devel::CheckLib; \& \& check_lib_or_exit( lib => \*(Aqjpeg\*(Aq, header => \*(Aqjpeglib.h\*(Aq ); \& check_lib_or_exit( lib => [ \*(Aqiconv\*(Aq, \*(Aqjpeg\*(Aq ] ); \& \& # or prompt for path to library and then do this: \& check_lib_or_exit( lib => \*(Aqjpeg\*(Aq, libpath => $additional_path ); .Ve .SH "USING IT IN Makefile.PL or Build.PL" .IX Header "USING IT IN Makefile.PL or Build.PL" If you want to use this from Makefile.PL or Build.PL, do not simply copy the module into your distribution as this may cause problems when \s-1PAUSE\s0 and search.cpan.org index the distro. Instead, use the use-devel-checklib script. .SH "HOW IT WORKS" .IX Header "HOW IT WORKS" You pass named parameters to a function, describing to it how to build and link to the libraries. .PP It works by trying to compile some code \- which defaults to this: .PP .Vb 1 \& int main(int argc, char *argv[]) { return 0; } .Ve .PP and linking it to the specified libraries. If something pops out the end which looks executable, it gets executed, and if \fBmain()\fR returns 0 we know that it worked. That tiny program is built once for each library that you specify, and (without linking) once for each header file. .PP If you want to check for the presence of particular functions in a library, or even that those functions return particular results, then you can pass your own function body for \fBmain()\fR thus: .PP .Vb 7 \& check_lib_or_exit( \& function => \*(Aqfoo();if(libversion() > 5) return 0; else return 1;\*(Aq \& incpath => ... \& libpath => ... \& lib => ... \& header => ... \& ); .Ve .PP In that case, it will fail to build if either \fBfoo()\fR or \fBlibversion()\fR don't exist, and \fBmain()\fR will return the wrong value if \fBlibversion()\fR's return value isn't what you want. .SH "FUNCTIONS" .IX Header "FUNCTIONS" All of these take the same named parameters and are exported by default. To avoid exporting them, \f(CW\*(C`use Devel::CheckLib ()\*(C'\fR. .SS "assert_lib" .IX Subsection "assert_lib" This takes several named parameters, all of which are optional, and dies with an error message if any of the libraries listed can not be found. \fBNote\fR: dying in a Makefile.PL or Build.PL may provoke a '\s-1FAIL\s0' report from \s-1CPAN\s0 Testers' automated smoke testers. Use \&\f(CW\*(C`check_lib_or_exit\*(C'\fR instead. .PP The named parameters are: .IP "lib" 4 .IX Item "lib" Must be either a string with the name of a single library or a reference to an array of strings of library names. Depending on the compiler found, library names will be fed to the compiler either as \&\f(CW\*(C`\-l\*(C'\fR arguments or as \f(CW\*(C`.lib\*(C'\fR file names. (E.g. \f(CW\*(C`\-ljpeg\*(C'\fR or \f(CW\*(C`jpeg.lib\*(C'\fR) .IP "libpath" 4 .IX Item "libpath" a string or an array of strings representing additional paths to search for libraries. .IP "\s-1LIBS\s0" 4 .IX Item "LIBS" a \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR\-style space-separated list of libraries (each preceded by '\-l') and directories (preceded by '\-L'). .Sp This can also be supplied on the command-line. .IP "debug" 4 .IX Item "debug" If true \- emit information during processing that can be used for debugging. .PP And libraries are no use without header files, so ... .IP "header" 4 .IX Item "header" Must be either a string with the name of a single header file or a reference to an array of strings of header file names. .IP "incpath" 4 .IX Item "incpath" a string or an array of strings representing additional paths to search for headers. .IP "\s-1INC\s0" 4 .IX Item "INC" a \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR\-style space-separated list of incpaths, each preceded by '\-I'. .Sp This can also be supplied on the command-line. .IP "ccflags" 4 .IX Item "ccflags" Extra flags to pass to the compiler. .IP "ldflags" 4 .IX Item "ldflags" Extra flags to pass to the linker. .IP "analyze_binary" 4 .IX Item "analyze_binary" a callback function that will be invoked in order to perform custom analysis of the generated binary. The callback arguments are the library name and the path to the binary just compiled. .Sp It is possible to use this callback, for instance, to inspect the binary for further dependencies. .IP "not_execute" 4 .IX Item "not_execute" Do not try to execute generated binary. Only check that compilation has not failed. .SS "check_lib_or_exit" .IX Subsection "check_lib_or_exit" This behaves exactly the same as \f(CW\*(C`assert_lib()\*(C'\fR except that instead of dieing, it warns (with exactly the same error message) and exits. This is intended for use in Makefile.PL / Build.PL when you might want to prompt the user for various paths and things before checking that what they've told you is sane. .PP If any library or header is missing, it exits with an exit value of 0 to avoid causing a \s-1CPAN\s0 Testers '\s-1FAIL\s0' report. \s-1CPAN\s0 Testers should ignore this result \*(-- which is what you want if an external library dependency is not available. .SS "check_lib" .IX Subsection "check_lib" This behaves exactly the same as \f(CW\*(C`assert_lib()\*(C'\fR except that it is silent, returning false instead of dieing, or true otherwise. .SH "PLATFORMS SUPPORTED" .IX Header "PLATFORMS SUPPORTED" You must have a C compiler installed. We check for \f(CW$Config{cc}\fR, both literally as it is in Config.pm and also in the \f(CW$PATH\fR. .PP It has been tested with varying degrees of rigorousness on: .IP "gcc (on Linux, *BSD, Mac \s-1OS X,\s0 Solaris, Cygwin)" 4 .IX Item "gcc (on Linux, *BSD, Mac OS X, Solaris, Cygwin)" .PD 0 .IP "Sun's compiler tools on Solaris" 4 .IX Item "Sun's compiler tools on Solaris" .IP "\s-1IBM\s0's tools on \s-1AIX\s0" 4 .IX Item "IBM's tools on AIX" .IP "\s-1SGI\s0's tools on Irix 6.5" 4 .IX Item "SGI's tools on Irix 6.5" .IP "Microsoft's tools on Windows" 4 .IX Item "Microsoft's tools on Windows" .IP "MinGW on Windows (with Strawberry Perl)" 4 .IX Item "MinGW on Windows (with Strawberry Perl)" .IP "Borland's tools on Windows" 4 .IX Item "Borland's tools on Windows" .IP "\s-1QNX\s0" 4 .IX Item "QNX" .PD .SH "WARNINGS, BUGS and FEEDBACK" .IX Header "WARNINGS, BUGS and FEEDBACK" This is a very early release intended primarily for feedback from people who have discussed it. The interface may change and it has not been adequately tested. .PP Feedback is most welcome, including constructive criticism. Bug reports should be made using <http://rt.cpan.org/> or by email. .PP When submitting a bug report, please include the output from running: .PP .Vb 2 \& perl \-V \& perl \-MDevel::CheckLib \-e0 .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Devel::CheckOS .PP Probe::Perl .SH "AUTHORS" .IX Header "AUTHORS" David Cantrell <david@cantrell.org.uk> .PP David Golden <dagolden@cpan.org> .PP Yasuhiro Matsumoto <mattn@cpan.org> .PP Thanks to the cpan-testers-discuss mailing list for prompting us to write it in the first place; .PP to Chris Williams for help with Borland support; .PP to Tony Cook for help with Microsoft compiler command-line options .SH "COPYRIGHT and LICENCE" .IX Header "COPYRIGHT and LICENCE" Copyright 2007 David Cantrell. Portions copyright 2007 David Golden. .PP This module is free-as-in-speech software, and may be used, distributed, and modified under the same conditions as perl itself. .SH "CONSPIRACY" .IX Header "CONSPIRACY" This module is also free-as-in-mason software. PK � �[���Ep p man1/use-devel-checklib.1nu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "USE-DEVEL-CHECKLIB 1" .TH USE-DEVEL-CHECKLIB 1 "2022-05-04" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" use\-devel\-checklib \- (DEPRECATED)a script to package Devel::CheckLib with your code. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This script was \s-1DEPRECATED.\s0 .PP If you need to depend on this library, you should use `configure_requires` in Makefile.PL or Build.PL instead. .SH "WARNINGS, BUGS and FEEDBACK" .IX Header "WARNINGS, BUGS and FEEDBACK" This script has not been thoroughly tested. You should check by hand that it has done what you expected after running it. .PP If you use Module::Build::Compat to write a Makefile.PL, then you will need to re-run this script whenever you have generated a new Makefile.PL. .PP I welcome feedback about my code, including constructive criticism. Bug reports should be made using <http://rt.cpan.org/> or by email. .SH "SEE ALSO" .IX Header "SEE ALSO" Devel::CheckLib .SH "AUTHOR" .IX Header "AUTHOR" David Cantrell <\fIdavid@cantrell.org.uk\fR> .SH "COPYRIGHT and LICENCE" .IX Header "COPYRIGHT and LICENCE" Copyright 2007 David Cantrell .PP This software is free-as-in-speech software, and may be used, distributed, and modified under the same conditions as perl itself. .SH "CONSPIRACY" .IX Header "CONSPIRACY" This module is also free-as-in-mason software. PK � �[ arch/auto/Devel/CheckLib/.existsnu �[��� PK � �[�Ŗ� � script/use-devel-checklibnu ȯ�� #!/usr/bin/perl -w # $Id: use-devel-checklib,v 1.9 2008/03/12 19:52:50 drhyde Exp $ use strict; $/ = undef; use File::Spec; use Devel::CheckLib; warn "----------------------- [WARNING] --------\n"; warn "THIS SCRIPT WAS DEPRECATED.\n"; warn "YOU SHOULD USE configure_requires INSTEAD.\n"; warn "---------- [/WARNING] --------------------\n"; my @files = grep { -f $_ } qw(Makefile.PL Build.PL); push @files, 'Makefile.PL' unless(@files); my @libs = @ARGV; mkdir 'inc'; mkdir 'inc/Devel'; open(CHECKLIBPM, $INC{'Devel/CheckLib.pm'}) || die("Can't read $INC{'Devel/CheckLib.pm'}: $!"); (my $checklibpm = <CHECKLIBPM>) =~ s/package Devel::CheckLib/package #\nDevel::CheckLib/; close(CHECKLIBPM); open(CHECKLIBPM, '>'.File::Spec->catfile(qw(inc Devel CheckLib.pm))) || die("Can't write inc/Devel/CheckLib.pm: $!"); print CHECKLIBPM $checklibpm; close(CHECKLIBPM); print "Copied Devel::CheckLib to inc/ directory\n"; foreach my $file (@files) { open(FILE, $file) || next; my $contents = <FILE>; close(FILE); open(FILE, ">$file") || die("Can't write $file\n"); print FILE q{use lib qw(inc); use Devel::CheckLib; # Prompt the user here for any paths and other configuration check_lib_or_exit( # fill in what you prompted the user for here lib => [qw(}.join(' ', @libs).q{)] ); }; print FILE "\n\n$contents"; close(FILE); print "Updated/created $file\n"; } open(MANIFEST, 'MANIFEST') || warn("Couldn't read MANIFEST, will create one\n"); my $manifest = <MANIFEST>; close(MANIFEST); open(MANIFEST, '>MANIFEST') || die("Couldn't write MANIFEST\n"); print MANIFEST "inc/Devel/CheckLib.pm\n$manifest"; close(MANIFEST); print "Updated/created MANIFEST\n"; =head1 NAME use-devel-checklib - (DEPRECATED)a script to package Devel::CheckLib with your code. =head1 DESCRIPTION This script was DEPRECATED. If you need to depend on this library, you should use `configure_requires` in Makefile.PL or Build.PL instead. =head1 WARNINGS, BUGS and FEEDBACK This script has not been thoroughly tested. You should check by hand that it has done what you expected after running it. If you use Module::Build::Compat to write a Makefile.PL, then you will need to re-run this script whenever you have generated a new Makefile.PL. I welcome feedback about my code, including constructive criticism. Bug reports should be made using L<http://rt.cpan.org/> or by email. =head1 SEE ALSO L<Devel::CheckLib> =head1 AUTHOR David Cantrell E<lt>F<david@cantrell.org.uk>E<gt> =head1 COPYRIGHT and LICENCE Copyright 2007 David Cantrell This software is free-as-in-speech software, and may be used, distributed, and modified under the same conditions as perl itself. =head1 CONSPIRACY This module is also free-as-in-mason software. =cut PK � �[ lib/auto/Devel/CheckLib/.existsnu �[��� PK � �[ lib/Devel/.existsnu �[��� PK � �[��]�`I `I lib/Devel/CheckLib.pmnu ��6�$ # $Id: CheckLib.pm,v 1.25 2008/10/27 12:16:23 drhyde Exp $ package Devel::CheckLib; use 5.00405; #postfix foreach use strict; use vars qw($VERSION @ISA @EXPORT); $VERSION = '1.16'; use Config qw(%Config); use Text::ParseWords qw(quotewords shellwords); use File::Spec; use File::Temp; require Exporter; @ISA = qw(Exporter); @EXPORT = qw(assert_lib check_lib_or_exit check_lib); # localising prevents the warningness leaking out of this module local $^W = 1; # use warnings is a 5.6-ism _findcc(); # bomb out early if there's no compiler =head1 NAME Devel::CheckLib - check that a library is available =head1 DESCRIPTION Devel::CheckLib is a perl module that checks whether a particular C library and its headers are available. =head1 SYNOPSIS use Devel::CheckLib; check_lib_or_exit( lib => 'jpeg', header => 'jpeglib.h' ); check_lib_or_exit( lib => [ 'iconv', 'jpeg' ] ); # or prompt for path to library and then do this: check_lib_or_exit( lib => 'jpeg', libpath => $additional_path ); =head1 USING IT IN Makefile.PL or Build.PL If you want to use this from Makefile.PL or Build.PL, do not simply copy the module into your distribution as this may cause problems when PAUSE and search.cpan.org index the distro. Instead, use the use-devel-checklib script. =head1 HOW IT WORKS You pass named parameters to a function, describing to it how to build and link to the libraries. It works by trying to compile some code - which defaults to this: int main(int argc, char *argv[]) { return 0; } and linking it to the specified libraries. If something pops out the end which looks executable, it gets executed, and if main() returns 0 we know that it worked. That tiny program is built once for each library that you specify, and (without linking) once for each header file. If you want to check for the presence of particular functions in a library, or even that those functions return particular results, then you can pass your own function body for main() thus: check_lib_or_exit( function => 'foo();if(libversion() > 5) return 0; else return 1;' incpath => ... libpath => ... lib => ... header => ... ); In that case, it will fail to build if either foo() or libversion() don't exist, and main() will return the wrong value if libversion()'s return value isn't what you want. =head1 FUNCTIONS All of these take the same named parameters and are exported by default. To avoid exporting them, C<use Devel::CheckLib ()>. =head2 assert_lib This takes several named parameters, all of which are optional, and dies with an error message if any of the libraries listed can not be found. B<Note>: dying in a Makefile.PL or Build.PL may provoke a 'FAIL' report from CPAN Testers' automated smoke testers. Use C<check_lib_or_exit> instead. The named parameters are: =over =item lib Must be either a string with the name of a single library or a reference to an array of strings of library names. Depending on the compiler found, library names will be fed to the compiler either as C<-l> arguments or as C<.lib> file names. (E.g. C<-ljpeg> or C<jpeg.lib>) =item libpath a string or an array of strings representing additional paths to search for libraries. =item LIBS a C<ExtUtils::MakeMaker>-style space-separated list of libraries (each preceded by '-l') and directories (preceded by '-L'). This can also be supplied on the command-line. =item debug If true - emit information during processing that can be used for debugging. =back And libraries are no use without header files, so ... =over =item header Must be either a string with the name of a single header file or a reference to an array of strings of header file names. =item incpath a string or an array of strings representing additional paths to search for headers. =item INC a C<ExtUtils::MakeMaker>-style space-separated list of incpaths, each preceded by '-I'. This can also be supplied on the command-line. =item ccflags Extra flags to pass to the compiler. =item ldflags Extra flags to pass to the linker. =item analyze_binary a callback function that will be invoked in order to perform custom analysis of the generated binary. The callback arguments are the library name and the path to the binary just compiled. It is possible to use this callback, for instance, to inspect the binary for further dependencies. =item not_execute Do not try to execute generated binary. Only check that compilation has not failed. =back =head2 check_lib_or_exit This behaves exactly the same as C<assert_lib()> except that instead of dieing, it warns (with exactly the same error message) and exits. This is intended for use in Makefile.PL / Build.PL when you might want to prompt the user for various paths and things before checking that what they've told you is sane. If any library or header is missing, it exits with an exit value of 0 to avoid causing a CPAN Testers 'FAIL' report. CPAN Testers should ignore this result -- which is what you want if an external library dependency is not available. =head2 check_lib This behaves exactly the same as C<assert_lib()> except that it is silent, returning false instead of dieing, or true otherwise. =cut sub check_lib_or_exit { eval 'assert_lib(@_)'; if($@) { warn $@; exit; } } sub check_lib { eval 'assert_lib(@_)'; return $@ ? 0 : 1; } # borrowed from Text::ParseWords sub _parse_line { my($delimiter, $keep, $line) = @_; my($word, @pieces); no warnings 'uninitialized'; # we will be testing undef strings while (length($line)) { # This pattern is optimised to be stack conservative on older perls. # Do not refactor without being careful and testing it on very long strings. # See Perl bug #42980 for an example of a stack busting input. $line =~ s/^ (?: # double quoted string (") # $quote ((?>[^\\"]*(?:\\.[^\\"]*)*))" # $quoted | # --OR-- # singe quoted string (') # $quote ((?>[^\\']*(?:\\.[^\\']*)*))' # $quoted | # --OR-- # unquoted string ( # $unquoted (?:\\.|[^\\"'])*? ) # followed by ( # $delim \Z(?!\n) # EOL | # --OR-- (?-x:$delimiter) # delimiter | # --OR-- (?!^)(?=["']) # a quote ) )//xs or return; # extended layout my ($quote, $quoted, $unquoted, $delim) = (($1 ? ($1,$2) : ($3,$4)), $5, $6); return() unless( defined($quote) || length($unquoted) || length($delim)); if ($keep) { $quoted = "$quote$quoted$quote"; } else { $unquoted =~ s/\\(.)/$1/sg; if (defined $quote) { $quoted =~ s/\\(.)/$1/sg if ($quote eq '"'); } } $word .= substr($line, 0, 0); # leave results tainted $word .= defined $quote ? $quoted : $unquoted; if (length($delim)) { push(@pieces, $word); push(@pieces, $delim) if ($keep eq 'delimiters'); undef $word; } if (!length($line)) { push(@pieces, $word); } } return(@pieces); } sub _parsewords { return shellwords @_ if $^O ne 'MSWin32'; # for Win32, take off "" but leave \ map { my $s=$_; $s =~ s/^"(.*)"$/$1/; $s } grep defined && length, quotewords '\s+', 1, @_; } sub _compile_cmd { my ($Config_cc, $cc, $cfile, $exefile, $incpaths, $ld, $Config_libs, $lib, $libpaths) = @_; my @sys_cmd = @$cc; if ( $Config_cc eq 'cl' ) { # Microsoft compiler # this is horribly sensitive to the order of arguments push @sys_cmd, $cfile, (defined $lib ? "${lib}.lib" : ()), "/Fe$exefile", (map '/I'.$_, @$incpaths), "/link", @$ld, _parsewords($Config_libs), (defined $lib ? map '/libpath:'.$_, @$libpaths : ()), ; } elsif($Config_cc =~ /bcc32(\.exe)?/) { # Borland push @sys_cmd, @$ld, (map "-I$_", @$incpaths), "-o$exefile", (defined $lib ? ((map "-L$_", @$libpaths), "-l$lib") : ()), $cfile, ; } else { # Unix-ish: gcc, Sun, AIX (gcc, cc), ... push @sys_cmd, (map "-I$_", @$incpaths), $cfile, (!defined $lib ? () : ( (map "-L$_", @$libpaths), ($^O eq 'darwin' ? (map { "-Wl,-rpath,$_" } @$libpaths) : ()), "-l$lib", )), @$ld, "-o", $exefile, ; } @sys_cmd; } sub _make_cfile { my ($use_headers, $function, $debug) = @_; my $code = ''; $code .= qq{#include <$_>\n} for @$use_headers; $code .= "int main(int argc, char *argv[]) { ".($function || 'return 0;')." }\n"; if ($debug) { (my $c = $code) =~ s:^:# :gm; warn "# Code:\n$c\n"; } my ($ch, $cfile) = File::Temp::tempfile( 'assertlibXXXXXXXX', SUFFIX => '.c' ); print $ch $code; close $ch; (my $ofile = $cfile) =~ s/\.c$/$Config{_o}/; ($cfile, $ofile); } sub assert_lib { my %args = @_; $args{$_} = [$args{$_}] for grep $args{$_} && !ref($args{$_}), qw(lib libpath header incpath); my @libs = @{$args{lib} || []}; my @libpaths = @{$args{libpath} || []}; my @headers = @{$args{header} || []}; my @incpaths = @{$args{incpath} || []}; my $analyze_binary = $args{analyze_binary}; my $execute = !$args{not_execute}; my @argv = @ARGV; push @argv, _parse_line('\s+', 0, $ENV{PERL_MM_OPT}||''); # work-a-like for Makefile.PL's LIBS and INC arguments # if given as command-line argument, append to %args for my $arg (@argv) { for my $mm_attr_key (qw(LIBS INC)) { if (my ($mm_attr_value) = $arg =~ /\A $mm_attr_key = (.*)/x) { # it is tempting to put some \s* into the expression, but the # MM command-line parser only accepts LIBS etc. followed by =, # so we should not be any more lenient with whitespace than that $args{$mm_attr_key} .= " $mm_attr_value"; } } } if(defined($args{LIBS})) { foreach my $arg (_parsewords($args{LIBS})) { die("LIBS argument badly-formed: $arg\n") unless($arg =~ /^-[lLR]/); push @{$arg =~ /^-l/ ? \@libs : \@libpaths}, substr($arg, 2); } } if(defined($args{INC})) { foreach my $arg (_parsewords($args{INC})) { die("INC argument badly-formed: $arg\n") unless($arg =~ /^-I/); push @incpaths, substr($arg, 2); } } my ($cc, $ld) = _findcc($args{debug}, $args{ccflags}, $args{ldflags}); my @missing; my @wrongresult; my @wronganalysis; my @use_headers; # first figure out which headers we can't find ... for my $header (@headers) { push @use_headers, $header; my ($cfile, $ofile) = _make_cfile(\@use_headers, '', $args{debug}); my $exefile = File::Temp::mktemp( 'assertlibXXXXXXXX' ) . $Config{_exe}; my @sys_cmd = _compile_cmd($Config{cc}, $cc, $cfile, $exefile, \@incpaths, $ld, $Config{libs}); warn "# @sys_cmd\n" if $args{debug}; my $rv = $args{debug} ? system(@sys_cmd) : _quiet_system(@sys_cmd); push @missing, $header if $rv != 0 || ! -f $exefile; _cleanup_exe($exefile); unlink $cfile; } # now do each library in turn with headers my ($cfile, $ofile) = _make_cfile(\@use_headers, @args{qw(function debug)}); for my $lib ( @libs ) { last if $Config{cc} eq 'CC/DECC'; # VMS my $exefile = File::Temp::mktemp( 'assertlibXXXXXXXX' ) . $Config{_exe}; my @sys_cmd = _compile_cmd($Config{cc}, $cc, $cfile, $exefile, \@incpaths, $ld, $Config{libs}, $lib, \@libpaths); warn "# @sys_cmd\n" if $args{debug}; local $ENV{LD_RUN_PATH} = join(":", grep $_, @libpaths, $ENV{LD_RUN_PATH}) unless $^O eq 'MSWin32' or $^O eq 'darwin'; local $ENV{PATH} = join(";", @libpaths).";".$ENV{PATH} if $^O eq 'MSWin32'; my $rv = $args{debug} ? system(@sys_cmd) : _quiet_system(@sys_cmd); if ($rv != 0 || ! -f $exefile) { push @missing, $lib; } else { chmod 0755, $exefile; my $absexefile = File::Spec->rel2abs($exefile); $absexefile = '"'.$absexefile.'"' if $absexefile =~ m/\s/; warn "# Execute($execute): $absexefile\n" if $args{debug}; if ($execute) { my $retval = system($absexefile); warn "# return value: $retval\n" if $args{debug}; push @wrongresult, $lib if $retval != 0; } push @wronganalysis, $lib if $analyze_binary and !$analyze_binary->($lib, $exefile); } _cleanup_exe($exefile); } unlink $cfile; my $miss_string = join( q{, }, map qq{'$_'}, @missing ); die("Can't link/include C library $miss_string, aborting.\n") if @missing; my $wrong_string = join( q{, }, map qq{'$_'}, @wrongresult); die("wrong result: $wrong_string\n") if @wrongresult; my $analysis_string = join(q{, }, map qq{'$_'}, @wronganalysis ); die("wrong analysis: $analysis_string") if @wronganalysis; } sub _cleanup_exe { my ($exefile) = @_; my $ofile = $exefile; $ofile =~ s/$Config{_exe}$/$Config{_o}/; # List of files to remove my @rmfiles; push @rmfiles, $exefile, $ofile, "$exefile\.manifest"; if ( $Config{cc} eq 'cl' ) { # MSVC also creates foo.ilk and foo.pdb my $ilkfile = $exefile; $ilkfile =~ s/$Config{_exe}$/.ilk/; my $pdbfile = $exefile; $pdbfile =~ s/$Config{_exe}$/.pdb/; push @rmfiles, $ilkfile, $pdbfile; } foreach (grep -f, @rmfiles) { unlink $_ or warn "Could not remove $_: $!"; } return } # return ($cc, $ld) # where $cc is an array ref of compiler name, compiler flags # where $ld is an array ref of linker flags sub _findcc { my ($debug, $user_ccflags, $user_ldflags) = @_; # Need to use $keep=1 to work with MSWin32 backslashes and quotes my $Config_ccflags = $Config{ccflags}; # use copy so ASPerl will compile $Config_ccflags =~ s:-O\S*::; # stop GCC optimising away test code my @Config_ldflags = (); for my $config_val ( @Config{qw(ldflags)} ){ push @Config_ldflags, $config_val if ( $config_val =~ /\S/ ); } my @ccflags = grep { length } _parsewords($Config_ccflags||'', $user_ccflags||''); my @ldflags = grep { length && $_ !~ m/^-Wl/ } _parsewords(@Config_ldflags, $user_ldflags||''); my @paths = split(/$Config{path_sep}/, $ENV{PATH}); my @cc = _parsewords($Config{cc}); if (check_compiler ($cc[0], $debug)) { return ( [ @cc, @ccflags ], \@ldflags ); } # Find the extension for executables. my $exe = $Config{_exe}; if ($^O eq 'cygwin') { $exe = ''; } foreach my $path (@paths) { # Look for "$path/$cc[0].exe" my $compiler = File::Spec->catfile($path, $cc[0]) . $exe; if (check_compiler ($compiler, $debug)) { return ([ $compiler, @cc[1 .. $#cc], @ccflags ], \@ldflags) } next if ! $exe; # Look for "$path/$cc[0]" without the .exe, if necessary. $compiler = File::Spec->catfile($path, $cc[0]); if (check_compiler ($compiler, $debug)) { return ([ $compiler, @cc[1 .. $#cc], @ccflags ], \@ldflags) } } die("Couldn't find your C compiler.\n"); } sub check_compiler { my ($compiler, $debug) = @_; if (-f $compiler && -x $compiler) { warn "# Compiler seems to be $compiler\n" if $debug; return 1; } warn "# Compiler was not $compiler\n" if $debug; return ''; } # code substantially borrowed from IPC::Run3 sub _quiet_system { my (@cmd) = @_; # save handles local *STDOUT_SAVE; local *STDERR_SAVE; open STDOUT_SAVE, ">&STDOUT" or die "CheckLib: $! saving STDOUT"; open STDERR_SAVE, ">&STDERR" or die "CheckLib: $! saving STDERR"; # redirect to nowhere local *DEV_NULL; open DEV_NULL, ">" . File::Spec->devnull or die "CheckLib: $! opening handle to null device"; open STDOUT, ">&" . fileno DEV_NULL or die "CheckLib: $! redirecting STDOUT to null handle"; open STDERR, ">&" . fileno DEV_NULL or die "CheckLib: $! redirecting STDERR to null handle"; # run system command my $rv = system(@cmd); # restore handles open STDOUT, ">&" . fileno STDOUT_SAVE or die "CheckLib: $! restoring STDOUT handle"; open STDERR, ">&" . fileno STDERR_SAVE or die "CheckLib: $! restoring STDERR handle"; return $rv; } =head1 PLATFORMS SUPPORTED You must have a C compiler installed. We check for C<$Config{cc}>, both literally as it is in Config.pm and also in the $PATH. It has been tested with varying degrees of rigorousness on: =over =item gcc (on Linux, *BSD, Mac OS X, Solaris, Cygwin) =item Sun's compiler tools on Solaris =item IBM's tools on AIX =item SGI's tools on Irix 6.5 =item Microsoft's tools on Windows =item MinGW on Windows (with Strawberry Perl) =item Borland's tools on Windows =item QNX =back =head1 WARNINGS, BUGS and FEEDBACK This is a very early release intended primarily for feedback from people who have discussed it. The interface may change and it has not been adequately tested. Feedback is most welcome, including constructive criticism. Bug reports should be made using L<http://rt.cpan.org/> or by email. When submitting a bug report, please include the output from running: perl -V perl -MDevel::CheckLib -e0 =head1 SEE ALSO L<Devel::CheckOS> L<Probe::Perl> =head1 AUTHORS David Cantrell E<lt>david@cantrell.org.ukE<gt> David Golden E<lt>dagolden@cpan.orgE<gt> Yasuhiro Matsumoto E<lt>mattn@cpan.orgE<gt> Thanks to the cpan-testers-discuss mailing list for prompting us to write it in the first place; to Chris Williams for help with Borland support; to Tony Cook for help with Microsoft compiler command-line options =head1 COPYRIGHT and LICENCE Copyright 2007 David Cantrell. Portions copyright 2007 David Golden. This module is free-as-in-speech software, and may be used, distributed, and modified under the same conditions as perl itself. =head1 CONSPIRACY This module is also free-as-in-mason software. =cut 1; PK � �[� �K�3 �3 man3/NetAddr::IP::InetBase.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "NetAddr::IP::InetBase 3" .TH NetAddr::IP::InetBase 3 "2012-10-02" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" NetAddr::IP::InetBase \-\- IPv4 and IPV6 utilities .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use NetAddr::IP::Base qw( \& :upper \& inet_aton \& inet_ntoa \& ipv6_aton \& ipv6_ntoa \& ipv6_n2x \& ipv6_n2d \& inet_any2n \& inet_n2dx \& inet_n2ad \& inet_pton \& inet_ntop \& packzeros \& isIPv4 \& isNewIPv4 \& isAnyIPv4 \& AF_INET \& AF_INET6 \& fake_AF_INET6 \& fillIPv4 \& ); \& \& use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math) \& \& :ipv4 => inet_aton, inet_ntoa, fillIPv4 \& \& :ipv6 => ipv6_aton, ipv6_ntoa,ipv6_n2x, ipv6_n2d, \& inet_any2n, inet_n2dx, inet_n2ad \& inet_pton, inet_ntop, packzeros \& \& $dotquad = inet_ntoa($netaddr); \& $netaddr = inet_aton($dotquad); \& $ipv6naddr = ipv6_aton($ipv6_text); \& $ipv6_text = ipv6_ntoa($ipv6naddr); \& $hex_text = ipv6_n2x($ipv6naddr); \& $dec_text = ipv6_n2d($ipv6naddr); \& $ipv6naddr = inet_any2n($dotquad or $ipv6_text); \& $dotquad or $hex_text = inet_n2dx($ipv6naddr); \& $dotquad or $dec_text = inet_n2ad($ipv6naddr); \& $netaddr = inet_pton($AF_family,$text_addr); \& $text_addr = inet_ntop($AF_family,$netaddr); \& $hex_text = packzeros($hex_text); \& $rv = isIPv4($bits128); \& $rv = isNewIPv4($bits128); \& $rv = isAnyIPv4($bits128); \& $constant = AF_INET(); \& $constant = AF_INET6(); \& $trueif = fake_AF_INET6(); \& $ip_filled = fillIPv4($shortIP); \& \& NetAddr::IP::InetBase::lower(); \& NetAddr::IP::InetBase::upper(); .Ve .SH "INSTALLATION" .IX Header "INSTALLATION" Un-tar the distribution in an appropriate directory and type: .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBNetAddr::IP::InetBase\fR provides a suite network of conversion functions written in pure Perl for converting both IPv4 and IPv6 addresses to and from network address format and text format. .PP The IPv6 functions support all rfc1884 formats. .PP .Vb 5 \& i.e. x:x:x:x:x:x:x:x:x \& x:x:x:x:x:x:x:d.d.d.d \& ::x:x:x \& ::x:d.d.d.d \& and so on... .Ve .IP "\(bu" 4 \&\f(CW$dotquad\fR = inet_ntoa($netaddr); .Sp Convert a packed IPv4 network address to a dot-quad \s-1IP\s0 address. .Sp .Vb 2 \& input: packed network address \& returns: IP address i.e. 10.4.12.123 .Ve .IP "\(bu" 4 \&\f(CW$netaddr\fR = inet_aton($dotquad); .Sp Convert a dot-quad \s-1IP\s0 address into an IPv4 packed network address. .Sp .Vb 2 \& input: IP address i.e. 192.5.16.32 \& returns: packed network address .Ve .IP "\(bu" 4 \&\f(CW$ipv6addr\fR = ipv6_aton($ipv6_text); .Sp Takes an IPv6 address of the form described in rfc1884 and returns a 128 bit binary \s-1RDATA\s0 string. .Sp .Vb 2 \& input: ipv6 text \& returns: 128 bit RDATA string .Ve .IP "\(bu" 4 \&\f(CW$ipv6text\fR = ipv6_ntoa($ipv6naddr); .Sp Convert a 128 bit binary IPv6 address to compressed rfc 1884 text representation. .Sp .Vb 2 \& input: 128 bit RDATA string \& returns: ipv6 text .Ve .IP "\(bu" 4 \&\f(CW$hex_text\fR = ipv6_n2x($ipv6addr); .Sp Takes an IPv6 \s-1RDATA\s0 string and returns an 8 segment IPv6 hex address .Sp .Vb 2 \& input: 128 bit RDATA string \& returns: x:x:x:x:x:x:x:x \& \& Note: this function does NOT compress adjacent \& strings of 0:0:0:0 into the :: format .Ve .IP "\(bu" 4 \&\f(CW$dec_text\fR = ipv6_n2d($ipv6addr); .Sp Takes an IPv6 \s-1RDATA\s0 string and returns a mixed hex \- decimal IPv6 address with the 6 uppermost chunks in hex and the lower 32 bits in dot-quad representation. .Sp .Vb 2 \& input: 128 bit RDATA string \& returns: x:x:x:x:x:x:d.d.d.d \& \& Note: this function does NOT compress adjacent \& strings of 0:0:0:0 into the :: format .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = inet_any2n($dotquad or \f(CW$ipv6_text\fR); .Sp This function converts a text IPv4 or IPv6 address in text format in any standard notation into a 128 bit IPv6 string address. It prefixes any dot-quad address (if found) with '::' and passes it to \fBipv6_aton\fR. .Sp .Vb 2 \& input: dot\-quad or rfc1844 address \& returns: 128 bit IPv6 string .Ve .IP "\(bu" 4 \&\f(CW$dotquad\fR or \f(CW$hex_text\fR = inet_n2dx($ipv6naddr); .Sp This function \fBdoes the right thing\fR and returns the text for either a dot-quad IPv4 or a hex notation IPv6 address. .Sp .Vb 3 \& input: 128 bit IPv6 string \& returns: ddd.ddd.ddd.ddd \& or x:x:x:x:x:x:x:x \& \& Note: this function does NOT compress adjacent \& strings of 0:0:0:0 into the :: format .Ve .IP "\(bu" 4 \&\f(CW$dotquad\fR or \f(CW$dec_text\fR = inet_n2ad($ipv6naddr); .Sp This function \fBdoes the right thing\fR and returns the text for either a dot-quad IPv4 or a hex::decimal notation IPv6 address. .Sp .Vb 3 \& input: 128 bit IPv6 string \& returns: ddd.ddd.ddd.ddd \& or x:x:x:x:x:x:ddd.ddd.ddd.dd \& \& Note: this function does NOT compress adjacent \& strings of 0:0:0:0 into the :: format .Ve .IP "\(bu" 4 \&\f(CW$netaddr\fR = inet_pton($AF_family,$text_addr); .Sp This function takes an \s-1IP\s0 address in IPv4 or IPv6 text format and converts it into binary format. The type of \s-1IP\s0 address conversion is controlled by the \s-1FAMILY\s0 argument. .Sp \&\s-1NOTE:\s0 inet_pton, inet_ntop and \s-1AF_INET6\s0 come from the Socket6 library if it is present on this host. .IP "\(bu" 4 \&\f(CW$text_addr\fR = inet_ntop($AF_family,$netaddr); .Sp This function takes and \s-1IP\s0 address in binary format and converts it into text format. The type of \s-1IP\s0 address conversion is controlled by the \s-1FAMILY\s0 argument. .Sp \&\s-1NOTE:\s0 inet_ntop \s-1ALWAYS\s0 returns lowercase characters. .Sp \&\s-1NOTE:\s0 inet_pton, inet_ntop and \s-1AF_INET6\s0 come from the Socket6 library if it is present on this host. .IP "\(bu" 4 \&\f(CW$hex_text\fR = packzeros($hex_text); .Sp This function optimizes and rfc 1884 IPv6 hex address to reduce the number of long strings of zero bits as specified in rfc 1884, 2.2 (2) by substituting \&\fB::\fR for the first occurence of the longest string of zeros in the address. .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = ipv4to6($netaddr); .Sp Convert an ipv4 network address into an ipv6 network address. .Sp .Vb 2 \& input: 32 bit network address \& returns: 128 bit network address .Ve .IP "\(bu" 4 \&\f(CW$rv\fR = isIPv4($bits128); .Sp This function returns true if there are no on bits present in the IPv6 portion of the 128 bit string and false otherwise. .Sp .Vb 1 \& i.e. the address must be of the form \- ::d.d.d.d .Ve .Sp Note: this is an old and deprecated ipV4 compatible ipV6 address .IP "\(bu" 4 \&\f(CW$rv\fR = isNewIPv4($bits128); .Sp This function return true if the IPv6 128 bit string is of the form .Sp .Vb 1 \& ::ffff:d.d.d.d .Ve .IP "\(bu" 4 \&\f(CW$rv\fR = isAnyIPv4($bits128); .Sp This function return true if the IPv6 bit string is of the form .Sp .Vb 1 \& ::d.d.d.d or ::ffff:d.d.d.d .Ve .IP "\(bu" 4 \&\fBNetAddr::IP::InetBase::lower()\fR; .Sp Return IPv6 strings in lowercase. This is the default. .IP "\(bu" 4 \&\fBNetAddr::IP::InetBase::upper()\fR; .Sp Return IPv6 strings in uppercase. .Sp The default may be set to uppercase when the module is loaded by invoking the \s-1TAG\s0 :upper. i.e. .Sp .Vb 1 \& use NetAddr::IP::InetBase qw( :upper ); .Ve .IP "\(bu" 4 \&\f(CW$constant\fR = \s-1AF_INET\s0; .Sp This function returns the system value for \s-1AF_INET.\s0 .IP "\(bu" 4 \&\f(CW$constant\fR = \s-1AF_INET6\s0; .Sp \&\s-1AF_INET6\s0 is sometimes present in the Socket library and always present in the Socket6 library. When the Socket library does not contain \s-1AF_INET6\s0 and when Socket6 is not present, a place holder value is \f(CW\*(C`guessed\*(C'\fR based on the underlying host operating system. See \fBfake_AF_INET6\fR below. .Sp \&\s-1NOTE:\s0 inet_pton, inet_ntop and \s-1AF_INET6\s0 come from the Socket6 library if it is present on this host. .IP "\(bu" 4 \&\f(CW$trueif\fR = fake_AF_INET6; .Sp This function return \s-1FALSE\s0 if \s-1AF_INET6\s0 is provided by Socket or Socket6. Otherwise, it returns the best guess value based on name of the host operating system. .IP "\(bu" 4 \&\f(CW$ip_filled\fR = fillIPv4($shortIP); .Sp This function converts IPv4 addresses of the form 127.1 to the long form 127.0.0.1 .Sp If the function is passed an argument that does not match the form of an \s-1IP\s0 address, the original argument is returned. i.e. pass it a hostname or a short \s-1IP\s0 and it will return a hostname or a filled \s-1IP.\s0 .SH "EXPORT_OK" .IX Header "EXPORT_OK" .Vb 10 \& :upper \& inet_aton \& inet_ntoa \& ipv6_aton \& ipv6_ntoa \& ipv6_n2x \& ipv6_n2d \& inet_any2n \& inet_n2dx \& inet_n2ad \& inet_pton \& inet_ntop \& packzeros \& isIPv4 \& isNewIPv4 \& isAnyIPv4 \& AF_INET \& AF_INET6 \& fake_AF_INET6 \& fillIPv4 .Ve .ie n .SH "%EXPORT_TAGS" .el .SH "\f(CW%EXPORT_TAGS\fP" .IX Header "%EXPORT_TAGS" .Vb 4 \& :all \& :ipv4 \& :ipv6 \& :upper .Ve .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton <michael@bizsystems.com> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2003 \- 2012, Michael Robinton <michael@bizsystems.com> .PP All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: .PP .Vb 3 \& a) the GNU General Public License as published by the Free \& Software Foundation; either version 2, or (at your option) any \& later version, or \& \& b) the "Artistic License" which comes with this distribution. .Ve .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the \s-1GNU\s0 General Public License or the Artistic License for more details. .PP You should have received a copy of the Artistic License with this distribution, in the file named \*(L"Artistic\*(R". If not, I'll be glad to provide one. .PP You should also have received a copy of the \s-1GNU\s0 General Public License along with this program in the file named \*(L"Copying\*(R". If not, write to the .PP .Vb 3 \& Free Software Foundation, Inc., \& 51 Franklin Street, Fifth Floor \& Boston, MA 02110\-1301 USA .Ve .PP or visit their web page on the internet at: .PP .Vb 1 \& http://www.gnu.org/copyleft/gpl.html. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton <michael@bizsystems.com> .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBNetAddr::IP\fR\|(3), \fBNetAddr::IP::Lite\fR\|(3), \fBNetAddr::IP::Util\fR\|(3) PK � �[�o%�V �V man3/NetAddr::IP::Util.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Util 3" .TH Util 3 "2015-08-17" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" NetAddr::IP::Util \-\- IPv4/6 and 128 bit number utilities .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use NetAddr::IP::Util qw( \& inet_aton \& inet_ntoa \& ipv6_aton \& ipv6_ntoa \& ipv6_n2x \& ipv6_n2d \& inet_any2n \& hasbits \& isIPv4 \& isNewIPv4 \& isAnyIPv4 \& inet_n2dx \& inet_n2ad \& inet_pton \& inet_ntop \& inet_4map6 \& ipv4to6 \& mask4to6 \& ipanyto6 \& maskanyto6 \& ipv6to4 \& packzeros \& shiftleft \& addconst \& add128 \& sub128 \& notcontiguous \& bin2bcd \& bcd2bin \& mode \& AF_INET \& AF_INET6 \& naip_gethostbyname \& ); \& \& use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math) \& \& :inet => inet_aton, inet_ntoa, ipv6_aton \& ipv6_ntoa, ipv6_n2x, ipv6_n2d, \& inet_any2n, inet_n2dx, inet_n2ad, \& inet_pton, inet_ntop, inet_4map6, \& ipv4to6, mask4to6, ipanyto6, packzeros \& maskanyto6, ipv6to4, naip_gethostbyname \& \& :ipv4 => inet_aton, inet_ntoa \& \& :ipv6 => ipv6_aton, ipv6_ntoa, ipv6_n2x, \& ipv6_n2d, inet_any2n, inet_n2dx, \& inet_n2ad, inet_pton, inet_ntop, \& inet_4map6, ipv4to6, mask4to6, \& ipanyto6, maskanyto6, ipv6to4, \& packzeros, naip_gethostbyname \& \& :math => hasbits, isIPv4, isNewIPv4, isAnyIPv4, \& addconst, add128, sub128, notcontiguous, \& bin2bcd, bcd2bin, shiftleft \& \& $dotquad = inet_ntoa($netaddr); \& $netaddr = inet_aton($dotquad); \& $ipv6naddr = ipv6_aton($ipv6_text); \& $ipv6_text = ipvt_ntoa($ipv6naddr); \& $hex_text = ipv6_n2x($ipv6naddr); \& $dec_text = ipv6_n2d($ipv6naddr); \& $hex_text = packzeros($hex_text); \& $ipv6naddr = inet_any2n($dotquad or $ipv6_text); \& $ipv6naddr = inet_4map6($netaddr or $ipv6naddr); \& $rv = hasbits($bits128); \& $rv = isIPv4($bits128); \& $rv = isNewIPv4($bits128); \& $rv = isAnyIPv4($bits128); \& $dotquad or $hex_text = inet_n2dx($ipv6naddr); \& $dotquad or $dec_text = inet_n2ad($ipv6naddr); \& $netaddr = inet_pton($AF_family,$hex_text); \& $hex_text = inet_ntop($AF_family,$netaddr); \& $ipv6naddr = ipv4to6($netaddr); \& $ipv6naddr = mask4to6($netaddr); \& $ipv6naddr = ipanyto6($netaddr); \& $ipv6naddr = maskanyto6($netaddr); \& $netaddr = ipv6to4($pv6naddr); \& $bitsX2 = shiftleft($bits128,$n); \& $carry = addconst($ipv6naddr,$signed_32con); \& ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con); \& $carry = add128($ipv6naddr1,$ipv6naddr2); \& ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2); \& $carry = sub128($ipv6naddr1,$ipv6naddr2); \& ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2); \& ($spurious,$cidr) = notcontiguous($mask128); \& $bcdtext = bin2bcd($bits128); \& $bits128 = bcd2bin($bcdtxt); \& $modetext = mode; \& ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME); \& $trueif = havegethostbyname2(); \& \& NetAddr::IP::Util::lower(); \& NetAddr::IP::Util::upper(); .Ve .SH "INSTALLATION" .IX Header "INSTALLATION" Un-tar the distribution in an appropriate directory and type: .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP \&\fBNetAddr::IP::Util\fR installs by default with its primary functions compiled using Perl's \s-1XS\s0 extensions to build a 'C' library. If you do not have a 'C' complier available or would like the slower Pure Perl version for some other reason, then type: .PP .Vb 4 \& perl Makefile.PL \-noxs \& make \& make test \& make install .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBNetAddr::IP::Util\fR provides a suite of tools for manipulating and converting IPv4 and IPv6 addresses into 128 bit string context and back to text. The strings can be manipulated with Perl's logical operators: .PP .Vb 4 \& and & \& or | \& xor ^ \& ~ compliment .Ve .PP in the same manner as 'vec' strings. .PP The IPv6 functions support all rfc1884 formats. .PP .Vb 5 \& i.e. x:x:x:x:x:x:x:x:x \& x:x:x:x:x:x:x:d.d.d.d \& ::x:x:x \& ::x:d.d.d.d \& and so on... .Ve .IP "\(bu" 4 \&\f(CW$dotquad\fR = inet_ntoa($netaddr); .Sp Convert a packed IPv4 network address to a dot-quad \s-1IP\s0 address. .Sp .Vb 2 \& input: packed network address \& returns: IP address i.e. 10.4.12.123 .Ve .IP "\(bu" 4 \&\f(CW$netaddr\fR = inet_aton($dotquad); .Sp Convert a dot-quad \s-1IP\s0 address into an IPv4 packed network address. .Sp .Vb 2 \& input: IP address i.e. 192.5.16.32 \& returns: packed network address .Ve .IP "\(bu" 4 \&\f(CW$ipv6addr\fR = ipv6_aton($ipv6_text); .Sp Takes an IPv6 address of the form described in rfc1884 and returns a 128 bit binary \s-1RDATA\s0 string. .Sp .Vb 2 \& input: ipv6 text \& returns: 128 bit RDATA string .Ve .IP "\(bu" 4 \&\f(CW$ipv6_text\fR = ipv6_ntoa($ipv6naddr); .Sp Convert a 128 bit binary IPv6 address to compressed rfc 1884 text representation. .Sp .Vb 2 \& input: 128 bit RDATA string \& returns: ipv6 text .Ve .IP "\(bu" 4 \&\f(CW$hex_text\fR = ipv6_n2x($ipv6addr); .Sp Takes an IPv6 \s-1RDATA\s0 string and returns an 8 segment IPv6 hex address .Sp .Vb 2 \& input: 128 bit RDATA string \& returns: x:x:x:x:x:x:x:x .Ve .IP "\(bu" 4 \&\f(CW$dec_text\fR = ipv6_n2d($ipv6addr); .Sp Takes an IPv6 \s-1RDATA\s0 string and returns a mixed hex \- decimal IPv6 address with the 6 uppermost chunks in hex and the lower 32 bits in dot-quad representation. .Sp .Vb 2 \& input: 128 bit RDATA string \& returns: x:x:x:x:x:x:d.d.d.d .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = inet_any2n($dotquad or \f(CW$ipv6_text\fR); .Sp This function converts a text IPv4 or IPv6 address in text format in any standard notation into a 128 bit IPv6 string address. It prefixes any dot-quad address (if found) with '::' and passes it to \fBipv6_aton\fR. .Sp .Vb 2 \& input: dot\-quad or rfc1844 address \& returns: 128 bit IPv6 string .Ve .IP "\(bu" 4 \&\f(CW$rv\fR = hasbits($bits128); .Sp This function returns true if there are one's present in the 128 bit string and false if all the bits are zero. .Sp .Vb 3 \& i.e. if (hasbits($bits128)) { \& &do_something; \& } \& \& or if (hasbits($bits128 & $mask128) { \& &do_something; \& } .Ve .Sp This allows the implementation of logical functions of the form of: .Sp .Vb 2 \& if ($bits128 & $mask128) { \& ... \& \& input: 128 bit IPv6 string \& returns: true if any bits are present .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = inet_4map6($netaddr or \f(CW$ipv6naddr\fR .Sp This function returns an ipV6 network address with the first 80 bits set to zero and the next 16 bits set to one, while the last 32 bits are filled with the ipV4 address. .Sp .Vb 3 \& input: ipV4 netaddr \& or ipV6 netaddr \& returns: ipV6 netaddr \& \& returns: undef on error .Ve .Sp An ipV6 network address must be in one of the two compatible ipV4 mapped address spaces. i.e. .Sp .Vb 1 \& ::ffff::d.d.d.d or ::d.d.d.d .Ve .IP "\(bu" 4 \&\f(CW$rv\fR = isIPv4($bits128); .Sp This function returns true if there are no on bits present in the IPv6 portion of the 128 bit string and false otherwise. .Sp .Vb 1 \& i.e. the address must be of the form \- ::d.d.d.d .Ve .Sp Note: this is an old and deprecated ipV4 compatible ipV6 address .IP "\(bu" 4 \&\f(CW$rv\fR = isNewIPv4($bits128); .Sp This function return true if the IPv6 128 bit string is of the form .Sp .Vb 1 \& ::ffff::d.d.d.d .Ve .IP "\(bu" 4 \&\f(CW$rv\fR = isAnyIPv4($bits128); .Sp This function return true if the IPv6 bit string is of the form .Sp .Vb 1 \& ::d.d.d.d or ::ffff::d.d.d.d .Ve .IP "\(bu" 4 \&\f(CW$dotquad\fR or \f(CW$hex_text\fR = inet_n2dx($ipv6naddr); .Sp This function \fBdoes the right thing\fR and returns the text for either a dot-quad IPv4 or a hex notation IPv6 address. .Sp .Vb 3 \& input: 128 bit IPv6 string \& returns: ddd.ddd.ddd.ddd \& or x:x:x:x:x:x:x:x .Ve .IP "\(bu" 4 \&\f(CW$dotquad\fR or \f(CW$dec_text\fR = inet_n2ad($ipv6naddr); .Sp This function \fBdoes the right thing\fR and returns the text for either a dot-quad IPv4 or a hex::decimal notation IPv6 address. .Sp .Vb 3 \& input: 128 bit IPv6 string \& returns: ddd.ddd.ddd.ddd \& or x:x:x:x:x:x:ddd.ddd.ddd.dd .Ve .IP "\(bu" 4 \&\f(CW$netaddr\fR = inet_pton($AF_family,$hex_text); .Sp This function takes an \s-1IP\s0 address in IPv4 or IPv6 text format and converts it into binary format. The type of \s-1IP\s0 address conversion is controlled by the \s-1FAMILY\s0 argument. .IP "\(bu" 4 \&\f(CW$hex_text\fR = inet_ntop($AF_family,$netaddr); .Sp This function takes and \s-1IP\s0 address in binary format and converts it into text format. The type of \s-1IP\s0 address conversion is controlled by the \s-1FAMILY\s0 argument. .Sp \&\s-1NOTE:\s0 inet_ntop \s-1ALWAYS\s0 returns lowercase characters. .IP "\(bu" 4 \&\f(CW$hex_text\fR = packzeros($hex_text); .Sp This function optimizes and rfc 1884 IPv6 hex address to reduce the number of long strings of zero bits as specified in rfc 1884, 2.2 (2) by substituting \&\fB::\fR for the first occurence of the longest string of zeros in the address. .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = ipv4to6($netaddr); .Sp Convert an ipv4 network address into an IPv6 network address. .Sp .Vb 2 \& input: 32 bit network address \& returns: 128 bit network address .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = mask4to6($netaddr); .Sp Convert an ipv4 network address/mask into an ipv6 network mask. .Sp .Vb 2 \& input: 32 bit network/mask address \& returns: 128 bit network/mask address .Ve .Sp \&\s-1NOTE:\s0 returns the high 96 bits as one's .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = ipanyto6($netaddr); .Sp Similar to ipv4to6 except that this function takes either an IPv4 or IPv6 input and always returns a 128 bit IPv6 network address. .Sp .Vb 2 \& input: 32 or 128 bit network address \& returns: 128 bit network address .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = maskanyto6($netaddr); .Sp Similar to mask4to6 except that this function takes either an IPv4 or IPv6 netmask and always returns a 128 bit IPv6 netmask. .Sp .Vb 2 \& input: 32 or 128 bit network mask \& returns: 128 bit network mask .Ve .IP "\(bu" 4 \&\f(CW$netaddr\fR = ipv6to4($pv6naddr); .Sp Truncate the upper 96 bits of a 128 bit address and return the lower 32 bits. Returns an IPv4 address as returned by inet_aton. .Sp .Vb 2 \& input: 128 bit network address \& returns: 32 bit inet_aton network address .Ve .IP "\(bu" 4 \&\f(CW$bitsXn\fR = shiftleft($bits128,$n); .Sp .Vb 3 \& input: 128 bit string variable, \& number of shifts [optional] \& returns: bits X n shifts \& \& NOTE: a single shift is performed \& if $n is not specified .Ve .IP "\(bu" 4 addconst($ipv6naddr,$signed_32con); .Sp Add a signed constant to a 128 bit string variable. .Sp .Vb 4 \& input: 128 bit IPv6 string, \& signed 32 bit integer \& returns: scalar carry \& array (carry, result) .Ve .IP "\(bu" 4 add128($ipv6naddr1,$ipv6naddr2); .Sp Add two 128 bit string variables. .Sp .Vb 4 \& input: 128 bit string var1, \& 128 bit string var2 \& returns: scalar carry \& array (carry, result) .Ve .IP "\(bu" 4 sub128($ipv6naddr1,$ipv6naddr2); .Sp Subtract two 128 bit string variables. .Sp .Vb 4 \& input: 128 bit string var1, \& 128 bit string var2 \& returns: scalar carry \& array (carry, result) .Ve .Sp Note: The carry from this operation is the result of adding the one's complement of \s-1ARG2 +1\s0 to the \s-1ARG1.\s0 It is logically \&\fB\s-1NOT\s0 borrow\fR. .Sp .Vb 2 \& i.e. if ARG1 >= ARG2 then carry = 1 \& or if ARG1 < ARG2 then carry = 0 .Ve .IP "\(bu" 4 ($spurious,$cidr) = notcontiguous($mask128); .Sp This function counts the bit positions remaining in the mask when the rightmost '0's are removed. .Sp .Vb 6 \& input: 128 bit netmask \& returns true if there are spurious \& zero bits remaining in the \& mask, false if the mask is \& contiguous one\*(Aqs, \& 128 bit cidr number .Ve .IP "\(bu" 4 \&\f(CW$bcdtext\fR = bin2bcd($bits128); .Sp Convert a 128 bit binary string into binary coded decimal text digits. .Sp .Vb 2 \& input: 128 bit string variable \& returns: string of bcd text digits .Ve .IP "\(bu" 4 \&\f(CW$bits128\fR = bcd2bin($bcdtxt); .Sp Convert a bcd text string to 128 bit string variable .Sp .Vb 2 \& input: string of bcd text digits \& returns: 128 bit string variable .Ve .IP "\(bu" 4 \&\f(CW$modetext\fR = mode; .Sp Returns the operating mode of this module. .Sp .Vb 3 \& input: none \& returns: "Pure Perl" \& or "CC XS" .Ve .IP "\(bu" 4 ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(\s-1NAME\s0); .Sp Replacement for Perl's gethostbyname if Socket6 is available .Sp In \s-1ARRAY\s0 context, returns a list of five elements, the hostname or \s-1NAME,\s0 a space separated list of C_NAMES, \s-1AF\s0 family, length of the address structure, and an array of one or more netaddr's .Sp In \s-1SCALAR\s0 context, returns the first netaddr. .Sp This function \s-1ALWAYS\s0 returns an IPv6 address, even on IPv4 only systems. IPv4 addresses are mapped into IPv6 space in the form: .Sp .Vb 1 \& ::FFFF:FFFF:d.d.d.d .Ve .Sp This is \s-1NOT\s0 the expected result from Perl's gethostbyname2. It is instead equivalent to: .Sp .Vb 2 \& On an IPv4 only system: \& $ipv6naddr = ipv4to6 scalar ( gethostbyname( name )); \& \& On a system with Socket6 and a working gethostbyname2: \& $ipv6naddr = gethostbyname2( name, AF_INET6 ); \& and if that fails, the IPv4 conversion above. .Ve .Sp For a gethostbyname2 emulator that behave like Socket6, see: Net::DNS::Dig .IP "\(bu" 4 \&\f(CW$trueif\fR = \fBhavegethostbyname2()\fR; .Sp This function returns \s-1TRUE\s0 if Socket6 has a functioning \fBgethostbyname2\fR, otherwise it returns \s-1FALSE.\s0 See the comments above about the behavior of \&\fBnaip_gethostbyname\fR. .IP "\(bu" 4 \&\fBNetAddr::IP::Util::lower()\fR; .Sp Return IPv6 strings in lowercase. .IP "\(bu" 4 \&\fBNetAddr::IP::Util::upper()\fR; .Sp Return IPv6 strings in uppercase. This is the default. .SH "EXAMPLES" .IX Header "EXAMPLES" .Vb 4 \& # convert any textual IP address into a 128 bit vector \& # \& sub text2vec { \& my($anyIP,$anyMask) = @_; \& \& # not IPv4 bit mask \& my $notiv4 = ipv6_aton(\*(AqFFFF:FFFF:FFFF:FFFF:FFFF:FFFF::\*(Aq); \& \& my $vecip = inet_any2n($anyIP); \& my $mask = inet_any2n($anyMask); \& \& # extend mask bits for IPv4 \& my $bits = 128; # default \& unless (hasbits($mask & $notiv4)) { \& $mask |= $notiv4; \& $bits = 32; \& } \& return ($vecip, $mask, $bits); \& } \& \& ... alternate implementation, a little faster \& \& sub text2vec { \& my($anyIP,$anyMask) = @_; \& \& # not IPv4 bit mask \& my $notiv4 = ipv6_aton(\*(AqFFFF:FFFF:FFFF:FFFF:FFFF:FFFF::\*(Aq); \& \& my $vecip = inet_any2n($anyIP); \& my $mask = inet_any2n($anyMask); \& \& # extend mask bits for IPv4 \& my $bits = 128; # default \& if (isIPv4($mask)) { \& $mask |= $notiv4; \& $bits = 32; \& } \& return ($vecip, $mask, $bits); \& } \& \& \& ... elsewhere \& $nip = { \& addr => $vecip, \& mask => $mask, \& bits => $bits, \& }; \& \& # return network and broadcast addresses from IP and Mask \& # \& sub netbroad { \& my($nip) = shift; \& my $notmask = ~ $nip\->{mask}; \& my $bcast = $nip\->{addr} | $notmask; \& my $network = $nip\->{addr} & $nip\->{mask}; \& return ($network, $broadcast); \& } \& \& # check if address is within a network \& # \& sub within { \& my($nip,$net) = @_; \& my $addr = $nip\->{addr} \& my($nw,$bc) = netbroad($net); \& # arg1 >= arg2, sub128 returns true \& return (sub128($addr,$nw) && sub128($bc,$addr)) \& ? 1 : 0; \& } \& \& # truely hard way to do $ip++ \& # add a constant, wrapping at netblock boundaries \& # to subtract the constant, negate it before calling \& # \*(Aqaddwrap\*(Aq since \*(Aqaddconst\*(Aq will extend the sign bits \& # \& sub addwrap { \& my($nip,$const) = @_; \& my $addr = $nip\->{addr}; \& my $mask = $nip\->{mask}; \& my $bits = $nip\->{bits}; \& my $notmask = ~ $mask; \& my $hibits = $addr & $mask; \& $addr = addconst($addr,$const); \& my $wraponly = $addr & $notmask; \& my $newip = { \& addr => $hibits | $wraponly, \& mask => $mask, \& bits => $bits, \& }; \& # bless $newip as appropriate \& return $newip; \& } \& \& # something more useful \& # increment a /24 net to the NEXT net at the boundry \& \& my $nextnet = 256; # for /24 \& LOOP: \& while (...continuing) { \& your code.... \& ... \& my $lastip = $ip\-copy(); \& $ip++; \& if ($ip < $lastip) { # host part wrapped? \& # discard carry \& (undef, $ip\->{addr} = addconst($ip\->{addr}, $nextnet); \& } \& next LOOP; \& } .Ve .SH "EXPORT_OK" .IX Header "EXPORT_OK" .Vb 10 \& inet_aton \& inet_ntoa \& ipv6_aton \& ipv6_ntoa \& ipv6_n2x \& ipv6_n2d \& inet_any2n \& hasbits \& isIPv4 \& isNewIPv4 \& isAnyIPv4 \& inet_n2dx \& inet_n2ad \& inet_pton \& inet_ntop \& inet_4map6 \& ipv4to6 \& mask4to6 \& ipanyto6 \& maskanyto6 \& ipv6to4 \& packzeros \& shiftleft \& addconst \& add128 \& sub128 \& notcontiguous \& bin2bcd \& bcd2bin \& mode \& naip_gethostbyname \& havegethostbyname2 .Ve .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton <michael@bizsystems.com> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2003 \- 2014, Michael Robinton <michael@bizsystems.com> .PP All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: .PP .Vb 3 \& a) the GNU General Public License as published by the Free \& Software Foundation; either version 2, or (at your option) any \& later version, or \& \& b) the "Artistic License" which comes with this distribution. .Ve .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the \s-1GNU\s0 General Public License or the Artistic License for more details. .PP You should have received a copy of the Artistic License with this distribution, in the file named \*(L"Artistic\*(R". If not, I'll be glad to provide one. .PP You should also have received a copy of the \s-1GNU\s0 General Public License along with this program in the file named \*(L"Copying\*(R". If not, write to the .PP .Vb 3 \& Free Software Foundation, Inc. \& 51 Franklin Street, Fifth Floor \& Boston, MA 02110\-1301 USA. .Ve .PP or visit their web page on the internet at: .PP .Vb 1 \& http://www.gnu.org/copyleft/gpl.html. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton <michael@bizsystems.com> .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBNetAddr::IP\fR\|(3), \fBNetAddr::IP::Lite\fR\|(3), \fBNetAddr::IP::InetBase\fR\|(3) PK � �[�� % % man3/NetAddr::IP::UtilPP.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "NetAddr::IP::UtilPP 3" .TH NetAddr::IP::UtilPP 3 "2012-08-10" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" NetAddr::IP::UtilPP \-\- pure Perl functions for NetAddr::IP::Util .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use NetAddr::IP::UtilPP qw( \& hasbits \& shiftleft \& addconst \& add128 \& sub128 \& notcontiguous \& ipv4to6 \& mask4to6 \& ipanyto6 \& maskanyto6 \& ipv6to4 \& bin2bcd \& bcd2bin \& ); \& \& use NetAddr::IP::UtilPP qw(:all) \& \& $rv = hasbits($bits128); \& $bitsX2 = shiftleft($bits128,$n); \& $carry = addconst($ipv6naddr,$signed_32con); \& ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con); \& $carry = add128($ipv6naddr1,$ipv6naddr2); \& ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2); \& $carry = sub128($ipv6naddr1,$ipv6naddr2); \& ($spurious,$cidr) = notcontiguous($mask128); \& ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2); \& $ipv6naddr = ipv4to6($netaddr); \& $ipv6naddr = mask4to6($netaddr); \& $ipv6naddr = ipanyto6($netaddr); \& $ipv6naddr = maskanyto6($netaddr); \& $netaddr = ipv6to4($pv6naddr); \& $bcdtext = bin2bcd($bits128); \& $bits128 = bcd2bin($bcdtxt); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBNetAddr::IP::UtilPP\fR provides pure Perl functions for \fBNetAddr::IP::Util\fR .IP "\(bu" 4 \&\f(CW$rv\fR = hasbits($bits128); .Sp This function returns true if there are one's present in the 128 bit string and false if all the bits are zero. .Sp .Vb 3 \& i.e. if (hasbits($bits128)) { \& &do_something; \& } \& \& or if (hasbits($bits128 & $mask128) { \& &do_something; \& } .Ve .Sp This allows the implementation of logical functions of the form of: .Sp .Vb 2 \& if ($bits128 & $mask128) { \& ... \& \& input: 128 bit IPv6 string \& returns: true if any bits are present .Ve .IP "\(bu" 4 \&\f(CW$bitsXn\fR = shiftleft($bits128,$n); .Sp .Vb 3 \& input: 128 bit string variable, \& number of shifts [optional] \& returns: bits X n shifts \& \& NOTE: input bits are returned \& if $n is not specified .Ve .IP "\(bu" 4 addconst($ipv6naddr,$signed_32con); .Sp Add a signed constant to a 128 bit string variable. .Sp .Vb 4 \& input: 128 bit IPv6 string, \& signed 32 bit integer \& returns: scalar carry \& array (carry, result) .Ve .IP "\(bu" 4 add128($ipv6naddr1,$ipv6naddr2); .Sp Add two 128 bit string variables. .Sp .Vb 4 \& input: 128 bit string var1, \& 128 bit string var2 \& returns: scalar carry \& array (carry, result) .Ve .IP "\(bu" 4 sub128($ipv6naddr1,$ipv6naddr2); .Sp Subtract two 128 bit string variables. .Sp .Vb 4 \& input: 128 bit string var1, \& 128 bit string var2 \& returns: scalar carry \& array (carry, result) .Ve .Sp Note: The carry from this operation is the result of adding the one's complement of \s-1ARG2 +1\s0 to the \s-1ARG1.\s0 It is logically \&\fB\s-1NOT\s0 borrow\fR. .Sp .Vb 2 \& i.e. if ARG1 >= ARG2 then carry = 1 \& or if ARG1 < ARG2 then carry = 0 .Ve .IP "\(bu" 4 ($spurious,$cidr) = notcontiguous($mask128); .Sp This function counts the bit positions remaining in the mask when the rightmost '0's are removed. .Sp .Vb 6 \& input: 128 bit netmask \& returns true if there are spurious \& zero bits remaining in the \& mask, false if the mask is \& contiguous one\*(Aqs, \& 128 bit cidr .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = ipv4to6($netaddr); .Sp Convert an ipv4 network address into an ipv6 network address. .Sp .Vb 2 \& input: 32 bit network address \& returns: 128 bit network address .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = mask4to6($netaddr); .Sp Convert an ipv4 netowrk address into an ipv6 network mask. .Sp .Vb 2 \& input: 32 bit network/mask address \& returns: 128 bit network/mask address .Ve .Sp \&\s-1NOTE:\s0 returns the high 96 bits as one's .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = ipanyto6($netaddr); .Sp Similar to ipv4to6 except that this function takes either an IPv4 or IPv6 input and always returns a 128 bit IPv6 network address. .Sp .Vb 2 \& input: 32 or 128 bit network address \& returns: 128 bit network address .Ve .IP "\(bu" 4 \&\f(CW$ipv6naddr\fR = maskanyto6($netaddr); .Sp Similar to mask4to6 except that this function takes either an IPv4 or IPv6 netmask and always returns a 128 bit IPv6 netmask. .Sp .Vb 2 \& input: 32 or 128 bit network mask \& returns: 128 bit network mask .Ve .IP "\(bu" 4 \&\f(CW$netaddr\fR = ipv6to4($pv6naddr); .Sp Truncate the upper 96 bits of a 128 bit address and return the lower 32 bits. Returns an IPv4 address as returned by inet_aton. .Sp .Vb 2 \& input: 128 bit network address \& returns: 32 bit inet_aton network address .Ve .IP "\(bu" 4 \&\f(CW$bcdtext\fR = bin2bcd($bits128); .Sp Convert a 128 bit binary string into binary coded decimal text digits. .Sp .Vb 2 \& input: 128 bit string variable \& returns: string of bcd text digits .Ve .IP "\(bu" 4 \&\f(CW$bits128\fR = bcd2bin($bcdtxt); .Sp Convert a bcd text string to 128 bit string variable .Sp .Vb 2 \& input: string of bcd text digits \& returns: 128 bit string variable .Ve .SH "EXPORT_OK" .IX Header "EXPORT_OK" .Vb 10 \& hasbits \& shiftleft \& addconst \& add128 \& sub128 \& notcontiguous \& ipv4to6 \& mask4to6 \& ipanyto6 \& maskanyto6 \& ipv6to4 \& bin2bcd \& bcd2bin \& comp128 \& bin2bcdn \& bcdn2txt \& bcdn2bin \& simple_pack \& threads .Ve .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton <michael@bizsystems.com> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2003 \- 2012, Michael Robinton <michael@bizsystems.com> .PP All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: .PP .Vb 3 \& a) the GNU General Public License as published by the Free \& Software Foundation; either version 2, or (at your option) any \& later version, or \& \& b) the "Artistic License" which comes with this distribution. .Ve .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the \s-1GNU\s0 General Public License or the Artistic License for more details. .PP You should have received a copy of the Artistic License with this distribution, in the file named \*(L"Artistic\*(R". If not, I'll be glad to provide one. .PP You should also have received a copy of the \s-1GNU\s0 General Public License along with this program in the file named \*(L"Copying\*(R". If not, write to the .PP .Vb 3 \& Free Software Foundation, Inc., \& 51 Franklin Street, Fifth Floor \& Boston, MA 02110\-1301 USA .Ve .PP or visit their web page on the internet at: .PP .Vb 1 \& http://www.gnu.org/copyleft/gpl.html. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton <michael@bizsystems.com> PK � �[� �厑 �� man3/NetAddr::IP.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "IP 3" .TH IP 3 "2016-03-26" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" NetAddr::IP \- Manages IPv4 and IPv6 addresses and subnets .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use NetAddr::IP qw( \& Compact \& Coalesce \& Zeros \& Ones \& V4mask \& V4net \& netlimit \& :aton DEPRECATED \& :lower \& :upper \& :old_storable \& :old_nth \& :rfc3021 \& :nofqdn \& ); \& \& NOTE: NetAddr::IP::Util has a full complement of network address \& utilities to convert back and forth between binary and text. \& \& inet_aton, inet_ntoa, ipv6_aton, ipv6_ntoa \& ipv6_n2x, ipv6_n2d inet_any2d, inet_n2dx, \& inet_n2ad, inetanyto6, ipv6to4 .Ve .PP See NetAddr::IP::Util .PP .Vb 7 \& my $ip = new NetAddr::IP \*(Aq127.0.0.1\*(Aq; \& or if you prefer \& my $ip = NetAddr::IP\->new(\*(Aq127.0.0.1); \& or from a packed IPv4 address \& my $ip = new_from_aton NetAddr::IP (inet_aton(\*(Aq127.0.0.1\*(Aq)); \& or from an octal filtered IPv4 address \& my $ip = new_no NetAddr::IP \*(Aq127.012.0.0\*(Aq; \& \& print "The address is ", $ip\->addr, " with mask ", $ip\->mask, "\en" ; \& \& if ($ip\->within(new NetAddr::IP "127.0.0.0", "255.0.0.0")) { \& print "Is a loopback address\en"; \& } \& \& # This prints 127.0.0.1/32 \& print "You can also say $ip...\en"; .Ve .PP * The following four functions return ipV6 representations of: .PP .Vb 4 \& :: = Zeros(); \& FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones(); \& FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask(); \& ::FFFF:FFFF = V4net(); \& \& Will also return an ipV4 or ipV6 representation of a \& resolvable Fully Qualified Domanin Name (FQDN). .Ve .PP ###### \s-1DEPRECATED,\s0 will be remove in version 5 ############ .PP .Vb 2 \& * To accept addresses in the format as returned by \& inet_aton, invoke the module as: \& \& use NetAddr::IP qw(:aton); .Ve .PP ###### \s-1USE\s0 new_from_aton instead ########################## .PP * To enable usage of legacy data files containing NetAddr::IP objects stored using the Storable module. .PP .Vb 1 \& use NetAddr::IP qw(:old_storable); .Ve .PP * To compact many smaller subnets (see: \f(CW\*(C`$me\->compact($addr1,$addr2,...)\*(C'\fR .PP .Vb 1 \& @compacted_object_list = Compact(@object_list) .Ve .PP * Return a reference to list of \f(CW\*(C`NetAddr::IP\*(C'\fR subnets of \&\f(CW$masklen\fR mask length, when \f(CW$number\fR or more addresses from \&\f(CW@list_of_subnets\fR are found to be contained in said subnet. .PP .Vb 1 \& $arrayref = Coalesce($masklen, $number, @list_of_subnets) .Ve .PP * By default \fBNetAddr::IP\fR functions and methods return string IPv6 addresses in uppercase. To change that to lowercase: .PP \&\s-1NOTE:\s0 the \s-1AUGUST 2010 RFC5952\s0 states: .PP .Vb 1 \& 4.3. Lowercase \& \& The characters "a", "b", "c", "d", "e", and "f" in an IPv6 \& address MUST be represented in lowercase. .Ve .PP It is recommended that all \s-1NEW\s0 applications using NetAddr::IP be invoked as shown on the next line. .PP .Vb 1 \& use NetAddr::IP qw(:lower); .Ve .PP * To ensure the current IPv6 string case behavior even if the default changes: .PP .Vb 1 \& use NetAddr::IP qw(:upper); .Ve .PP * To set a limit on the size of \fBnets\fR processed or returned by NetAddr::IP. .PP Set the maximum number of nets beyond which NetAddr::IP will return an error as a power of 2 (default 16 or 65536 nets). Each 2**16 consumes approximately 4 megs of memory. A 2**20 consumes 64 megs of memory, A 2**24 consumes 1 gigabyte of memory. .PP .Vb 2 \& use NetAddr::IP qw(netlimit); \& netlimit 20; .Ve .PP The maximum \fBnetlimit\fR allowed is 2**24. Attempts to set limits below the default of 16 or above the maximum of 24 are ignored. .PP Returns true on success, otherwise \f(CW\*(C`undef\*(C'\fR. .SH "INSTALLATION" .IX Header "INSTALLATION" Un-tar the distribution in an appropriate directory and type: .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP \&\fBNetAddr::IP\fR depends on \fBNetAddr::IP::Util\fR which installs by default with its primary functions compiled using Perl's \s-1XS\s0 extensions to build a C library. If you do not have a C complier available or would like the slower Pure Perl version for some other reason, then type: .PP .Vb 4 \& perl Makefile.PL \-noxs \& make \& make test \& make install .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides an object-oriented abstraction on top of \s-1IP\s0 addresses or \s-1IP\s0 subnets that allows for easy manipulations. Version 4.xx of NetAddr::IP will work with older versions of Perl and is compatible with Math::BigInt. .PP The internal representation of all \s-1IP\s0 objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects may be freely mixed. .SS "Overloaded Operators" .IX Subsection "Overloaded Operators" Many operators have been overloaded, as described below: .ie n .IP "\fBAssignment (\f(CB""=""\fB)\fR" 4 .el .IP "\fBAssignment (\f(CB=\fB)\fR" 4 .IX Item "Assignment (=)" Has been optimized to copy one NetAddr::IP object to another very quickly. .ie n .IP "\fB\f(CB""\->copy()""\fB\fR" 4 .el .IP "\fB\f(CB\->copy()\fB\fR" 4 .IX Item "->copy()" The \fBassignment (\f(CB\*(C`=\*(C'\fB)\fR operation is only put in to operation when the copied object is further mutated by another overloaded operation. See overload \fB\s-1SPECIAL SYMBOLS FOR\s0 \*(L"use overload\*(R"\fR for details. .Sp \&\fB\f(CB\*(C`\->copy()\*(C'\fB\fR actually creates a new object when called. .IP "\fBStringification\fR" 4 .IX Item "Stringification" An object can be used just as a string. For instance, the following code .Sp .Vb 2 \& my $ip = new NetAddr::IP \*(Aq192.168.1.123\*(Aq; \& print "$ip\en"; .Ve .Sp Will print the string 192.168.1.123/32. .IP "\fBEquality\fR" 4 .IX Item "Equality" You can test for equality with either \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`==\*(C'\fR. \f(CW\*(C`eq\*(C'\fR allows comparison with arbitrary strings as well as NetAddr::IP objects. The following example: .Sp .Vb 2 \& if (NetAddr::IP\->new(\*(Aq127.0.0.1\*(Aq,\*(Aq255.0.0.0\*(Aq) eq \*(Aq127.0.0.1/8\*(Aq) \& { print "Yes\en"; } .Ve .Sp will print out \*(L"Yes\*(R". .Sp Comparison with \f(CW\*(C`==\*(C'\fR requires both operands to be NetAddr::IP objects. .Sp In both cases, a true value is returned if the \s-1CIDR\s0 representation of the operands is equal. .ie n .IP "\fBComparison via >, <, >=, <=, <=> and \f(CB""cmp""\fB\fR" 4 .el .IP "\fBComparison via >, <, >=, <=, <=> and \f(CBcmp\fB\fR" 4 .IX Item "Comparison via >, <, >=, <=, <=> and cmp" Internally, all network objects are represented in 128 bit format. The numeric representation of the network is compared through the corresponding operation. Comparisons are tried first on the address portion of the object and if that is equal then the \s-1NUMERIC\s0 cidr portion of the masks are compared. This leads to the counterintuitive result that .Sp .Vb 1 \& /24 > /16 .Ve .Sp Comparison should not be done on netaddr objects with different \s-1CIDR\s0 as this may produce indeterminate \- unexpected results, rather the determination of which netblock is larger or smaller should be done by comparing .Sp .Vb 1 \& $ip1\->masklen <=> $ip2\->masklen .Ve .ie n .IP "\fBAddition of a constant (\f(CB""+""\fB)\fR" 4 .el .IP "\fBAddition of a constant (\f(CB+\fB)\fR" 4 .IX Item "Addition of a constant (+)" Add a 32 bit signed constant to the address part of a NetAddr object. This operation changes the address part to point so many hosts above the current objects start address. For instance, this code: .Sp .Vb 1 \& print NetAddr::IP\->new(\*(Aq127.0.0.1/8\*(Aq) + 5; .Ve .Sp will output 127.0.0.6/8. The address will wrap around at the broadcast back to the network address. This code: .Sp .Vb 1 \& print NetAddr::IP\->new(\*(Aq10.0.0.1/24\*(Aq) + 255; \& \& outputs 10.0.0.0/24. .Ve .Sp Returns the the unchanged object when the constant is missing or out of range. .Sp .Vb 1 \& 2147483647 <= constant >= \-2147483648 .Ve .ie n .IP "\fBSubtraction of a constant (\f(CB""\-""\fB)\fR" 4 .el .IP "\fBSubtraction of a constant (\f(CB\-\fB)\fR" 4 .IX Item "Subtraction of a constant (-)" The complement of the addition of a constant. .ie n .IP "\fBDifference (\f(CB""\-""\fB)\fR" 4 .el .IP "\fBDifference (\f(CB\-\fB)\fR" 4 .IX Item "Difference (-)" Returns the difference between the address parts of two NetAddr::IP objects address parts as a 32 bit signed number. .Sp Returns \fBundef\fR if the difference is out of range. .Sp (See range restrictions on Addition above) .IP "\fBAuto-increment\fR" 4 .IX Item "Auto-increment" Auto-incrementing a NetAddr::IP object causes the address part to be adjusted to the next host address within the subnet. It will wrap at the broadcast address and start again from the network address. .IP "\fBAuto-decrement\fR" 4 .IX Item "Auto-decrement" Auto-decrementing a NetAddr::IP object performs exactly the opposite of auto-incrementing it, as you would expect. .SS "Serializing and Deserializing" .IX Subsection "Serializing and Deserializing" This module defines hooks to collaborate with Storable for serializing \f(CW\*(C`NetAddr::IP\*(C'\fR objects, through compact and human readable strings. You can revert to the old format by invoking this module as .PP .Vb 1 \& use NetAddr::IP \*(Aq:old_storable\*(Aq; .Ve .PP You must do this if you have legacy data files containing NetAddr::IP objects stored using the Storable module. .SS "Methods" .IX Subsection "Methods" .ie n .IP """\->new([$addr, [ $mask|IPv6 ]])""" 4 .el .IP "\f(CW\->new([$addr, [ $mask|IPv6 ]])\fR" 4 .IX Item "->new([$addr, [ $mask|IPv6 ]])" .PD 0 .ie n .IP """\->new6([$addr, [ $mask]])""" 4 .el .IP "\f(CW\->new6([$addr, [ $mask]])\fR" 4 .IX Item "->new6([$addr, [ $mask]])" .ie n .IP """\->new_no([$addr, [ $mask]])""" 4 .el .IP "\f(CW\->new_no([$addr, [ $mask]])\fR" 4 .IX Item "->new_no([$addr, [ $mask]])" .ie n .IP """\->new_from_aton($netaddr)""" 4 .el .IP "\f(CW\->new_from_aton($netaddr)\fR" 4 .IX Item "->new_from_aton($netaddr)" .IP "new_cis and new_cis6 are \s-1DEPRECATED\s0" 4 .IX Item "new_cis and new_cis6 are DEPRECATED" .ie n .IP """\->new_cis(""$addr $mask)""" 4 .el .IP "\f(CW\->new_cis(""$addr $mask)\fR" 4 .IX Item "->new_cis(""$addr $mask)" .ie n .IP """\->new_cis6(""$addr $mask)""" 4 .el .IP "\f(CW\->new_cis6(""$addr $mask)\fR" 4 .IX Item "->new_cis6(""$addr $mask)" .PD The first two methods create a new address with the supplied address in \&\f(CW$addr\fR and an optional netmask \f(CW$mask\fR, which can be omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses respectively. .Sp The third method \f(CW\*(C`new_no\*(C'\fR is exclusively for IPv4 addresses and filters improperly formatted dot quad strings for leading 0's that would normally be interpreted as octal format by NetAddr per the specifications for inet_aton. .Sp \&\fBnew_from_aton\fR takes a packed IPv4 address and assumes a /32 mask. This function replaces the \s-1DEPRECATED\s0 :aton functionality which is fundamentally broken. .Sp The last two methods \fBnew_cis\fR and \fBnew_cis6\fR differ from \fBnew\fR and \&\fBnew6\fR only in that they except the common Cisco address notation for address/mask pairs with a \fBspace\fR as a separator instead of a slash (/) .Sp These methods are \s-1DEPRECATED\s0 because the functionality is now included in the other \*(L"new\*(R" methods .Sp .Vb 3 \& i.e. \->new_cis(\*(Aq1.2.3.0 24\*(Aq) \& or \& \->new_cis6(\*(Aq::1.2.3.0 120\*(Aq) .Ve .Sp \&\f(CW\*(C`\->new6\*(C'\fR and \&\f(CW\*(C`\->new_cis6\*(C'\fR mark the address as being in ipV6 address space even if the format would suggest otherwise. .Sp .Vb 1 \& i.e. \->new6(\*(Aq1.2.3.4\*(Aq) will result in ::102:304 \& \& addresses submitted to \->new in ipV6 notation will \& remain in that notation permanently. i.e. \& \->new(\*(Aq::1.2.3.4\*(Aq) will result in ::102:304 \& whereas new(\*(Aq1.2.3.4\*(Aq) would print out as 1.2.3.4 \& \& See "STRINGIFICATION" below. .Ve .Sp \&\f(CW$addr\fR can be almost anything that can be resolved to an \s-1IP\s0 address in all the notations I have seen over time. It can optionally contain the mask in \s-1CIDR\s0 notation. .Sp \&\fBprefix\fR notation is understood, with the limitation that the range specified by the prefix must match with a valid subnet. .Sp Addresses in the same format returned by \f(CW\*(C`inet_aton\*(C'\fR or \&\f(CW\*(C`gethostbyname\*(C'\fR can also be understood, although no mask can be specified for them. The default is to not attempt to recognize this format, as it seems to be seldom used. .Sp To accept addresses in that format, invoke the module as in .Sp .Vb 1 \& use NetAddr::IP \*(Aq:aton\*(Aq .Ve .Sp If called with no arguments, 'default' is assumed. .Sp If called with an empty string as the argument, returns 'undef' .Sp \&\f(CW$addr\fR can be any of the following and possibly more... .Sp .Vb 11 \& n.n \& n.n/mm \& n.n.n \& n.n.n/mm \& n.n.n.n \& n.n.n.n/mm 32 bit cidr notation \& n.n.n.n/m.m.m.m \& loopback, localhost, broadcast, any, default \& x.x.x.x/host \& 0xABCDEF, 0b111111000101011110, (a bcd number) \& a netaddr as returned by \*(Aqinet_aton\*(Aq .Ve .Sp Any \s-1RFC1884\s0 notation .Sp .Vb 10 \& ::n.n.n.n \& ::n.n.n.n/mmm 128 bit cidr notation \& ::n.n.n.n/::m.m.m.m \& ::x:x \& ::x:x/mmm \& x:x:x:x:x:x:x:x \& x:x:x:x:x:x:x:x/mmm \& x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation \& loopback, localhost, unspecified, any, default \& ::x:x/host \& 0xABCDEF, 0b111111000101011110 within the limits \& of perl\*(Aqs number resolution \& 123456789012 a \*(Aqbig\*(Aq bcd number (bigger than perl likes) \& and Math::BigInt .Ve .Sp A Fully Qualified Domain Name which returns an ipV4 address or an ipV6 address, embodied in that order. This previously undocumented feature may be disabled with: .Sp .Vb 1 \& use NetAddr::IP::Lite \*(Aq:nofqdn\*(Aq; .Ve .Sp If called with no arguments, 'default' is assumed. .Sp If called with an empty string as the argument, returns 'undef' .ie n .IP """\->broadcast()""" 4 .el .IP "\f(CW\->broadcast()\fR" 4 .IX Item "->broadcast()" Returns a new object referring to the broadcast address of a given subnet. The broadcast address has all ones in all the bit positions where the netmask has zero bits. This is normally used to address all the hosts in a given subnet. .ie n .IP """\->network()""" 4 .el .IP "\f(CW\->network()\fR" 4 .IX Item "->network()" Returns a new object referring to the network address of a given subnet. A network address has all zero bits where the bits of the netmask are zero. Normally this is used to refer to a subnet. .ie n .IP """\->addr()""" 4 .el .IP "\f(CW\->addr()\fR" 4 .IX Item "->addr()" Returns a scalar with the address part of the object as an IPv4 or IPv6 text string as appropriate. This is useful for printing or for passing the address part of the NetAddr::IP object to other components that expect an \s-1IP\s0 address. If the object is an ipV6 address or was created using \->new6($ip) it will be reported in ipV6 hex format otherwise it will be reported in dot quad format only if it resides in ipV4 address space. .ie n .IP """\->mask()""" 4 .el .IP "\f(CW\->mask()\fR" 4 .IX Item "->mask()" Returns a scalar with the mask as an IPv4 or IPv6 text string as described above. .ie n .IP """\->masklen()""" 4 .el .IP "\f(CW\->masklen()\fR" 4 .IX Item "->masklen()" Returns a scalar the number of one bits in the mask. .ie n .IP """\->bits()""" 4 .el .IP "\f(CW\->bits()\fR" 4 .IX Item "->bits()" Returns the width of the address in bits. Normally 32 for v4 and 128 for v6. .ie n .IP """\->version()""" 4 .el .IP "\f(CW\->version()\fR" 4 .IX Item "->version()" Returns the version of the address or subnet. Currently this can be either 4 or 6. .ie n .IP """\->cidr()""" 4 .el .IP "\f(CW\->cidr()\fR" 4 .IX Item "->cidr()" Returns a scalar with the address and mask in \s-1CIDR\s0 notation. A NetAddr::IP object \fIstringifies\fR to the result of this function. (see comments about \->\fBnew6()\fR and \->\fBaddr()\fR for output formats) .ie n .IP """\->aton()""" 4 .el .IP "\f(CW\->aton()\fR" 4 .IX Item "->aton()" Returns the address part of the NetAddr::IP object in the same format as the \f(CW\*(C`inet_aton()\*(C'\fR or \f(CW\*(C`ipv6_aton\*(C'\fR function respectively. If the object was created using \->new6($ip), the address returned will always be in ipV6 format, even for addresses in ipV4 address space. .ie n .IP """\->range()""" 4 .el .IP "\f(CW\->range()\fR" 4 .IX Item "->range()" Returns a scalar with the base address and the broadcast address separated by a dash and spaces. This is called range notation. .ie n .IP """\->prefix()""" 4 .el .IP "\f(CW\->prefix()\fR" 4 .IX Item "->prefix()" Returns a scalar with the address and mask in ipV4 prefix representation. This is useful for some programs, which expect its input to be in this format. This method will include the broadcast address in the encoding. .ie n .IP """\->nprefix()""" 4 .el .IP "\f(CW\->nprefix()\fR" 4 .IX Item "->nprefix()" Just as \f(CW\*(C`\->prefix()\*(C'\fR, but does not include the broadcast address. .ie n .IP """\->numeric()""" 4 .el .IP "\f(CW\->numeric()\fR" 4 .IX Item "->numeric()" When called in a scalar context, will return a numeric representation of the address part of the \s-1IP\s0 address. When called in an array contest, it returns a list of two elements. The first element is as described, the second element is the numeric representation of the netmask. .Sp This method is essential for serializing the representation of a subnet. .ie n .IP """\->bigint()""" 4 .el .IP "\f(CW\->bigint()\fR" 4 .IX Item "->bigint()" When called in scalar context, will return a Math::BigInt representation of the address part of the \s-1IP\s0 address. When called in an array context, it returns a list of two elements, The first element is as described, the second element is the Math::BigInt representation of the netmask. .ie n .IP """\->wildcard()""" 4 .el .IP "\f(CW\->wildcard()\fR" 4 .IX Item "->wildcard()" When called in a scalar context, returns the wildcard bits corresponding to the mask, in dotted-quad or ipV6 format as applicable. .Sp When called in an array context, returns a two-element array. The first element, is the address part. The second element, is the wildcard translation of the mask. .ie n .IP """\->short()""" 4 .el .IP "\f(CW\->short()\fR" 4 .IX Item "->short()" Returns the address part in a short or compact notation. .Sp .Vb 1 \& (ie, 127.0.0.1 becomes 127.1). .Ve .Sp Works with both, V4 and V6. .ie n .IP """\->canon()""" 4 .el .IP "\f(CW\->canon()\fR" 4 .IX Item "->canon()" Returns the address part in canonical notation as a string. For ipV4, this is dotted quad, and is the same as the return value from \&\*(L"\->\fBaddr()\fR\*(R". For ipV6 it is as per \s-1RFC5952,\s0 and is the same as the \s-1LOWER CASE\s0 value returned by \*(L"\->\fBshort()\fR\*(R". .ie n .IP """\->full()""" 4 .el .IP "\f(CW\->full()\fR" 4 .IX Item "->full()" Returns the address part in \s-1FULL\s0 notation for ipV4 and ipV6 respectively. .Sp .Vb 2 \& i.e. for ipV4 \& 0000:0000:0000:0000:0000:0000:127.0.0.1 \& \& for ipV6 \& 0000:0000:0000:0000:0000:0000:0000:0000 .Ve .Sp To force ipV4 addresses into full ipV6 format use: .ie n .IP """\->full6()""" 4 .el .IP "\f(CW\->full6()\fR" 4 .IX Item "->full6()" Returns the address part in \s-1FULL\s0 ipV6 notation .ie n .IP """\->full6m()""" 4 .el .IP "\f(CW\->full6m()\fR" 4 .IX Item "->full6m()" Returns the mask part in \s-1FULL\s0 ipV6 notation .ie n .IP """$me\->contains($other)""" 4 .el .IP "\f(CW$me\->contains($other)\fR" 4 .IX Item "$me->contains($other)" Returns true when \f(CW$me\fR completely contains \f(CW$other\fR. False is returned otherwise and \f(CW\*(C`undef\*(C'\fR is returned if \f(CW$me\fR and \f(CW$other\fR are not both \f(CW\*(C`NetAddr::IP\*(C'\fR objects. .ie n .IP """$me\->within($other)""" 4 .el .IP "\f(CW$me\->within($other)\fR" 4 .IX Item "$me->within($other)" The complement of \f(CW\*(C`\->contains()\*(C'\fR. Returns true when \f(CW$me\fR is completely contained within \f(CW$other\fR. .Sp Note that \f(CW$me\fR and \f(CW$other\fR must be \f(CW\*(C`NetAddr::IP\*(C'\fR objects. .IP "C\->\fBis_rfc1918()\fR>" 4 .IX Item "C->is_rfc1918()>" Returns true when \f(CW$me\fR is an \s-1RFC 1918\s0 address. .Sp .Vb 3 \& 10.0.0.0 \- 10.255.255.255 (10/8 prefix) \& 172.16.0.0 \- 172.31.255.255 (172.16/12 prefix) \& 192.168.0.0 \- 192.168.255.255 (192.168/16 prefix) .Ve .ie n .IP """\->is_local()""" 4 .el .IP "\f(CW\->is_local()\fR" 4 .IX Item "->is_local()" Returns true when \f(CW$me\fR is a local network address. .Sp .Vb 2 \& i.e. ipV4 127.0.0.0 \- 127.255.255.255 \& or ipV6 === ::1 .Ve .ie n .IP """\->splitref($bits,[optional $bits1,$bits2,...])""" 4 .el .IP "\f(CW\->splitref($bits,[optional $bits1,$bits2,...])\fR" 4 .IX Item "->splitref($bits,[optional $bits1,$bits2,...])" Returns a reference to a list of objects, representing subnets of \f(CW\*(C`bits\*(C'\fR mask produced by splitting the original object, which is left unchanged. Note that \f(CW$bits\fR must be longer than the original mask in order for it to be splittable. .Sp \&\s-1ERROR\s0 conditions: .Sp .Vb 3 \& \->splitref will DIE with the message \*(Aqnetlimit exceeded\*(Aq \& if the number of return objects exceeds \*(Aqnetlimit\*(Aq. \& See function \*(Aqnetlimit\*(Aq above (default 2**16 or 65536 nets). \& \& \->splitref returns undef when C<bits> or the (bits list) \& will not fit within the original object. \& \& \->splitref returns undef if a supplied ipV4, ipV6, or NetAddr \& mask in inappropriately formatted, .Ve .Sp \&\fBbits\fR may be a \s-1CIDR\s0 mask, a dot quad or ipV6 string or a NetAddr::IP object. If \f(CW\*(C`bits\*(C'\fR is missing, the object is split for into all available addresses within the ipV4 or ipV6 object ( auto-mask of \s-1CIDR 32, 128\s0 respectively ). .Sp With optional additional \f(CW\*(C`bits\*(C'\fR list, the original object is split into parts sized based on the list. \s-1NOTE:\s0 a short list will replicate the last item. If the last item is too large to for what remains of the object after splitting off the first parts of the list, a \*(L"best fits\*(R" list of remaining objects will be returned based on an increasing sort of the \s-1CIDR\s0 values of the \f(CW\*(C`bits\*(C'\fR list. .Sp .Vb 2 \& i.e. my $ip = new NetAddr::IP(\*(Aq192.168.0.0/24\*(Aq); \& my $objptr = $ip\->split(28, 29, 28, 29, 26); \& \& has split plan 28 29 28 29 26 26 26 28 \& and returns this list of objects \& \& 192.168.0.0/28 \& 192.168.0.16/29 \& 192.168.0.24/28 \& 192.168.0.40/29 \& 192.168.0.48/26 \& 192.168.0.112/26 \& 192.168.0.176/26 \& 192.168.0.240/28 .Ve .Sp \&\s-1NOTE:\s0 that /26 replicates twice beyond the original request and /28 fills the remaining return object requirement. .ie n .IP """\->rsplitref($bits,[optional $bits1,$bits2,...])""" 4 .el .IP "\f(CW\->rsplitref($bits,[optional $bits1,$bits2,...])\fR" 4 .IX Item "->rsplitref($bits,[optional $bits1,$bits2,...])" \&\f(CW\*(C`\->rsplitref\*(C'\fR is the same as \f(CW\*(C`\->splitref\*(C'\fR above except that the split plan is applied to the original object in reverse order. .Sp .Vb 2 \& i.e. my $ip = new NetAddr::IP(\*(Aq192.168.0.0/24\*(Aq); \& my @objects = $ip\->split(28, 29, 28, 29, 26); \& \& has split plan 28 26 26 26 29 28 29 28 \& and returns this list of objects \& \& 192.168.0.0/28 \& 192.168.0.16/26 \& 192.168.0.80/26 \& 192.168.0.144/26 \& 192.168.0.208/29 \& 192.168.0.216/28 \& 192.168.0.232/29 \& 192.168.0.240/28 .Ve .ie n .IP """\->split($bits,[optional $bits1,$bits2,...])""" 4 .el .IP "\f(CW\->split($bits,[optional $bits1,$bits2,...])\fR" 4 .IX Item "->split($bits,[optional $bits1,$bits2,...])" Similar to \f(CW\*(C`\->splitref\*(C'\fR above but returns the list rather than a list reference. You may not want to use this if a large number of objects is expected. .ie n .IP """\->rsplit($bits,[optional $bits1,$bits2,...])""" 4 .el .IP "\f(CW\->rsplit($bits,[optional $bits1,$bits2,...])\fR" 4 .IX Item "->rsplit($bits,[optional $bits1,$bits2,...])" Similar to \f(CW\*(C`\->rsplitref\*(C'\fR above but returns the list rather than a list reference. You may not want to use this if a large number of objects is expected. .ie n .IP """\->hostenum()""" 4 .el .IP "\f(CW\->hostenum()\fR" 4 .IX Item "->hostenum()" Returns the list of hosts within a subnet. .Sp \&\s-1ERROR\s0 conditions: .Sp .Vb 3 \& \->hostenum will DIE with the message \*(Aqnetlimit exceeded\*(Aq \& if the number of return objects exceeds \*(Aqnetlimit\*(Aq. \& See function \*(Aqnetlimit\*(Aq above (default 2**16 or 65536 nets). .Ve .ie n .IP """\->hostenumref()""" 4 .el .IP "\f(CW\->hostenumref()\fR" 4 .IX Item "->hostenumref()" Faster version of \f(CW\*(C`\->hostenum()\*(C'\fR, returning a reference to a list. .Sp \&\s-1NOTE:\s0 hostenum and hostenumref report zero (0) useable hosts in a /31 network. This is the behavior expected prior to \s-1RFC 3021.\s0 To report 2 useable hosts for use in point-to-point networks, use \fB:rfc3021\fR tag. .Sp .Vb 1 \& use NetAddr::IP qw(:rfc3021); .Ve .Sp This will cause hostenum and hostenumref to return two (2) useable hosts in a /31 network. .ie n .IP """$me\->compact($addr1, $addr2, ...)""" 4 .el .IP "\f(CW$me\->compact($addr1, $addr2, ...)\fR" 4 .IX Item "$me->compact($addr1, $addr2, ...)" .PD 0 .ie n .IP """@compacted_object_list = Compact(@object_list)""" 4 .el .IP "\f(CW@compacted_object_list = Compact(@object_list)\fR" 4 .IX Item "@compacted_object_list = Compact(@object_list)" .PD Given a list of objects (including \f(CW$me\fR), this method will compact all the addresses and subnets into the largest (ie, least specific) subnets possible that contain exactly all of the given objects. .Sp Note that in versions prior to 3.02, if fed with the same \s-1IP\s0 subnets multiple times, these subnets would be returned. From 3.02 on, a more \&\*(L"correct\*(R" approach has been adopted and only one address would be returned. .Sp Note that \f(CW$me\fR and all \f(CW$addr\fR's must be \f(CW\*(C`NetAddr::IP\*(C'\fR objects. .ie n .IP """$me\->compactref(\e@list)""" 4 .el .IP "\f(CW$me\->compactref(\e@list)\fR" 4 .IX Item "$me->compactref(@list)" .PD 0 .ie n .IP """$compacted_object_list = Compact(\e@list)""" 4 .el .IP "\f(CW$compacted_object_list = Compact(\e@list)\fR" 4 .IX Item "$compacted_object_list = Compact(@list)" .PD As usual, a faster version of \f(CW\*(C`\->compact()\*(C'\fR that returns a reference to a list. Note that this method takes a reference to a list instead. .Sp Note that \f(CW$me\fR must be a \f(CW\*(C`NetAddr::IP\*(C'\fR object. .ie n .IP """$me\->coalesce($masklen, $number, @list_of_subnets)""" 4 .el .IP "\f(CW$me\->coalesce($masklen, $number, @list_of_subnets)\fR" 4 .IX Item "$me->coalesce($masklen, $number, @list_of_subnets)" .PD 0 .ie n .IP """$arrayref = Coalesce($masklen,$number,@list_of_subnets)""" 4 .el .IP "\f(CW$arrayref = Coalesce($masklen,$number,@list_of_subnets)\fR" 4 .IX Item "$arrayref = Coalesce($masklen,$number,@list_of_subnets)" .PD Will return a reference to list of \f(CW\*(C`NetAddr::IP\*(C'\fR subnets of \&\f(CW$masklen\fR mask length, when \f(CW$number\fR or more addresses from \&\f(CW@list_of_subnets\fR are found to be contained in said subnet. .Sp Subnets from \f(CW@list_of_subnets\fR with a mask shorter than \f(CW$masklen\fR are passed \*(L"as is\*(R" to the return list. .Sp Subnets from \f(CW@list_of_subnets\fR with a mask longer than \f(CW$masklen\fR will be counted (actually, the number of \s-1IP\s0 addresses is counted) towards \f(CW$number\fR. .Sp Called as a method, the array will include \f(CW$me\fR. .Sp \&\s-1WARNING:\s0 the list of subnet must be the same type. i.e ipV4 or ipV6 .ie n .IP """\->first()""" 4 .el .IP "\f(CW\->first()\fR" 4 .IX Item "->first()" Returns a new object representing the first usable \s-1IP\s0 address within the subnet (ie, the first host address). .ie n .IP """\->last()""" 4 .el .IP "\f(CW\->last()\fR" 4 .IX Item "->last()" Returns a new object representing the last usable \s-1IP\s0 address within the subnet (ie, one less than the broadcast address). .ie n .IP """\->nth($index)""" 4 .el .IP "\f(CW\->nth($index)\fR" 4 .IX Item "->nth($index)" Returns a new object representing the \fIn\fR\-th usable \s-1IP\s0 address within the subnet (ie, the \fIn\fR\-th host address). If no address is available (for example, when the network is too small for \f(CW$index\fR hosts), \&\f(CW\*(C`undef\*(C'\fR is returned. .Sp Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite implements \&\f(CW\*(C`\->nth($index)\*(C'\fR and \f(CW\*(C`\->num()\*(C'\fR exactly as the documentation states. Previous versions behaved slightly differently and not in a consistent manner. See the \s-1README\s0 file for details. .Sp To use the old behavior for \f(CW\*(C`\->nth($index)\*(C'\fR and \f(CW\*(C`\->num()\*(C'\fR: .Sp .Vb 1 \& use NetAddr::IP::Lite qw(:old_nth); \& \& old behavior: \& NetAddr::IP\->new(\*(Aq10/32\*(Aq)\->nth(0) == undef \& NetAddr::IP\->new(\*(Aq10/32\*(Aq)\->nth(1) == undef \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(0) == undef \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(1) == 10.0.0.1/31 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(0) == undef \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(1) == 10.0.0.1/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(2) == 10.0.0.2/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(3) == 10.0.0.3/30 .Ve .Sp Note that in each case, the broadcast address is represented in the output set and that the 'zero'th index is alway undef except for a point-to-point /31 or /127 network where there are exactly two addresses in the network. .Sp .Vb 8 \& new behavior: \& NetAddr::IP\->new(\*(Aq10/32\*(Aq)\->nth(0) == 10.0.0.0/32 \& NetAddr::IP\->new(\*(Aq10.1/32\*(Aq\->nth(0) == 10.0.0.1/32 \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(0) == 10.0.0.0/31 \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(1) == 10.0.0.1/31 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(0) == 10.0.0.1/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(1) == 10.0.0.2/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(2) == undef .Ve .Sp Note that a /32 net always has 1 usable address while a /31 has exactly two usable addresses for point-to-point addressing. The first index (0) returns the address immediately following the network address except for a /31 or /127 when it return the network address. .ie n .IP """\->num()""" 4 .el .IP "\f(CW\->num()\fR" 4 .IX Item "->num()" As of version 4.42 of NetAddr::IP and version 1.27 of NetAddr::IP::Lite a /31 and /127 with return a net \fBnum\fR value of 2 instead of 0 (zero) for point-to-point networks. .Sp Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite return the number of usable \s-1IP\s0 addresses within the subnet, not counting the broadcast or network address. .Sp Previous versions worked only for ipV4 addresses, returned a maximum span of 2**32 and returned the number of \s-1IP\s0 addresses not counting the broadcast address. (one greater than the new behavior) .Sp To use the old behavior for \f(CW\*(C`\->nth($index)\*(C'\fR and \f(CW\*(C`\->num()\*(C'\fR: .Sp .Vb 1 \& use NetAddr::IP::Lite qw(:old_nth); .Ve .Sp \&\s-1WARNING:\s0 .Sp NetAddr::IP will calculate and return a numeric string for network ranges as large as 2**128. These values are \s-1TEXT\s0 strings and perl can treat them as integers for numeric calculations. .Sp Perl on 32 bit platforms only handles integer numbers up to 2**32 and on 64 bit platforms to 2**64. .Sp If you wish to manipulate numeric strings returned by NetAddr::IP that are larger than 2**32 or 2**64, respectively, you must load additional modules such as Math::BigInt, bignum or some similar package to do the integer math. .ie n .IP """\->re()""" 4 .el .IP "\f(CW\->re()\fR" 4 .IX Item "->re()" Returns a Perl regular expression that will match an \s-1IP\s0 address within the given subnet. Defaults to ipV4 notation. Will return an ipV6 regex if the address in not in ipV4 space. .ie n .IP """\->re6()""" 4 .el .IP "\f(CW\->re6()\fR" 4 .IX Item "->re6()" Returns a Perl regular expression that will match an \s-1IP\s0 address within the given subnet. Always returns an ipV6 regex. .SH "EXPORT_OK" .IX Header "EXPORT_OK" .Vb 7 \& Compact \& Coalesce \& Zeros \& Ones \& V4mask \& V4net \& netlimit .Ve .SH "NOTES / BUGS ... FEATURES" .IX Header "NOTES / BUGS ... FEATURES" NetAddr::IP only runs in Pure Perl mode on Windows boxes because I don't have the resources or know how to get the \*(L"configure\*(R" stuff working in the Windows environment. Volunteers \s-1WELCOME\s0 to port the \*(L"C\*(R" portion of this module to Windows. .SH "HISTORY" .IX Header "HISTORY" .RS 4 See the Changes file .RE .SH "AUTHORS" .IX Header "AUTHORS" Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton <michael@bizsystems.com> .SH "WARRANTY" .IX Header "WARRANTY" This software comes with the same warranty as Perl itself (ie, none), so by using it you accept any and all the liability. .SH "COPYRIGHT" .IX Header "COPYRIGHT" This software is (c) Luis E. Muñoz, 1999 \- 2007, and (c) Michael Robinton, 2006 \- 2014. .PP All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: .PP .Vb 3 \& a) the GNU General Public License as published by the Free \& Software Foundation; either version 2, or (at your option) any \& later version, or \& \& b) the "Artistic License" which comes with this distribution. .Ve .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the \s-1GNU\s0 General Public License or the Artistic License for more details. .PP You should have received a copy of the Artistic License with this distribution, in the file named \*(L"Artistic\*(R". If not, I'll be glad to provide one. .PP You should also have received a copy of the \s-1GNU\s0 General Public License along with this program in the file named \*(L"Copying\*(R". If not, write to the .PP .Vb 3 \& Free Software Foundation, Inc. \& 51 Franklin Street, Fifth Floor \& Boston, MA 02110\-1301 USA. .Ve .PP or visit their web page on the internet at: .PP .Vb 1 \& http://www.gnu.org/copyleft/gpl.html. .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 2 \& perl(1) L<NetAddr::IP::Lite>, L<NetAddr::IP::Util>, \&L<NetAddr::IP::InetBase> .Ve PK � �[]g� �d �d man3/NetAddr::IP::Lite.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Lite 3" .TH Lite 3 "2016-03-26" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" NetAddr::IP::Lite \- Manages IPv4 and IPv6 addresses and subnets .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 11 \& use NetAddr::IP::Lite qw( \& Zeros \& Ones \& V4mask \& V4net \& :aton DEPRECATED ! \& :old_nth \& :upper \& :lower \& :nofqdn \& ); \& \& my $ip = new NetAddr::IP::Lite \*(Aq127.0.0.1\*(Aq; \& or if your prefer \& my $ip = NetAddr::IP::Lite\->new(\*(Aq127.0.0.1); \& or from a packed IPv4 address \& my $ip = new_from_aton NetAddr::IP::Lite (inet_aton(\*(Aq127.0.0.1\*(Aq)); \& or from an octal filtered IPv4 address \& my $ip = new_no NetAddr::IP::Lite \*(Aq127.012.0.0\*(Aq; \& \& print "The address is ", $ip\->addr, " with mask ", $ip\->mask, "\en" ; \& \& if ($ip\->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) { \& print "Is a loopback address\en"; \& } \& \& # This prints 127.0.0.1/32 \& print "You can also say $ip...\en"; \& \& The following four functions return ipV6 representations of: \& \& :: = Zeros(); \& FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones(); \& FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask(); \& ::FFFF:FFFF = V4net(); \& \& Will also return an ipV4 or ipV6 representation of a \& resolvable Fully Qualified Domanin Name (FQDN). .Ve .SH "INSTALLATION" .IX Header "INSTALLATION" Un-tar the distribution in an appropriate directory and type: .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP \&\fBNetAddr::IP::Lite\fR depends on \fBNetAddr::IP::Util\fR which installs by default with its primary functions compiled using Perl's \s-1XS\s0 extensions to build a 'C' library. If you do not have a 'C' complier available or would like the slower Pure Perl version for some other reason, then type: .PP .Vb 4 \& perl Makefile.PL \-noxs \& make \& make test \& make install .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides an object-oriented abstraction on top of \s-1IP\s0 addresses or \s-1IP\s0 subnets, that allows for easy manipulations. Most of the operations of NetAddr::IP are supported. This module will work with older versions of Perl and is compatible with Math::BigInt. .PP * By default \fBNetAddr::IP\fR functions and methods return string IPv6 addresses in uppercase. To change that to lowercase: .PP \&\s-1NOTE:\s0 the \s-1AUGUST 2010 RFC5952\s0 states: .PP .Vb 1 \& 4.3. Lowercase \& \& The characters "a", "b", "c", "d", "e", and "f" in an IPv6 \& address MUST be represented in lowercase. .Ve .PP It is recommended that all \s-1NEW\s0 applications using NetAddr::IP::Lite be invoked as shown on the next line. .PP .Vb 1 \& use NetAddr::IP::Lite qw(:lower); .Ve .PP * To ensure the current IPv6 string case behavior even if the default changes: .PP .Vb 1 \& use NetAddr::IP::Lite qw(:upper); .Ve .PP The internal representation of all \s-1IP\s0 objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects may be freely mixed. .PP The supported operations are described below: .SS "Overloaded Operators" .IX Subsection "Overloaded Operators" .ie n .IP "\fBAssignment (\f(CB""=""\fB)\fR" 4 .el .IP "\fBAssignment (\f(CB=\fB)\fR" 4 .IX Item "Assignment (=)" Has been optimized to copy one NetAddr::IP::Lite object to another very quickly. .ie n .IP "\fB\f(CB""\->copy()""\fB\fR" 4 .el .IP "\fB\f(CB\->copy()\fB\fR" 4 .IX Item "->copy()" The \fBassignment (\f(CB\*(C`=\*(C'\fB)\fR operation is only put in to operation when the copied object is further mutated by another overloaded operation. See overload \fB\s-1SPECIAL SYMBOLS FOR\s0 \*(L"use overload\*(R"\fR for details. .Sp \&\fB\f(CB\*(C`\->copy()\*(C'\fB\fR actually creates a new object when called. .IP "\fBStringification\fR" 4 .IX Item "Stringification" An object can be used just as a string. For instance, the following code .Sp .Vb 2 \& my $ip = new NetAddr::IP::Lite \*(Aq192.168.1.123\*(Aq; \& print "$ip\en"; .Ve .Sp Will print the string 192.168.1.123/32. .Sp .Vb 2 \& my $ip = new6 NetAddr::IP::Lite \*(Aq192.168.1.123\*(Aq; \& print "$ip\en"; .Ve .Sp Will print the string 0:0:0:0:0:0:C0A8:17B/128 .IP "\fBEquality\fR" 4 .IX Item "Equality" You can test for equality with either \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR, \f(CW\*(C`==\*(C'\fR or \f(CW\*(C`!=\*(C'\fR. \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR allows the comparison with arbitrary strings as well as NetAddr::IP::Lite objects. The following example: .Sp .Vb 2 \& if (NetAddr::IP::Lite\->new(\*(Aq127.0.0.1\*(Aq,\*(Aq255.0.0.0\*(Aq) eq \*(Aq127.0.0.1/8\*(Aq) \& { print "Yes\en"; } .Ve .Sp Will print out \*(L"Yes\*(R". .Sp Comparison with \f(CW\*(C`==\*(C'\fR and \f(CW\*(C`!=\*(C'\fR requires both operands to be NetAddr::IP::Lite objects. .ie n .IP "\fBComparison via >, <, >=, <=, <=> and \f(CB""cmp""\fB\fR" 4 .el .IP "\fBComparison via >, <, >=, <=, <=> and \f(CBcmp\fB\fR" 4 .IX Item "Comparison via >, <, >=, <=, <=> and cmp" Internally, all network objects are represented in 128 bit format. The numeric representation of the network is compared through the corresponding operation. Comparisons are tried first on the address portion of the object and if that is equal then the \s-1NUMERIC\s0 cidr portion of the masks are compared. This leads to the counterintuitive result that .Sp .Vb 1 \& /24 > /16 .Ve .Sp Comparison should not be done on netaddr objects with different \s-1CIDR\s0 as this may produce indeterminate \- unexpected results, rather the determination of which netblock is larger or smaller should be done by comparing .Sp .Vb 1 \& $ip1\->masklen <=> $ip2\->masklen .Ve .ie n .IP "\fBAddition of a constant (\f(CB""+""\fB)\fR" 4 .el .IP "\fBAddition of a constant (\f(CB+\fB)\fR" 4 .IX Item "Addition of a constant (+)" Add a 32 bit signed constant to the address part of a NetAddr object. This operation changes the address part to point so many hosts above the current objects start address. For instance, this code: .Sp .Vb 1 \& print NetAddr::IP::Lite\->new(\*(Aq127.0.0.1/8\*(Aq) + 5; .Ve .Sp will output 127.0.0.6/8. The address will wrap around at the broadcast back to the network address. This code: .Sp .Vb 1 \& print NetAddr::IP::Lite\->new(\*(Aq10.0.0.1/24\*(Aq) + 255; .Ve .Sp outputs 10.0.0.0/24. .Sp Returns the the unchanged object when the constant is missing or out of range. .Sp .Vb 1 \& 2147483647 <= constant >= \-2147483648 .Ve .ie n .IP "\fBSubtraction of a constant (\f(CB""\-""\fB)\fR" 4 .el .IP "\fBSubtraction of a constant (\f(CB\-\fB)\fR" 4 .IX Item "Subtraction of a constant (-)" The complement of the addition of a constant. .ie n .IP "\fBDifference (\f(CB""\-""\fB)\fR" 4 .el .IP "\fBDifference (\f(CB\-\fB)\fR" 4 .IX Item "Difference (-)" Returns the difference between the address parts of two NetAddr::IP::Lite objects address parts as a 32 bit signed number. .Sp Returns \fBundef\fR if the difference is out of range. .IP "\fBAuto-increment\fR" 4 .IX Item "Auto-increment" Auto-incrementing a NetAddr::IP::Lite object causes the address part to be adjusted to the next host address within the subnet. It will wrap at the broadcast address and start again from the network address. .IP "\fBAuto-decrement\fR" 4 .IX Item "Auto-decrement" Auto-decrementing a NetAddr::IP::Lite object performs exactly the opposite of auto-incrementing it, as you would expect. .SS "Methods" .IX Subsection "Methods" .ie n .IP """\->new([$addr, [ $mask|IPv6 ]])""" 4 .el .IP "\f(CW\->new([$addr, [ $mask|IPv6 ]])\fR" 4 .IX Item "->new([$addr, [ $mask|IPv6 ]])" .PD 0 .ie n .IP """\->new6([$addr, [ $mask]])""" 4 .el .IP "\f(CW\->new6([$addr, [ $mask]])\fR" 4 .IX Item "->new6([$addr, [ $mask]])" .ie n .IP """\->new6FFFF([$addr, [ $mask]])""" 4 .el .IP "\f(CW\->new6FFFF([$addr, [ $mask]])\fR" 4 .IX Item "->new6FFFF([$addr, [ $mask]])" .ie n .IP """\->new_no([$addr, [ $mask]])""" 4 .el .IP "\f(CW\->new_no([$addr, [ $mask]])\fR" 4 .IX Item "->new_no([$addr, [ $mask]])" .ie n .IP """\->new_from_aton($netaddr)""" 4 .el .IP "\f(CW\->new_from_aton($netaddr)\fR" 4 .IX Item "->new_from_aton($netaddr)" .IP "new_cis and new_cis6 are \s-1DEPRECATED\s0" 4 .IX Item "new_cis and new_cis6 are DEPRECATED" .ie n .IP """\->new_cis(""$addr $mask)""" 4 .el .IP "\f(CW\->new_cis(""$addr $mask)\fR" 4 .IX Item "->new_cis(""$addr $mask)" .ie n .IP """\->new_cis6(""$addr $mask)""" 4 .el .IP "\f(CW\->new_cis6(""$addr $mask)\fR" 4 .IX Item "->new_cis6(""$addr $mask)" .PD The first three methods create a new address with the supplied address in \&\f(CW$addr\fR and an optional netmask \f(CW$mask\fR, which can be omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses respectively. .Sp new6FFFF specifically returns an IPv4 address in IPv6 format according to \s-1RFC4291\s0 .Sp .Vb 2 \& new6 ::xxxx:xxxx \& new6FFFF ::FFFF:xxxx:xxxx .Ve .Sp The third method \f(CW\*(C`new_no\*(C'\fR is exclusively for IPv4 addresses and filters improperly formatted dot quad strings for leading 0's that would normally be interpreted as octal format by NetAddr per the specifications for inet_aton. .Sp \&\fBnew_from_aton\fR takes a packed IPv4 address and assumes a /32 mask. This function replaces the \s-1DEPRECATED\s0 :aton functionality which is fundamentally broken. .Sp The last two methods \fBnew_cis\fR and \fBnew_cis6\fR differ from \fBnew\fR and \&\fBnew6\fR only in that they except the common Cisco address notation for address/mask pairs with a \fBspace\fR as a separator instead of a slash (/) .Sp These methods are \s-1DEPRECATED\s0 because the functionality is now included in the other \*(L"new\*(R" methods .Sp .Vb 3 \& i.e. \->new_cis(\*(Aq1.2.3.0 24\*(Aq) \& or \& \->new_cis6(\*(Aq::1.2.3.0 120\*(Aq) .Ve .Sp \&\f(CW\*(C`\->new6\*(C'\fR and \&\f(CW\*(C`\->new_cis6\*(C'\fR mark the address as being in ipV6 address space even if the format would suggest otherwise. .Sp .Vb 1 \& i.e. \->new6(\*(Aq1.2.3.4\*(Aq) will result in ::102:304 \& \& addresses submitted to \->new in ipV6 notation will \& remain in that notation permanently. i.e. \& \->new(\*(Aq::1.2.3.4\*(Aq) will result in ::102:304 \& whereas new(\*(Aq1.2.3.4\*(Aq) would print out as 1.2.3.4 \& \& See "STRINGIFICATION" below. .Ve .Sp \&\f(CW$addr\fR can be almost anything that can be resolved to an \s-1IP\s0 address in all the notations I have seen over time. It can optionally contain the mask in \s-1CIDR\s0 notation. If the \s-1OPTIONAL\s0 perl module Socket6 is available in the local library it will autoload and ipV6 host6 names will be resolved as well as ipV4 hostnames. .Sp \&\fBprefix\fR notation is understood, with the limitation that the range specified by the prefix must match with a valid subnet. .Sp Addresses in the same format returned by \f(CW\*(C`inet_aton\*(C'\fR or \&\f(CW\*(C`gethostbyname\*(C'\fR can also be understood, although no mask can be specified for them. The default is to not attempt to recognize this format, as it seems to be seldom used. .Sp ###### \s-1DEPRECATED,\s0 will be remove in version 5 ############ To accept addresses in that format, invoke the module as in .Sp .Vb 1 \& use NetAddr::IP::Lite \*(Aq:aton\*(Aq .Ve .Sp ###### \s-1USE\s0 new_from_aton instead ########################## .Sp If called with no arguments, 'default' is assumed. .Sp If called with an empty string as the argument, returns 'undef' .Sp \&\f(CW$addr\fR can be any of the following and possibly more... .Sp .Vb 10 \& n.n \& n.n/mm \& n.n mm \& n.n.n \& n.n.n/mm \& n.n.n mm \& n.n.n.n \& n.n.n.n/mm 32 bit cidr notation \& n.n.n.n mm \& n.n.n.n/m.m.m.m \& n.n.n.n m.m.m.m \& loopback, localhost, broadcast, any, default \& x.x.x.x/host \& 0xABCDEF, 0b111111000101011110, (or a bcd number) \& a netaddr as returned by \*(Aqinet_aton\*(Aq .Ve .Sp Any \s-1RFC1884\s0 notation .Sp .Vb 10 \& ::n.n.n.n \& ::n.n.n.n/mmm 128 bit cidr notation \& ::n.n.n.n/::m.m.m.m \& ::x:x \& ::x:x/mmm \& x:x:x:x:x:x:x:x \& x:x:x:x:x:x:x:x/mmm \& x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation \& loopback, localhost, unspecified, any, default \& ::x:x/host \& 0xABCDEF, 0b111111000101011110 within the limits \& of perl\*(Aqs number resolution \& 123456789012 a \*(Aqbig\*(Aq bcd number (bigger than perl likes) \& and Math::BigInt .Ve .Sp A Fully Qualified Domain Name which returns an ipV4 address or an ipV6 address, embodied in that order. This previously undocumented feature may be disabled with: .Sp .Vb 1 \& use NetAddr::IP::Lite \*(Aq:nofqdn\*(Aq; .Ve .Sp If called with no arguments, 'default' is assumed. .Sp If called with and empty string as the argument, 'undef' is returned; .ie n .IP """\->broadcast()""" 4 .el .IP "\f(CW\->broadcast()\fR" 4 .IX Item "->broadcast()" Returns a new object referring to the broadcast address of a given subnet. The broadcast address has all ones in all the bit positions where the netmask has zero bits. This is normally used to address all the hosts in a given subnet. .ie n .IP """\->network()""" 4 .el .IP "\f(CW\->network()\fR" 4 .IX Item "->network()" Returns a new object referring to the network address of a given subnet. A network address has all zero bits where the bits of the netmask are zero. Normally this is used to refer to a subnet. .ie n .IP """\->addr()""" 4 .el .IP "\f(CW\->addr()\fR" 4 .IX Item "->addr()" Returns a scalar with the address part of the object as an IPv4 or IPv6 text string as appropriate. This is useful for printing or for passing the address part of the NetAddr::IP::Lite object to other components that expect an \s-1IP\s0 address. If the object is an ipV6 address or was created using \->new6($ip) it will be reported in ipV6 hex format otherwise it will be reported in dot quad format only if it resides in ipV4 address space. .ie n .IP """\->mask()""" 4 .el .IP "\f(CW\->mask()\fR" 4 .IX Item "->mask()" Returns a scalar with the mask as an IPv4 or IPv6 text string as described above. .ie n .IP """\->masklen()""" 4 .el .IP "\f(CW\->masklen()\fR" 4 .IX Item "->masklen()" Returns a scalar the number of one bits in the mask. .ie n .IP """\->bits()""" 4 .el .IP "\f(CW\->bits()\fR" 4 .IX Item "->bits()" Returns the width of the address in bits. Normally 32 for v4 and 128 for v6. .ie n .IP """\->version()""" 4 .el .IP "\f(CW\->version()\fR" 4 .IX Item "->version()" Returns the version of the address or subnet. Currently this can be either 4 or 6. .ie n .IP """\->cidr()""" 4 .el .IP "\f(CW\->cidr()\fR" 4 .IX Item "->cidr()" Returns a scalar with the address and mask in \s-1CIDR\s0 notation. A NetAddr::IP::Lite object \fIstringifies\fR to the result of this function. (see comments about \->\fBnew6()\fR and \->\fBaddr()\fR for output formats) .ie n .IP """\->aton()""" 4 .el .IP "\f(CW\->aton()\fR" 4 .IX Item "->aton()" Returns the address part of the NetAddr::IP::Lite object in the same format as the \f(CW\*(C`inet_aton()\*(C'\fR or \f(CW\*(C`ipv6_aton\*(C'\fR function respectively. If the object was created using \->new6($ip), the address returned will always be in ipV6 format, even for addresses in ipV4 address space. .ie n .IP """\->range()""" 4 .el .IP "\f(CW\->range()\fR" 4 .IX Item "->range()" Returns a scalar with the base address and the broadcast address separated by a dash and spaces. This is called range notation. .ie n .IP """\->numeric()""" 4 .el .IP "\f(CW\->numeric()\fR" 4 .IX Item "->numeric()" When called in a scalar context, will return a numeric representation of the address part of the \s-1IP\s0 address. When called in an array context, it returns a list of two elements. The first element is as described, the second element is the numeric representation of the netmask. .Sp This method is essential for serializing the representation of a subnet. .ie n .IP """\->bigint()""" 4 .el .IP "\f(CW\->bigint()\fR" 4 .IX Item "->bigint()" When called in a scalar context, will return a Math::BigInt representation of the address part of the \s-1IP\s0 address. When called in an array contest, it returns a list of two elements. The first element is as described, the second element is the Math::BigInt representation of the netmask. .ie n .IP """$me\->contains($other)""" 4 .el .IP "\f(CW$me\->contains($other)\fR" 4 .IX Item "$me->contains($other)" Returns true when \f(CW$me\fR completely contains \f(CW$other\fR. False is returned otherwise and \f(CW\*(C`undef\*(C'\fR is returned if \f(CW$me\fR and \f(CW$other\fR are not both \f(CW\*(C`NetAddr::IP::Lite\*(C'\fR objects. .ie n .IP """$me\->within($other)""" 4 .el .IP "\f(CW$me\->within($other)\fR" 4 .IX Item "$me->within($other)" The complement of \f(CW\*(C`\->contains()\*(C'\fR. Returns true when \f(CW$me\fR is completely contained within \f(CW$other\fR, undef if \f(CW$me\fR and \f(CW$other\fR are not both \f(CW\*(C`NetAddr::IP::Lite\*(C'\fR objects. .IP "C\->\fBis_rfc1918()\fR>" 4 .IX Item "C->is_rfc1918()>" Returns true when \f(CW$me\fR is an \s-1RFC 1918\s0 address. .Sp .Vb 3 \& 10.0.0.0 \- 10.255.255.255 (10/8 prefix) \& 172.16.0.0 \- 172.31.255.255 (172.16/12 prefix) \& 192.168.0.0 \- 192.168.255.255 (192.168/16 prefix) .Ve .ie n .IP """\->is_local()""" 4 .el .IP "\f(CW\->is_local()\fR" 4 .IX Item "->is_local()" Returns true when \f(CW$me\fR is a local network address. .Sp .Vb 2 \& i.e. ipV4 127.0.0.0 \- 127.255.255.255 \& or ipV6 === ::1 .Ve .ie n .IP """\->first()""" 4 .el .IP "\f(CW\->first()\fR" 4 .IX Item "->first()" Returns a new object representing the first usable \s-1IP\s0 address within the subnet (ie, the first host address). .ie n .IP """\->last()""" 4 .el .IP "\f(CW\->last()\fR" 4 .IX Item "->last()" Returns a new object representing the last usable \s-1IP\s0 address within the subnet (ie, one less than the broadcast address). .ie n .IP """\->nth($index)""" 4 .el .IP "\f(CW\->nth($index)\fR" 4 .IX Item "->nth($index)" Returns a new object representing the \fIn\fR\-th usable \s-1IP\s0 address within the subnet (ie, the \fIn\fR\-th host address). If no address is available (for example, when the network is too small for \f(CW$index\fR hosts), \&\f(CW\*(C`undef\*(C'\fR is returned. .Sp Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite implements \&\f(CW\*(C`\->nth($index)\*(C'\fR and \f(CW\*(C`\->num()\*(C'\fR exactly as the documentation states. Previous versions behaved slightly differently and not in a consistent manner. .Sp To use the old behavior for \f(CW\*(C`\->nth($index)\*(C'\fR and \f(CW\*(C`\->num()\*(C'\fR: .Sp .Vb 1 \& use NetAddr::IP::Lite qw(:old_nth); \& \& old behavior: \& NetAddr::IP\->new(\*(Aq10/32\*(Aq)\->nth(0) == undef \& NetAddr::IP\->new(\*(Aq10/32\*(Aq)\->nth(1) == undef \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(0) == undef \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(1) == 10.0.0.1/31 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(0) == undef \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(1) == 10.0.0.1/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(2) == 10.0.0.2/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(3) == 10.0.0.3/30 .Ve .Sp Note that in each case, the broadcast address is represented in the output set and that the 'zero'th index is alway undef except for a point-to-point /31 or /127 network where there are exactly two addresses in the network. .Sp .Vb 8 \& new behavior: \& NetAddr::IP\->new(\*(Aq10/32\*(Aq)\->nth(0) == 10.0.0.0/32 \& NetAddr::IP\->new(\*(Aq10.1/32\*(Aq\->nth(0) == 10.0.0.1/32 \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(0) == 10.0.0.0/32 \& NetAddr::IP\->new(\*(Aq10/31\*(Aq)\->nth(1) == 10.0.0.1/32 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(0) == 10.0.0.1/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(1) == 10.0.0.2/30 \& NetAddr::IP\->new(\*(Aq10/30\*(Aq)\->nth(2) == undef .Ve .Sp Note that a /32 net always has 1 usable address while a /31 has exactly two usable addresses for point-to-point addressing. The first index (0) returns the address immediately following the network address except for a /31 or /127 when it return the network address. .ie n .IP """\->num()""" 4 .el .IP "\f(CW\->num()\fR" 4 .IX Item "->num()" As of version 4.42 of NetAddr::IP and version 1.27 of NetAddr::IP::Lite a /31 and /127 with return a net \fBnum\fR value of 2 instead of 0 (zero) for point-to-point networks. .Sp Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite return the number of usable \s-1IP\s0 addresses within the subnet, not counting the broadcast or network address. .Sp Previous versions worked only for ipV4 addresses, returned a maximum span of 2**32 and returned the number of \s-1IP\s0 addresses not counting the broadcast address. (one greater than the new behavior) .Sp To use the old behavior for \f(CW\*(C`\->nth($index)\*(C'\fR and \f(CW\*(C`\->num()\*(C'\fR: .Sp .Vb 1 \& use NetAddr::IP::Lite qw(:old_nth); .Ve .Sp \&\s-1WARNING:\s0 .Sp NetAddr::IP will calculate and return a numeric string for network ranges as large as 2**128. These values are \s-1TEXT\s0 strings and perl can treat them as integers for numeric calculations. .Sp Perl on 32 bit platforms only handles integer numbers up to 2**32 and on 64 bit platforms to 2**64. .Sp If you wish to manipulate numeric strings returned by NetAddr::IP that are larger than 2**32 or 2**64, respectively, you must load additional modules such as Math::BigInt, bignum or some similar package to do the integer math. .SH "EXPORT_OK" .IX Header "EXPORT_OK" .Vb 9 \& Zeros \& Ones \& V4mask \& V4net \& :aton DEPRECATED \& :old_nth \& :upper \& :lower \& :nofqdn .Ve .SH "AUTHORS" .IX Header "AUTHORS" Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton <michael@bizsystems.com> .SH "WARRANTY" .IX Header "WARRANTY" This software comes with the same warranty as perl itself (ie, none), so by using it you accept any and all the liability. .SH "COPYRIGHT" .IX Header "COPYRIGHT" .Vb 2 \& This software is (c) Luis E. Muñoz, 1999 \- 2005 \& and (c) Michael Robinton, 2006 \- 2014. .Ve .PP All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: .PP .Vb 3 \& a) the GNU General Public License as published by the Free \& Software Foundation; either version 2, or (at your option) any \& later version, or \& \& b) the "Artistic License" which comes with this distribution. .Ve .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the \s-1GNU\s0 General Public License or the Artistic License for more details. .PP You should have received a copy of the Artistic License with this distribution, in the file named \*(L"Artistic\*(R". If not, I'll be glad to provide one. .PP You should also have received a copy of the \s-1GNU\s0 General Public License along with this program in the file named \*(L"Copying\*(R". If not, write to the .PP .Vb 3 \& Free Software Foundation, Inc., \& 51 Franklin Street, Fifth Floor \& Boston, MA 02110\-1301 USA .Ve .PP or visit their web page on the internet at: .PP .Vb 1 \& http://www.gnu.org/copyleft/gpl.html. .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBNetAddr::IP\fR\|(3), \fBNetAddr::IP::Util\fR\|(3), \fBNetAddr::IP::InetBase\fR\|(3) PK � �[ ! arch/auto/NetAddr/IP/Lite/.existsnu �[��� PK � �[ arch/auto/NetAddr/IP/.existsnu �[��� PK � �[q~$� � ! arch/auto/NetAddr/IP/Util/Util.sonu ȯ�� ELF > p$ @ P� @ 8 @ ' & �, �, P P P @\ @l @l ( 0 X\ Xl Xl � � � � � � � � $ $ S�td � � � P�td �T �T �T � � Q�td R�td @\ @l @l � � GNU � GNU j�9��^������ ={@c��� ��1 00.Q �A� �*"�� $ ,B ` " # % & ' ( * , . / 0 5 �@D ��^< ��R %MG%�jS���8s� �o ��}��ܙ�%��5<4��i����Oɝ�ս������T�<��~�g'(�� �1Oւ�%�#UDS�|��~�q2 �-s�uh�� -UЉ � _ � g � � � � � � � � � � , � � F " s = 0p u �H � l E � � �. ! . �= > J �> M M �+ & �= \ b �+ H p l �& ' p k , * � 6 n Pp � 8p c �C Xp � P. `p 3 p Y �+ 6 � p. " U 0% � � @p � Hp p w �& � `9 E V 0> � T (p ? p __gmon_start__ _ITM_deregisterTMCloneTable _ITM_registerTMCloneTable __cxa_finalize printb128 putchar puts extendipv4 extendmask4 PL_thr_key pthread_getspecific Perl_newSVpvn Perl_sv_2mortal Perl_sv_2pv_flags Perl_stack_grow Perl_croak_xs_usage __stack_chk_fail is_ipv4to6 Perl_croak_nocontext is_mask4to6 is_ipanyto6 is_maskanyto6 fastcomp128 adder128 addercon have128 Perl_sv_newmortal Perl_sv_setiv_mg is_hasbits _isipv4 netswap_copy netswap Perl_newSViv is_add128 is_sub128 Perl_sv_2iv_flags _countbits _128x2 is_comp128 is_ipv6to4 is_shiftleft _128x10 _128x10plusbcd is_bcd2bin is_bcdn2bin is_simple_pack _bin2bcd _bcd2txt boot_NetAddr__IP__Util Perl_xs_handshake Perl_newXS_flags Perl_xs_boot_epilog libperl.so.5.32 libc.so.6 GLIBC_2.4 GLIBC_2.34 GLIBC_2.2.5 � ii � ��� � ui � @l % Hl �$ Pl Pl p �Q p R p �Q p �Q p �P (p R 0p �Q 8p �Q @p UQ Hp oQ Pp Q Xp xP `p 7Q po ( xo * �o �o " �o 5 �o / �o �o �o 0 �o �o 1 �o 6 �o % �o �o + �o & �o �o `n hn pn xn �n # �n �n �n �n �n �n �n �n �n ' �n , �n �n �n �n �n $ o - o o o o 2 (o 3 0o 8o @o 4 Ho Po Xo `o ho ! � �H��H��O H��t��H��� �5*N �%+N � �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h! ������� ��%L D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%�K D � ��%}K D � ��%uK D � ��%mK D � ��%eK D � ��%]K D � ��%UK D � ��%MK D � ��%EK D � ��%=K D � ��%5K D � ��%-K D � ��%%K D � ��% K D � ��%K D � ��% K D � ��%K D � ��%�J D H�=�K H��K H9�tH��J H��t �� � � � H�=�K H�5�K H)�H��H��?H��H�H�tH�%K H��t��f D � � � ��=}K u+UH�=K H��t H�=NG �9����d����UK ]� � � � ��w��� � � �ATA�� U1�SH��� � �1 ����� �� �1 ������� �1 ����� �1 ������� �1 ������� �1 ������ �1 ���I��s � �����H������ �; �� �0 �q����@�H����0 �^���� �H����0 �K�����H����0 �8�����H����0 �%�����H����0 ������H����0 �����H����0 ����C��� � �1 �����`����[H�=X) ]A\��� �H� �F ��F � � � �H������F������F � � � �AWI��AVAUATUSH��8H� �H dH�%( H�D$(1��;����;H�(����;H�PxH�J�H�HxLc"�m���I�H�@D�j(J��H��H)�H�����U �;E�t$H���;���I��Ic�I�PL�$� L�4�A�F % = �� I�I�~H�@H�D$H��� E��L�l$L���� �����;����H�@ H)�H���� �;����� L��H���3����;I�����L��H���^����;H�E����;H�h���L�H�(H�D$(dH+%( �� H��8[]A\A]A^A_� � �����m���f D �;�A���H�T$� L��H���\���H��H�D$� ��� � �;����H��H�� H������H���,���H�5Z' L���G�����A��t'H��F H�H� � H�5' 1�H�=:) �E���H��F H���f � � �AWI��AVAUATUSH��8H� tF dH�%( H�D$(1��;�m����;H�(�c����;H�PxH�J�H�HxLc"�M���I�H�@D�j(J��H��H)�H������ �;E�t$H������I��Ic�I�PL�$� L�4�A�F % = �� I�M�vH�@H�D$H���� H���h E��L�l$L��L���� �����;���H�@ H)�H���� �;���� L��H�������;I���|���L��H���1���H�E�;�f����;H�h�[���L�H�(H�D$(dH+%( �� H��8[]A\A]A^A_�f������r���f D �;����L��H�T$� H���4���I��H�D$H�������;���H�@ H)�H��~G�;����� L��H���=��� � �;���H��H�� H���v���H������f D �;���H��H�� H���N���H���H�5�$ L�������u���A��t'H��D H�H� � H�5�$ 1�H�=�& ����H�ID H���ff. � �� �H�H�W� @ � ���A� 1�F� F ��A�r��F� I��I���u�ø ��f. � � ��ȉN 1�� ��F�F�5��� D � �D�� E��u�w��u�O��u �W 1������f D � �AWAVAUI��ATUSH��H� TC dH�%( H�D$1��;�M����;H�(�C����;H�PxH�J�H�HxLc2�-���H�@J��H)�H������ �;E�fMc������;N�,� H�@N�$����;H�@�@#�� ����H���s���H��A�D$ % = �� I�$I�|$H�@H�$H���� �{����;Lc�����;H�@N�t(��E %�����A���r������ �� E���� �M L�eI�n�;�F����;H�h�;���L�H�(H�D$dH+%( �� H��[]A\A]A^A_�f�� ����;H�h� ���H�@H�@H�l� � ���f D �;���H�� L��H����H��H�$����f��;��L��H��H������U���H� � H��A A�� H�5�! H�={$ H�1�� �����H�5�! L����� D � ��71���u�O��u �W1������f�� �Hc�1���~ ��ʉ�H��H9�u��ff. � � �Hc�H����~��H��ȉG�H9�u��ff. � @ � �AWI��AVAUATUSH��hH� �@ dH�%( H�D$X1��;��;L� ��;H�PxH�J�H�Hx�*��I�H�@�J(Hc�H��L��H)ЉL$ H�����^ �;D�u��I��Hc��Q�;I��Ic�I�PL�4� L�<��4�H�@H�,�A�G % = �� I�M�H�@H�D$H���� �E % = �� H�E H�mH�@H�D$H���� L�l$@L��� L��L�|$0�� H��L����|$ �� �;��H�@ L)�H���� H�l$ 1�H��L��L�����;A���e�Ic�M�l$H����;I���K�L��H��� �I�D$�;�4�H�P�R"��u&H��� HcB(��x H� @H��H�JH���P����t<�;��;H�h���L�H�(H�D$XdH+%( �� H��h[]A\A]A^A_Ð� H�����;��H�@ L)�H��� �;�� H��H����;H���{�H��H���0�;I�E�e�;H�h�Z�J�T5H��i��� D �;�A�L��H�T$� H���\�I��H�D$���� � �;��H��H�T$� H���,�H��H�D$���� � L��� �;���H�@ L)�H��~eH�l$ � �A���f D �;��L��L�� H���n�I������f D �;��L��L�� H���F�I������f D �;�a�L��L�� H��� �I���y����|$ tFH� = H�H�D$A�� H�5u H�= H� � 1�����H�5g L���Y�H��< H��ff. � f�� �AWAVI��AUATUSH��XH� �< dH�%( H�D$H1��;���;L� ���;H�PxH�J�H�Hx�*��Hc�H�@H��L��H)�H������ �;D�m��I��Hc��[��;I��Ic�I�PL�,� L�4��>��;H�@H��@ % = �� � ��;H�@H�,�� �� H��H����A��A�F % = �� I�I�vH�@H�D$H��� H�l$ � H�����;��H�@ L)�H���� L�t$0D��H�t$H��L���+��;����Hc�H������;H���m�H��H���"��;I�D$�V�H�P�R"��u&H��� HcB(��x H� @H��H�JH���P����t>�;���;H�h� �L�H�(H�D$HdH+%( �] H��X[]A\A]A^A_� � L��I������;���H�@ L)�H���� �;��� L��H���!��;H����H��H���L��;I�D$���;H�h�u�J�T-H��b��� � �;�Y�L��H�T$� H���t�H��H�D$�a��� � �+�H�@H��H� D�x � ��� � �;� �L��L�� H�����I���K���f D �;���L��L�� H����I������H�� �� H�5' 1�H�=� �4�H�5 L������� �SH�����A������M �S���� ���E���щC �C�� ��E����S��� ���E����CA��t�C �u�D��[�f�� �AWAVI��AUATUSH��8H� �8 dH�%( H�D$(1��;����;L� ����;H�PxH�J�H�HxHc*���H�@H��L��H)�H�����) �;D�mM�|$���I��Ic�I�PL�,� H�,E % = �i H�E H�uH�@H�D$H���� L�t$� L���,�L�����;���;�H�@ L)�H���K L�����;A����Ic�H���^��;I����L��H�����;I�G���H�P�R"��u&H��� HcB(��x H� @H��H�JH���P����t>�;���;H�h��L�H�(H�D$(dH+%( �� H��8[]A\A]A^A_� �;�q�H�@ L)�H���� �;�Z�@��H�����;H���D�H��H�����;I�D$�-��;H�h�"�J�T-H��w��� D �;� �H��H�T$� H���$�H��H�D$���� � �;���L��L��� H����I��L�`���f. � �;��L��L�� H���f�I���-�����H�5� L�����H�� �� H�5� 1�H�=� ��� � � ��W H�G H��H����҉W�� �H9�t ���� ��H���� ��PH9�u��ff. � � �AWAVAUATUH��SH��HH� �5 dH�%( H�D$81��;����;L�8����;H�HxM��H�q�H�pxD�)��Ic�A�UH�@�T$H��I)�H�E I��D�p(E���� �;Ic�H��I)��n�L��I��HcD$I�PL�<� H�4F % = �� H�L�FH�@H�D$H���� A���� A���� �;A���� �AoL�l$ )L$ �;���H�@ H)�H���� �;���� L��H���I��;I����L��H���t�H�E�;���;H�h��L�H�(H�D$8dH+%( �� H��H[]A\A]A^A_� D �Ao L�l$ L��)D$ ���]��� @ �;H�t$�D�H�t$H�T$� H���]�I��H�D$��L�D$A����Mc�L�D$H�@J��@ % = tS�;L�D$����;H�@N�$����� L��H���x�L�D$A��E��� �AoL�l$ )T$ ��� �;��L�D$H�@J��H� D�` �� �;L�D$�t�L�D$H�@ H)�H���� �;L�D$�S�L�D$� H��I�p �o��� D A��� �� L�l$ � L��L����f D L���8�A��u� L��������;���H��H�� H����H�����f D �;��H��H�� H���~�L�D$H���B�����H�5C H�����A��t3A��t9H��2 H�H� � A�� H�5� 1�H�=Q ���H�2 H���H�2 H���D��H�5� H�=� 1��� @ � �ATI��UH��H���:��E H��A�$�EA�D$�EA�D$�E A�D$ ��H��� �H��H��L��H��1�]A\�D� @ � �ATI��UH��S�������] L��[H�E H��L��1��E ]A\��f�� ��* ��(}�F�L�Rf�A� H�BA� H�A�B )��f D H����E1ɍ>A� ��~4��Ѓ��HЀ� w&Ic�E��u�H����A A���>A� ���1�� @ � �AWf�AVI��H��AUATUSH��(���� H��E1�1��' @ E��u{E��t �_ A� ��9��� A��uMA�I���jA� A��A��A����A��A���A����E��A��u�E��u{E��t D�o A� 9�}S��A���� � A��D�L$ �L$D�D$H�t$H�<$���L$H�<$��H�t$D�D$D�L$ 9��Z���H��([]A\A]A^A_�f D D��D�D$ D�L$�L$H�t$H�<$�1�H�<$H�t$�L$D�L$D�D$ �W��� � �AWAVAUATUH��SH�� H� q/ dH�%( H�D$x1��;�j��;L�(�`��;H�PxH�r�H�pxD�"�J�Ic�M��H�@H��I)�H�E M�Nj@(I���D$E���� �;Ic�L��E�t$H��H)���I��Ic�I�QL�4� L�,�A�E % = �; I�E M�mH�pH�t$H��(�9 �|$�E H���} A���^ �;A��Mc����;H�@J��@ % = �v �q��;H�@N�$��b�� H��L����H��H�L$L�d$ H�T$0L��L���5�� L���8��;�!�H�@ H)�H���1 �;� �� L��H���z��;I�����L��H����H�E�;����;H�h���L�H�(H�D$xdH+%( �m H�Ĉ []A\A]A^A_� �;��L��H�T$� H����H�t$I����� � H�T$@L��������F �D$��u#L�d$ H�T$0�( H�|$XL����� � �;�)�H�@ H)�H��~e�;��H�t$X� H������ @ ���H�@J��H� H�H ��� � �;����H��H�� H�����H�����f D �;���H��H�� H���n��H���y���H�5= H�������|$ �� H�m, H� H�D$H�L$H�T$1�A�( H�5� H�=� �����S��H�5 H�= 1����H�O, H�H�t$H� H�D$먃|$tAH��+ H���H�5L H�= 1��|���|$�t���H��+ H� H�D$�`���H��+ H�뽐� �AWH�Ff�E1�AVL�~(I��L�VAUI��ATU1�S�� H���F( H�D$1�FE���� E��A��E!��M��D �uI��M9�tTA� A�щ�D �t� � � � �<��E������u����� �A����I��A�@M9�u���t%A�E(E��u�Hc�A�@ ��A�� E�$�l���H�|$� ����H��� []A\A]A^A_�f�� �I��I��1�E1�� � E1���uNH��H��t\A� E����A��A��@��1�@�tD��Ic�A��0��E� ��@�ƃ�A��D�t�Hc׃�0D�GH��A�H��u�Ic�A� D���ff. � @ � �AWI��AVAUATUSH��XH� �) dH�%( H�D$H1��;�����;H�(�����;H�PxH�J�H�HxLc"���I�H�@D�j(J��H��H)�H�����% �;E�t$H�����I��Ic�I�PL�$� L�4�A�F % = � I�M�vH�PH�T$E���� A��� H��� �;�-��H�@ H)�H���] L�|$L��L������;A�����Ic�L��H���u���;I������L��H�����H�E�;�����;H�h����L�H�(H�D$HdH+%( �I H��X[]A\A]A^A_ÐH���4 L�|$L��L������;���H�@ H)�H���� H�|$(L���P���f��;�Y��H�T$L��� H���t��H�T$I����� � H���� �;� ��H�@ H)�H��~{H�t$L���v���;A�����Ic�H�t$(H���� @ �;����H��H�� H�����H���W���f D �;���H��H�� H���v��H�����f D �;���H��H�� H���N��H���c���H�5� L�������r��H���� H�5@ 1�H�=y ����H���� H�5= 1�H�=[ ���Hҹ( H�5< 1�H�=f ���f � � �AUL�-��ATL�%8 USH��H� �& �;����L����L� H��H� 1�����;������;����;���E1�L��L��L�� H�5� H���0���;H� �@( �o��E1�L��L��L�� H�5� H��� ���;H� �@( �?��E1�L��L��L�� H�5� H�������;L�-7�H� �@( ���E1�L��L��L�� H�5� H������;H� �@( ����E1�L��L��L�W H�5m H���i���;L�-����H� �@( ���E1�L��L�# H���H�5� H���.���;�w��E1�L��L�� H���H�5" H������;�M��E1�L��L��L�� H�5[ H�������;H� �@( � ��L��L��E1�L�� H�5� H������;H� �@( ����L��L��E1�L�m H�5� H���~���;L�-%���H� �@( ���L��L��E1�L�� H�5� H���G���;H� �@( ���L��L��E1�L�� H�5A H������;H� �@( �V��L��L��E1�L�� H�5� H�������;L�-n��H� �@( � ��L��E1�L�� H���H�5� H������;���L��L��E1�L�u H�5� H������;H� �@( ����L��L��E1�L�E H�5� H���V���;L�-���H� �@( ���L��L��E1�L� H�5� H��� ���;H� �@( �^��L��L��E1�H�5� H��L�� �����;H� �@( �.��H����[H��]A\A]�Z�� � �H��H��� NetAddr::IP::Util:: as, bs s, cnst NetAddr::IP::Util::addconst NetAddr::IP::Util::countbits s, ... NetAddr::IP::Util::shiftleft NetAddr::IP::Util::bcdn2bin NetAddr::IP::Util::bin2bcd NetAddr::IP::Util::bin2bcdn NetAddr::IP::Util::bcdn2txt 1.53 v5.32.0 Util.c $;@ NetAddr::IP::Util::comp128 NetAddr::IP::Util::ipv6to4 $$ NetAddr::IP::Util::add128 NetAddr::IP::Util::sub128 NetAddr::IP::Util::hasbits NetAddr::IP::Util::bcd2bin NetAddr::IP::Util::ipv4to6 NetAddr::IP::Util::mask4to6 NetAddr::IP::Util::ipanyto6 NetAddr::IP::Util::maskanyto6 simple_pack Bad arg length for %s%s, length is %d, should be 32 Bad arg length for %s%s, length is %d, should be 32 or 128 Bad arg length for %s%s, length is %d, should be %d Bad arg length for %s, length is %d, should be %d Bad arg value for %s, is %d, should be 0 thru 128 Bad arg length for %s%s, length is %d, should be %d digits or less Bad usage, should have %s('packedbcd,length) Bad char in string for %s%s, character is '%c', allowed are 0-9 Bad arg length for %s, length is %d, should %d digits or less NetAddr::IP::Util::simple_pack NetAddr::IP::Util::notcontiguous ;� ��� ���< ���T $��� D��� d��� ���� ��@ ��T T��h t��| ���� ���� ���� �� D�� D��h ��� �� �� $�4 �� d�� ��� 4�� ��8 d�� t�� �� $�4 zR x � $ x��0 FJ w� ?:*3$" D ��� ( \ H��� F�G�C �aHB � ��� � ��� H � ��� F�E�B �B(�A0�A8�DpA 8A0A(B BBBH H � ���t F�E�B �B(�A0�A8�DpN 8A0A(B BBBC H ��� \ ���6 p ��� � ���* H � �� F�B�B �E(�A0�A8�DPN 8A0A(B BBBC � ��� � ���" ��! L $��� F�E�B �B(�A0�A8�D�� 8A0A(B BBBB L p ���P F�B�E �B(�A0�A8�D�� 8A0A(B BBBD � ���n E�h H � (��� F�B�E �B(�A0�A8�Dp� 8A0A(B BBBD ( ��E L < ��� F�B�B �B(�A0�D8�D�k 8A0A(B BBBF $ � x�\ F�D�G xLB ( � ��> F�D�D �QXB � ��� H � @�M F�F�H �B(�A0�A8�D`� 8A0A(B BBBG L @ D�� F�B�B �B(�A0�D8�G�� 8A0A(B BBBD D � �� F�M�M �E(�A0�C8�IP�8F0A(B BBB � ��� L � (� F�E�B �B(�A0�A8�D�O 8A0A(B BBBB 8 < ��� F�I�H �A(�D0�(C DBB % �$ Pl � � �L @l Hl ���o � � � Hn 0 � � 0 ���o ���o � ���o �o ���o Xl 0 @ P ` p � � � � � � � � ! ! ! 0! @! P! `! p! �! �! �! �! �! �! �! �! " " " 0" @" �Q R �Q �Q �P R �Q �Q UQ oQ Q xP 7Q GCC: (GNU) 11.4.1 20231218 (Red Hat 11.4.1-3) AV:4g1231 RV:running gcc 11.4.1 20231218 BV:annobin gcc 11.4.1 20231218 GW:0x3d1056a lto SP:3 SC:-1 lto CF:8 lto FL:-2 lto GA:1 PI:2 SE:0 GA$3a1 p$ p$ GA$3a1 GA$3a1 �L �L GA$3a1 p$ )% GA$3a1 �L �L GA$3a1 �L �L GA$3a1 GA$3a1 �L �L , 0% f' �8 0% f' :� 0% � �5 D� M� # �� P% P% R� �� 2 0 Z% �8 U1 �� c% c% V� �� ? = m% �8 U1 �� v% v% Z2 �� L J �% �8 U1 �� �% �% ^w �� Y W �% �8 U1 �� �% �% b� �� f d �% �8 U1 �� �% �% f �� s q �% �8 U1 �� �% �% jF �� � �% �8 U1 �� �% �% n� �� � � �% �8 U: �� �% �% P� �� � � �% �8 U0 �� & & T �� � � & �8 U0 �� & & XY �� � � %& �8 U0 �� .& .& \� �� � � 8& �8 U0 �� A& A& `� �� � � K& �8 U0 �� T& T& d( �� � � ^& �8 U0 �� g& g& hm �� � � q& �8 U0 �� z& z& l� �� �& �8 U0 �� �& �& N� �� �& �8 U1 �� �& p �� ��8 �& �8 U P � �& �l � U &� T0� 0 ( � �& �� � U �� T� [ S �� �& �U �� � ~ �� � � �� � � ʘ � � ֘ " � N L � q i �� -' � A �� � � �� C' h � � � � ' � � � � � � � &� � � 3� ��?� ��L� < � M� ( U (( U u' U �' l T} �' U �' U �' Z ? T} Q@ ( U ( _ d T} ]( 5 o( U �( d � T~ Q��R2 �( U �( i � Tv Qv R1 �( s U 0R T P #' U -' U C' U �( n G U T P �( �8 "� -� � t� N� �� �� җ ) t �v ݗ � 4 , �� ` T � � � � � � � � � (� �� M) G �� 1 / 4� c) = 9� = 9 F� R � G� R N R� o a ^� � � k� ��w� ���) U �) l � U~ T} * U * U ** Z 4* U ?* _ � T} �* 5 �* U �* d 8 T~ Q��R2 �* U �* U �* U + i � Tv Qv R1 + U 2+ i � Tv Qv R1 x+ s U hR T P �� C* �� � � J* U U* U C) U M) U c) U F+ n h U T P K+ �8 ̣ �+ �� ֣ U� � � l� �+ 6 � {� U �� T �� Q�� � �� % �� l b �� � � £ &� �+ �� 5� A = ?� W S I� m i U� � `� � � �+ � U�UT�TQ�QR0 � , * �� � U � � � ͛ 0, �c ؛ � ! � G A �� k ] � � � � � � �� m, g ! ^ �� � � #� r � (� � 3� ?� / + L� ��Y� L F f� f b s� } t� { u >- U �- U . h Tv Q| �, U �, U �, U �, c - � - U �- U �- U �- U �- d � T| Q��R2 7. s U �R T P X� �� c- �� � � j- U u- U c, U m, U �, U <. �8 K. n U} T P �� �� � P. �� � U�� � � �� p. " �� �� U �� T¢ � � ͢ � ֢ > 6 x� �. ! �1 �� x t �� � � �� � � d� �. � �Z o� � � |� � � �� � �� g [ �� � � �� � � �� � Ɲ j2 �� / � � � �� 6 4 ͝ "/ ҝ B > ߝ � � � W S � j f �� � y � � � � � � � ��)� ��5� ��B� ��~W� |0 |0 3 <� h� � � u� �� � � W� �0 �0 & h� u� �� O� � - T� ) ' K1 U V1 U _/ U |/ U �/ � d U} Q4 0 � � U Tv Q4 0 U A0 � � U} T Qv K0 U [0 Z e0 U p0 _ � T |0 U �0 � ! Uv T4 1 U 1 U +1 Z X Tv Q@ 51 U @1 _ } Tv o1 U �1 d � T Q��~R2 �1 U �1 d � Tv Q��~R2 �1 v � U �1 U �1 U 2 i 4 T| Q| R1 '2 U :2 i d T} Q} R1 O2 U b2 i � T| Q| R1 �2 s U �R T P X� b� �0 c� 4 2 �0 U �0 U / U / U "/ U �2 �8 �2 n U T P � �� �2 P �� �� A = �� ] S �� � � Ü � � Ϝ & ܜ ` ^ �� 3 � � � �� } { � � I � � � �� � � � ��� � � � ��'� ��3� ��~W� Z4 Z4 3 T� h� � � u� �� � � W� g4 g4 & h� u� �� @� � E� # ! 05 U ;5 U U3 U r3 U �3 U �3 U �3 � Q Tv Q2 �3 � n Uv Q4 �3 U %4 � Uv T��Q~ R .4 U 94 Z � Tv $ & C4 U N4 _ � Tv Z4 U �4 � U~ T4 �4 U �4 U 5 Z W T~ Q@ 5 U $5 _ | Tv W5 U l5 d � T~ Q��~R2 �5 U �5 U �5 i � T| Q| R1 �5 U �5 i T| Q| R1 6 s U �R T %P R� S� �4 � T� . , �4 U �4 U 3 U 3 U "3 U 6 n � U~ T P 6 �8 )� 6 n �g 8� = 7 B� \ V L� { u V� � � `� � � j� � � -6 v Us ]� �6 � �k h� u� / # �� v ` �� � � �� �� 0 . �� �6 � � � �� M K �� � � �� [ U �� u q ˙ � � ؙ ��� ��W� �7 �7 3 �� h� � � u� �� � � W� �7 �7 & h� � � u� � � �� � � �� � � �8 U �8 U 7 U d7 � U~ Q4 l7 � 8 U~ u7 U �7 � ] U~ �7 U �7 Z � T~ $ & �7 U �7 _ � T~ �7 U ?8 U V8 U b8 Z � Tv � l8 U w8 _ Tv �8 U �8 d E Tv Q��R2 �8 U �8 i u T Q R1 9 U 9 i � T| Q| R1 X9 s U �R T AP R� � �7 � � � 8 U 8 U �6 U �6 U �6 U '9 �8 69 n U~ T P � `9 E �� �� � & � T N � w q s� �9 � � # ~� � � �� � � �� � � �� C # �� �� � � ɞ �� �9 z Q �� , * ՞ $: x ڞ : 4 � # �" � W Q � � o �� � � � ��� ��%� � � �� �: �: � "� � + ) � 7 3 �� �; �; e "� K I � V T � b ^ B: U �: U �: U �: Z �: U �: _ � T| W; v � U} l; U �; d ! T��Q��R2 �; U �; U �; U �; � M! T| Q2 < U << U ]< U �< � �! U} Q4 �< k �! U} �< � �! U} T4 �< U �< i �! Tv Qv R1 �< U = i &" Tv Qv R1 \= s X" U �R T P X� �= s U S T eP Q| C� ; �" D� x t ; U ; U �9 U �9 U : U = �8 #= n Uv T ^P �� �= \ ��# �� � � š � � ҡ � � ޡ �= k �# Uv �= k �# Uv �= k �# Uv �= � U�UT�TQ�UR0 [� �= > ��$ g� 1 ) t� Y Q �� } y �� � � �� � � > # X$ U| Tv .> � U�UT�TQ�UR0 � 0> � �P% � � � �� � � � � ? 7 � n j *� � ~ 6� � � A� � � N� � � ʤ E> = Q� � ٤ `� �> M ��& l� - ' x� L F �� k e �� � � �� � � �� � � �� * à h f Π t p ʤ �> R n"& � � � � � � ٤ � � ʤ �> �> oo& � � � � � � ٤ � � �? �# �& U��T��Q ���8$8& �? �# U��T��Q} � @ � ��* � � � -� � � 9� E� n X Q� � � ^� k� $ w� CC �� P@ b q p' �� d b ~� �@ �' �� r l �� m )* �� � � �� ���� ��~�� ��~�� � � ͚ � � ښ � � � ��~�@ U A U ?A U NA U ^A � M( T| Q2 {A P% �A � w( U| T4 �A U �A U �A Z �A U �A _ �( T| B U ,B d �( T} Q��~R2 MB �$ ) U} Q�� �B U �B U �B U �B U �B i j) Tv Qv R1 �B U C i �) Tv Qv R1 hC s �) U PS T P Q��~X( �C s * U �S T �P �C s U �S T P � �A j* � ) % �A U �A U F@ U P@ U f@ U )C n �* Uv T ^P mC �8 �� �C ��+ �� @ : ͟ a Y ؟ � � � � � � � � �� � � � � K G &� n d 3� � � >� � � I� # T� M E ʤ .D � ��+ � | z � � � ٤ � � �D � U��T5 T� E � �P, c� � � p� � � {� � � �� � � �� � �� - # � �E �0 #� V R 0� | h <� � � H� T� G C a� s q n� � � �� �E � @ �, �� � � z� �E - � � � �� � l/ �� � � �� ���� � � �� ��~%F U �F U �F �+ �F U �F Z �F U �F _ �- T} *G �* �- U~ T 1G U WG U lG d . T~ Q��~R2 �G U �G �* <. U~ T�� �G U �G U �G i y. Tv Qv R1 �G U H i �. Tv Qv R1 H U 2H i �. Tv Qv R1 lH s / U �R T �P R� �H s =/ U �R T �P R� �H s U T T �P R( �� �F �/ �� �F U �F U �E U �E U �E U IH n �/ U T P NH �8 U� �H � ��7 a� # n� 9 5 z� Q K �� �� �� �� �P ��� � ]7 �� � g Ɩ � �0 ˖ � � ؖ � �0 ݖ � � � � �0 � ! ! �� � �0 � ! ! � � 1 � ! ! � $1 %� #! !! 2� ?1 7� -! +! D� Z1 I� 7! 5! V� ) u1 [� A! ?! h� 4 �1 m� K! I! z� ? �1 � U! S! �� J �1 �� _! ]! �� U �1 �� i! g! �� ` �1 �� s! q! k 2 × }! {! I U 0I �7 a2 T Q Q} R| X Q Y0 AI U `I �7 �2 T $Q Q} R| X Q Y0 qI U �I �7 �2 T eP Q} R| X Q Y0 �I U �I �7 ?3 T BQ Q} R| X ?Q Y0 �I U �I �7 �3 T \Q Q} R| X ?Q Y0 J U 2J �7 �3 T %P Q �2 R| X ?Q Y0 9J U \J �7 +4 T vQ Q 0, R| X @Q Y0 cJ U �J �7 u4 T �P Q} R| X @Q Y0 �J U �J �7 �4 T �P Q} R| X @Q Y0 �J U �J �7 5 T �P Q} R| X @Q Y0 �J U K �7 S5 T �Q Q} R| X Q Y0 *K U IK �7 �5 T �P Q} R| X Q Y0 ZK U yK �7 �5 T HT Q} R| X Q Y0 �K U �K �7 86 T hT Q �6 R| X @Q Y0 �K U �K �7 �6 T �Q Q} R| X @Q Y0 �K U L �7 �6 T �Q Q} R| X @Q Y0 "L U AL �7 7 T �Q Q} R| X @Q Y0 RL U qL �7 T �Q Q} R| X @Q Y0 �H U �H �7 �7 U ��Q| R �P X �P I U I U �L U �L �7 � Е �� 1� p &� p � p � p � p �� (p � 0p � 8p ٓ @p Γ Hp Ó Pp �� Xp �� `p �1 � � �0 � � � � � Ql n ?� u � !� !� % !�0 !�0 !� � & !�& � ( % 0) )q @int q ' *1 ! �3 �8 � �1 �1 �8 �7 �1 # �8 � �� �+ �q � �� Z) �� A � � � � � � �( �� �5 �!� D !� D @� � O� �( l' \) � � �8 2) e �& �} $� � L4 � 8 � 8 /- � . � - � L 3 !�0 D 8 � 11 ! K X 1 ] $ o � q � ) � K � o � � � � � �% " � h� #� pI% $� x,' '� � � � 8 � C , x 8 K , *!% � . � F � Y ) } q. f � v 8 I �� n3 Z j ! q @F "� H v � 8 �% F � 9� � � q J7 8 � $8 -1 :� �" ;� $?L � A q � B q � C� $G} -1 I� �" J� � K� $ O� -1 Q� �" R� � S q ]7 T� w& U� $a� | c !% d ^ � e� 7 g} $ Y? �0 [ ]R �' h � $lc �8 n� J# o q $t� � v �/ w q x1 p3� D 5� � <� / D ,_rt LL �/ V} �+ i 9 p? \4 yc q 8 $�$ Y ' & q J ( q � * q Z 0 q �, { � � | j 'u q ? � z B!� � % ) �� �, �� �7 � � � D � 8 � � �* � � � � � � ), b % e. �q 1 �� �* � �. �� � �� / / v # � ( � 3 P N �6 o � N � � � � � � � ]$ � � x% �0 * �3 4 4 > : H H R � \ � f � p z � q � � � � � � � � % � 9 � M � L N �. � !� � {B �? r � ? �4 � O �5 � _ 6 O 8 B _ 8 N o 8 �6 �� � � � 8 �6 �k �5 � �+ $ � n ,� 15 -� F / � �# 0 � Z 2 q $� 4 � (� 9 � 0_- = 8� ? @� J� Hc) K� X� L� h�( Yk x 3 { 8 (tm 8 q = q � q � q � q - q U. q 4 q �% q �3 � (G 0 �, X h2 ? R4 u q ,2 N � b� � d ? � e u � fq V gq �% h u � �� 4 ? �6 u � q z) ? i D& 63 F ? `* G u 7 Hq D 6 8 � *DIR B �. "IV o� G "UV p8 "NV �m ! !� � f � { "OP h � (op ( �j > �s/ V �s/ ��E 6 �D �$ ��. � ��. �- ��. \6 ��. "$ ��. �3 ��. w ��. �+ ��. D. ��. " ��. # "COP i v 4cop X �� > �s/ V �s/ ��E 6 �D �$ ��. � ��. �- ��. \6 ��. "$ ��. �3 ��. w ��. �+ ��. D. ��. " ��. #� �/ $� �D (�4 � ? 0� � / 8� � / <[ �YK @�' � cK H�+ � / P # o � � ` � > �s/ V �s/ ��E 6 �D �$ ��. � ��. �- ��. \6 ��. "$ ��. �3 ��. w ��. �+ ��. D. ��. " ��. #_ � s/ (�+ � s/ 0�# D 8T- / @� �E H� F P�& s/ X s W6 P �/ > �s/ V �s/ ��E 6 �D �$ ��. � ��. �- ��. \6 ��. "$ ��. �3 ��. w ��. �+ ��. D. ��. " ��. #_ � s/ (�+ � s/ 0y � s/ 8� � s/ @� � s/ H 7 ~ < : �r$# �( #Z/ .Iop $s/ H) %Z/ [ 'Z/ �5 (Z/ � *W ( ,�. 0 -�. 4h6 /W 8� 0�. @� 1�. D� 3Z/ H�1 4h P8 5h XD$ 6h `� 8/ h+ :W p�3 <W x� =W �� A�. �� CW �+ En/ �M H�E �M- K�< �� L�< �p( Nx/ ��4 Ox/ ��3 ^�. �� h�. ��7 i�. ��- jd/ ��# v�. �o' }�. ��4 �n/ �� �n/ �z( �kN �v �i/ ��) �W �B- �i/ � �4 �G ' �P/ d �P/ � ��< j � W } �#W ( " �WD 0 � �$# 8 ' �$# P � �$# h �$# � �$ �@. � : �@. �5ISv �P/ � �(W .* �n/ 5Ina �{ � �� � �d/ � � �P/ �5Irs �P/ � � �d/ � � �d/ � r �d/ � � � � t6 �P/ � �4 �P/ � ^1 �P/ �> s/ � �L � �L * <K � P/ � 0 �1 �� s/ 1 s/ � n/ �# d/ � d/ o2 ? (D { 0�& �. 8�2 ?�. :� Ax/ ;| Bx/ <z+ Cx/ =29 Dx/ >� H& ? KP/ @7 N-W HX e�V x� }�V � ��V ��- �u �7 �? � �/ �1 �/ �� �q �6 �q �@ �u � �d/ � �d/ �]. �d/ �2 �? �\/ � �� �P/ �9 �P/ �� �P/ � �=W �z0 � � �x/ � �x/ � �x/ � �x/ � �x/ w �x/ h �x/ �x/ # �? P �P/ w �t { ��. (O ��. ,� ��. 0�1 �q 4e �BW 8� �d/ @� �d/ H� �d/ P�- �d/ X �i/ `�7 �d/ hy1 �d/ p&' �d/ xD �d/ �6 �d/ �\ �P/ � �P/ �{. �P/ �� �i/ �� �GW � �n/ �@ �n/ ��4 �P/ �> �i/ �l �i/ �( �i/ � �i/ � �i/ 2 �i/ � �? ]9 �7 � s/ � s/ (n# s/ 0v s/ 8�" kN @w3 q HM q L�& ? P_ i/ X7 P/ `\ P/ h�) q pb �. to8 x/ x�/ x/ y�% �. z� q |� �. ��3 #�. ��/ $WW ��* 3n/ �- 6\W �� 8j � :�7 �~ ;RD � <D �8 =D 4% E�7 �* Fq I/ $� Kx/ (� Lx/ )| Mx/ *� Nx/ +�8 Q\ ,� R\ 0� SP 4T, TP 8CIan U/ <�7 X/ @h `/ D} c/ H ) d/ LG, eu P i? X� k0 `` n�/ h� o�/ p� qaW x)) s/ �J u/ �] �U �/ �P/ �- ��. M �D l �D �' �D ( �6 �D 0 � �D 8 3 �qW @ _2 �? � n �� � � �� � � �/ � / ��. � D �x/ � i1 ��. � �( �x/ � �/ �? � �. �� � �8 �? � V �� � M. �x/ � d3 �x/ � � �$V � �% �x/ � � �? � 2 �q � % �x/ � �# �x/ � �, �? � M0 �P/ � �* p/ �x/ l7 �x/ �, �Z/ 1 �Z/ Y3 ��W ( �i/ 0 �0 � 8 t Z/ @ �. i/ H �W P � D X ( D ` . �W h �' n/ p y n/ x 2 �/ � T( �W � � �W � 0 i/ � e& i/ � �5 � � � #�U � ?% $�U � � -�U � j$ 1�U � � 4�U � � 7V � � :n/ � �" @n/ � � Ci/ � En/ � �. G�W �8 K�W > MbV 3 P�V X �6 Y�W ` � Zq h y bSU p f o�W � �8 zD � 6 |{ � � �D � �2 ��W � �& �P/ � � �P/ � �* �P/ � � �P/ � $/ �P/ � X �P/ � �P/ � 3 �P/ � �P/ � �P/ �" �P/ � �P/ � �P/ ( 6 �P/ 0 � �P/ 8 �$ �P/ @ � �P/ H R5 �P/ P Z' �P/ X �5 ��W ` �6 ��W � .8 �P/ ` �P/ h�) �P/ p �P/ x� �P/ ��. �P/ �& �P/ �' �P/ �84 �P/ �I �P/ �=3 �P/ �� �{ ��/ �{ �R1 �{ � "SV � 4# $# (sv �t# 4' � # �/ � �/ Z �Y1 "AV � # (av ��# 4' �O3 # �/ � �/ Z ��2 "HV � �# (hv � $ 4' ��3 # �/ � �/ Z �T3 "CV � $ $ (cv �Z$ 4' ��2 # �/ � �/ Z �^2 �, � g$ 9 �$ 4' P6 # / � / Z S4 "GP � �$ (gp P e% !4 P/ G D �, �7 0" / � / j/ n/ e, i/ (. �7 0w d/ 8:- / U" / �" �6 H "GV � p% (gv �% 4' �Y2 # �/ � �/ Z ��1 4io �% 4' N4 # / � / Z �3 � & � h n & (% rCO �3 h ��& � � �. � � �. - � �. ' � �. � �. �$ �. �) kN R9 �< � h s �. (;' N 0 ,$ � �& j 0!K' �# ! 7 ! �P 41 ! �. |8 ! D � ! �. r ! h ? ! P/ �, ! ? ( "XPV � W' 4xpv ��' �( �n/ *" ��6 � �{ � �7 � � �' � ( �' �( n/ *" �6 � { � )7 5 �6 � � ( f7 (" [( �( " n/ *" " �6 5, " h 5 " h @# " Z/ 6 � h( #��( �( #� n/ *" #��6 �& #�{ � #�{ � � �( � 0 ;) �( <n/ *" <�6 � <{ � <M7 5 =�6 � >U6 ( � � ') �8 h$ �) �( $n/ *" $�6 � ${ � $�D �' $n/ �* $�D (_ $�D 0� $E 89" $? @� $<E H� $�7 Pj0 $/ X20 $q7 \�/ $�. ` � �) � � e+ �( fn/ *" f�6 � f{ � f�7 5 g�6 � i�1 ("9 v�7 0�% x G 8� y G @_% z G H03 { ? P�) | d/ X� } ? `�4 ~ d/ h�- ? p� � d/ x, � D �� � �. � $ � + � @! �+ @ ! $P �4 ! $P � ! BP �1 ! $P �0 ! $P 57 ! oP (*0 ! �P 0 ! $P 8 "ANY � �+ Dany �~, � � �P/ �1 �Z/ � �d/ < �i/ C �n/ o �s/ � �? � �u 0 � �. � � / � � G 1 � W �2 � � �( � x/ w � >/ "2 � �/ �- y�, k z?U �2 {z ~ | � � �, �, 0'- *# �DU � � W < � W ( �NU a �?U �?U ( � � 4- F ( ��- &* �i/ . �W �+ ��/ � ��/ � �i/ P � �- 8 % �- r % h � %&\D ^ %' / + %( / "PAD � t# � � �- (%+@. / %, h # %-�D g %. h G %/D � %0 / _ � M. � 0%L�. �8 %M? j- %Mn/ � %M�D + %M/ ( %M/ X# %M/ �4 %Mq $8& %M�. (� %M�. ) *I8 &�? *U8 &� *U16 &�% *I32 &�q �. *U32 &�1 / E/ � &� / � Y '>/ 3/ �7 � $# P/ P/ Z/ e% t# �# � !H '�/ �/ / / D �/ 8 < '<�/ � � '>�/ �/ } 'Q �/ o � (4e � (5�/ �/ '0 q 0 &/ � (;�/ 9�' )�\0 2 )� �. �" )� ? �" )� s/ T' )� d/ �' )� 0 61 ��0 � �0 ; B" � �, 0 G � � ^ 2 ) *HE ��0 (he # 1 1. #$ �1 #% �6 #)�J *HEK �%1 (hek #-Y1 ;( #./ � #/�. �- #5�/ ��1 � �? N �G 5 �W � �b S �P/ '4 �Z/ � ��1 p ��1 ��1 �1 �0 �$ �/ �Y2 � �? N �G 5 �W � �b S �P/ '4 �Z/ � ��1 p ��1 ��1 �( ��2 � �? N �G 5 �W � �b S �P/ '4 �Z/ � ��1 p ��1 ��1 ) �O3 � �? N �G 5 �W � �b S �P/ '4 �Z/ � ��1 p ��1 ��1 �' ��3 � �? N �G 5 �W � �b S �P/ '4 �Z/ � ��1 p ��1 ��1 [( # N4 � ? N G 5 W � b S P/ '4 Z/ � �1 p �1 �1 �) # �4 � ? N G 5 W � b S P/ '4 Z/ � �1 p �1 �1 �$ �*nP6 �( *on/ *" *o�6 � *o{ � *o�8 � *p!�9 B4 *q �8 (x" *r n/ 0�4 *x / 8P# *y / <� *z h @� *{ h He *| { P�1 * �9 XJ+ *� `�1 *� / h *� / l *��9 p� *� u x�& *� / �+ *�/ n% *�/ $� *� ? � *�P/ ��$ *� h ��7 *� h �� *� h �$ *� h �� *� �7 � �4 7Y% ��6 � � b �, � n/ :* � / >7 � x/ 7C5 ��6 �$ � G �* � W �6 � �6 4 � x/ 1 7 9 � 7 f � 7 @ � { �& # �)7 � �{ p �P6 # M7 � { p P6 # <q7 � <{ p <P6 S+ A / '�7 �/ �7 $ ~7 �- # f�7 � f{ p fP6 # s�7 ^" t�7 �2 u 6 � * 8 . *�. 8 * �. * * �. � * �7 X (*(z8 } *) h � ** h k *+ P/ f *, P/ � *- h 1 �*/�8 ;. *0 �. �7 *1 �8 +8 �8 8 -+ *<�8 *= h .end *> h � *E h -+ *F�8 Z$ �8 *o 9 � *o{ p *oP6 � h*��9 4 *�H: g *��: � *��: �0 *��: � *��: �8 *� ; (0 *�6; 0)6 *�Y; 8, *��; @�# *��; H+ *��: P?1 *��; X4 *�< ` 9 �9 z8 �8 �$ *��4 � *� : |, *� u � *� : h (( *��9 �8 H: �/ U/ / /: �. �: �/ �8 ? ? ? h P/ / M: ? �: �/ �8 P/ ? ? / �: #: �: P/ �: �/ �8 �: '�: �/ �8 �: ' ; �/ �8 �. U/ �: ',; �/ �8 �. 1; /# ,; ; �. Y; �/ �8 1; �. ;; P/ �; �/ �8 U/ U/ / ^; P/ �; �/ �8 1; / �; �; �/ �8 �; '- �; �8 < �/ _/ q s/ �9 �8 < / / x/ �; X*� �< rex *� �< N- *��< *�P/ � *�? �$ *� { �7 *� { (� *� { 0 sv *�P/ 8�" *� 7 @ pos *� h HQ *� �. P �9 � �* *� < *� = �* *� = � *� c= *� �= *� ? �< ~ �*�c= N *� q � *� ? � *� ? sr0 *� )? u *wC = :k x*��= � *��C �5 *��= hk *�"�= p h= �( *��< + *� �. *��= �3 *� c= *� > �3 *� c= *� / �& *� / cp *��= *�n> �3 *� c= *� / �& *� / cp * �= � *n> 8 @*$? �3 * c= * / �& * / cp * �= K' * / M * x/ r *$? me *n> (� * )? 0e * / 8 * �. <$ * �. > �. �. @*�? �3 * c= � * c= �' * $c= � * �8 cp * �= �6 * �= $� * / ( B *!n> 0� *"? 8 0*% @ �3 *' c= �. *( �. �) *) �. � **�. *+? end *,? me *-n> ( *0c@ �3 *2 c= � *3 c= � *4 P/ T7 *5 ? *8|@ val *9 q 8*>A �3 *@ c= � *A c= me *Bn> B *Cn> cp *D�= � *E x/ $� *F q (� *I q , *J ? 0 (*MmA �3 *O c= �! *P c= cp *Q�= �6 *R�= *S ? �. *T �. T *U �. $ `*X4B �3 *Z c= c1 *[ q c2 *[q cp *\�= *] / �& *^ / ) *_ �. � *` �. � *a x/ $ A *bn> ( B *bn> 0 me *cn> 8�2 *d4B @� *e4B N �. DB 8 h*hC � *i / cp *j�= *k / �& *l / c1 *m q c2 *mq �, *n ? g *o ? � *p q ( min *q q , max *qq 0 A *rn> 8 B *rn> @�2 *s4B H� *t4B V #h*��C �( *��= �* *� �< 1yes *��= � *� �= � * > :% *s> � *#.? �& *.�? ' *6 @ S *:c@ " *K|@ 14 *VA j *fmA � *uDB ~ *x= �C �C 8 k *�h= S +D8 �% i %h $%!RD %"RD %# WD % %$ WD �- �- % ~D 2 % ~D %%�D WD !D �D @. %M�D j+ %Mn/ o %M�7 $�D � ${ p $P6 $�D A' $s/ ] $�+ $E * $s/ � $�7 $<E �' $d/ �0 $�6 $^E 4 $�7 � $ � �E �6 �D ,sv �P/ ,iv �G ,uv �W ,pv �? �h 0 �^E s/ �E �/ �E �E # F s/ P2 D t d/ # &F � s/ �# D � 0,1�F � ,3 ? �" ,4 ? �. ,6 � �3 ,7 � � ,8 ? q ,9 ? �/ ,: ? ( � -*�F �$ -, ? � -- ? � -. � U/ -/ u ;?+ �.H3G -% .M3G q .V3G � � .[DG �( .bUG � .iD � � .nfG D DG 28 D UG 28 � D fG 28 � D wG 28 �w 6 H/+�G � /- ? � /. ? � //� V /0� � /1� /2� ( , /4� 0� /6� 8�7 /88 @ F�0� �J " 0�? � 0� � � 0��J p 0�? � 0� � Q 0��F (C 0�? H�0 0� � P 0��J X� 0�X `� 0�? �� 0� � � 0��J ��- 0�q �# 0�? �� 0� � �j* 0� ��' 0�? �t 0� � ��$ 0��J �b( 0�q �4 0�� � 5 0�? 0� � 0��J � 0�&F � 0�? H�2 0� � P� 0��J X� 0�� `h" 0�? �' 0� � �8 0��J � 0�wG �) 0�? �p 0� � �� 0��J �� 0 { �z' 0 { 0B& 0"? h� 0# � pD( 0'? x�6 0( � �_& 0, q � �F �F X � &F � wG 0 0-�G #&�J >, #'P/ #( � � 7K �5 !7K D1 "� G # q � 6 $ x/ �F %�. �5/ &h � �J � )�J � � TK :) { YK HK �" 0 S�K T s/ c8 U�. D W WD cv X �7 f' Z �. 95 [ i/ ( ? 0 `+L a s/ c8 b�. D d WD cv e �7 gv g d/ �/ h d/ ( � 8 ��L � s/ c8 ��. � � P/ y# � s/ I9 � P/ cv � �7 (^+ ��L 0 <K # ��L 1svp � Z/ 1gv � d/ ��L ary � i/ ix � G �M �* � �. ix � G �6M cur � G end � G �]M cur � P/ end � P/ # ��M 1ary ��L l ��L �, �M K1 �6M Q6 0 ��M � � �M K" ��L �& �P/ �+ �]M � � WD ( + � N I5 �s/ �' � P/ #8 kN " hK �. �K � +L �. �M $ �M j �4 X .CO $1 / �. } 0 �. U 1 �. � 2 �. � 4 h ) 5 h � 6 ? 7 7 P/ �) 8 P/ (�! 9 ? 0�! : ? 8� ; ? @ < H- =�8 P #h ogO � p & �4 qpN �) 8 �O i i/ � �O � �O �/ �O � �. � �. $� �. (� �. ,$ �. 0 �% gO $ !gO q $P �/ P/ 7 P / BP �/ P/ 7 )P q oP �/ P/ 7 P/ �. GP q �P �/ 7 �; tP + $1 �P .val 1 \0 U 1 R 1 �. 1 �7 1�P � (10Q � 10Q � 1 P/ 1 ? l5 1 ? � 1 P/ �P < 1 �P ;G6 �1"U 1&U , 1'\0 �# 1(q 1+q l 1- U * 1. U .ps 1/ U (� 10q 0 14 �. 4�) 15 �. 8 16 �. <! 17 ? @x 18 ? H�( 19 �. P " 1: �. Q` 1< �. R�& 1= x/ S" 1>x/ T� 1? �. U� 1@ s/ X�+ 1A s/ `% 1B P/ h� 1C �. pO 1D �. r� 1E �. t� 1F P/ x� 1G �. �e 1H �. �� 1I W ��6 1J W � 8 1Kx/ �A 1L �. �" 1M �. ��" 1N �. �* 1O s/ �( 1P P/ �� 1QU �� 1R P/ � 1S ? �5 1V ? �5 1W ? �� 1X ? �<8 1Y ? �v 1Z ? � 1[ ? �Z 1` / �y* 1a �. �� 1b �. � 1c �. � & 1d n/ � 1e �1 �7 1f i/ � 1h U T 1i #U @ �1 1j �. T � 1k �. U * 1l �. V b 1m �. W � 1n kN X � 1o & ` �6 1p / ` �$ 1q / d F/ 1tW h F8 1uW p g 1vD x � 1wx/ y 1yx/ z0 1{�. �D 1|�. �� 1}�. ��+ 1~�. � AQ �P 5Q \0 #U 8 �. 3U 8 G6 1AQ ~, ?U $ IU � ��U ��/ �5 �$�U k �$�U SU 5 &�U �U q �U �/ � '�U �U '�U �/ P/ � (�U �1 *�U �U x/ V �/ P/ � +V V '$V �/ G� 1 ybV { � �1 S8 �+ �( z5 H V pad V $# �V 8 � &�V �V '�V �/ s/ � :�7 F >�V _0 BV IW fn J �/ ptr K �- L�V �+ �. �O �C �C 3U ? =W 8 q G WW 8 W / qW 8 ? �W 8 �, n/ �J �/ K' P/ �W 8 " D �W 8 P/ �W 8 HZ <-C/ 61 2>�X ; � r � ^ � ( �* } �% 7 '7 � �' �0 L �/ H N$ M* �, && �+ �$ � �5 �( �% k) � �2 61 3�Z X 22 � L � z2 �1 g � �3 d � � 6 � o 9 ( E � d R 9 ( D � c Q � S& � !D* "p #�% $k %� &J3 '�% (d )�2 *� +�# ,� -� .3# /� 02# 1'- 2 3&- 4 5t 6�& 7s 8�& 9� :e# ;�- <�- =� >� ?\ @}7 A� B�" C�2 D� EW F G� Hk, Iz7 J� K 41 �Z ,u 43�Z ,c 44�Z � �Z 8 �Z 8 � 45�Z %a5 7? %� 7"? %}4 7@? %] 8? %�3 8 ? % 9? %d4 ;? %� ;"? %y- ;D? % <? %[ <$? %o4 =? %�" =(? >6 ,4?�[ .txt 4A �[ .bcd 4B �[ D �[ 8 � �[ 8 *BCD 4Ca[ <<0 K�[ �/ U/ R )2$ 5� P/ �[ �/ )�5 5� G \ �/ U/ �. )� 5k P/ $\ �/ R =� �6\ 3 )7 5� P/ R\ �/ U/ ) 5� P/ s\ �/ � )7 5} Z/ �\ �/ Z/ Z/ h )�1 5� ? �\ �/ U/ ^K �. =<2 ��\ �\ $ �\ <I &�\ �/ �. ). 5� �7 %] �/ �V / )4 5(�. G] / 3 )� 6 ^] Ig 73 q z] q 3 0�) 83�^ 83�/ cv 83�7 ax 88 �. ' 88 Z/ sp 88 Z/ @ 88 �. �4 8= cv 8L�7 �] p_ 8O ^ p_ 8Q !^ p_ 8S 3^ p_ 8U E^ p_ 8W W^ p_ 8[ i^ p_ 8] {^ p_ 8_ �^ p_ 8a �^ p_ 8c �^ p_ 8e �^ p_ 8h �^ p_ 8j �^ p_ 8l p_ 8n +c �_ 8�/ cv 8�7 sp 8 Z/ ax 8 �. ' 8 Z/ @ 8 �. ix 8�. k_ p_ 8 s 8 P/ ip 4 �_ �/ 4 ? wa 4 �Z len 4 { � 4 R +Y ��` 8��/ cv 8��7 sp 8� Z/ ax 8� �. ' 8� Z/ @ 8� �. ix 8��. 3` p_ 8� s 8�P/ ip 4��_ �/ 4� ? wa 4� �Z len 4� { � 4R +�7 �:a 8��/ cv 8��7 sp 8� Z/ ax 8� �. ' 8� Z/ @ 8� �. s 8�P/ ap 4��_ � 4� wa 4� �Z len 4� { )a � 4�R � 4�R +� o=b 8o�/ cv 8o�7 sp 8q Z/ ax 8q �. ' 8q Z/ @ 8q �. ix 8r�. >v$ ��a p_ 8r s 8xP/ n 4��[ � 4��Z �4 4� �Z cp 4��_ � 4� �/ 4� ? len 4� { ,b � 4�R � 4�R +@ >�b 8>�/ cv 8>�7 sp 8@ Z/ ax 8@ �. ' 8@ Z/ @ 8@ �. ix 8A�. �b p_ 8A s 8GP/ n 4u�[ cp 4v�_ len 4w { � 4�R +� �c 8 �/ cv 8 �7 sp 8! Z/ ax 8! �. ' 8! Z/ @ 8! �. �c s 8%P/ bp 4`�_ �/ 4a ? len 4b { � 8,q 9 8-U/ � 87 G � 89R +� ��d 8��/ cv 8��7 sp 8� Z/ ax 8� �. ' 8� Z/ @ 8� �. s 8�P/ � 8�. �4 4H�Z ap 4I�_ wa 4J �Z wb 4J�Z len 4K { xd � 4WR � 4YR +, ��e 8��/ cv 8��7 sp 8� Z/ ax 8� �. ' 8� Z/ @ 8� �. ix 8��. >q &e p_ 8� as 8�P/ bs 8�P/ ap 4 �_ bp 4 �_ �/ 4 ? wa 4 �Z wb 4 �Z �4 4!�Z len 4" { �e � 4?R � 4AR +k xyf 8x�/ cv 8x�7 sp 8z Z/ ax 8z �. ' 8z Z/ @ 8z �. ix 8{�. f p_ 8{ s 8�P/ ap 4��_ �/ 4� ? wa 4� �Z len 4� { i 4�q hf � 4�R � 4R 8U �q �f ,9 4��_ n 4�'�f bcd 4� *3 4� i 4�q j 4� q �[ 8T �q �g & 4��_ n 4�)�f tmp 4�� � 4� � - 4�"� P/ 4�(� � 4�.� ' 4� � u, 4� c 4�q i 4� q j 4�q p 4�q 0{- 4i h bp 4i _ 4i h 4i+ h len 4i6q i 4kq �5 4kq lo 4k q c 4l cp 4l �_ �Z 8� ID �h str 4I len 4I q n 4I(�f i 4Kq j 4Kq lo 4Kq c 4L � 4L �_ sp 4LC�_ 0� 4;�h _ 4; h � 4;% h �) 4;1D ap 4=�h tp 4=)�h � 0 4*i _ 4* h � 4* h ap 4,�h tp 4,)�h 0�1 4Ni ap 4�h p 4�h �6 4#� � 4)� -�# 4� �i ap � p0 ��h p1 �0�h p2 �>�h p3 �L�h � 4 /� ��i ap � len �q a ��h /� �j &�) 4� src �" len �+q d ��h s �$�h - 4�q (j bp � p ��h -^ 4�q Kj bp � p ��h -�0 4�q �j aa � bb �!�h &_ 4�, h con �;� tmp �� -% 4�q �j aa � bb � &_ 4�' h &� 4�2q i �q a �� b �� r � � /% �k aa � a ��h /�2 ~7k aa ~ ux ~ a ��h /K t_k aa t ux t a v�h /P) I|k b I? c Kq J� 9 �. �k 9 �/ � 9" �. � 9# �. K� 9��. �k & 9��/ -� :Tq �k & :T 3 -� ;9 #l &�) ;9 &2 ;9q &� ;9� L� ; &�) ; &� ; &� ;� I ~ H } 4 1�B H} 1�B 4 1 H} 1U .1@z 1R�B X!Y W! 1 . 1 1 1R�B UX YW 4 1 1R�B X!YW H}� 1R�B X!Y!�W! 6 1 . ?<n:!;! % 1R�B UX Y W 1R�B UX YW H }� . ?<n : ; 9 I8 : ;9 I8 : ;9 I8 !I ( I 4 : ;9 I : ; 9 I : ;9 I 4 : ;9 I : ; 9 I : ; 9 I8 : ;9 I8 : ;9 I I : ; 9 ! I/ & I 7 I : ; 9 I k : ;9 : ; 9 : ;9 I : ;9 : ;9 I :!4; 9 I 4 :!4; 9 I < : ;9!I k 'I !$ > " :!;9 I # : ;9! $ : ; 9 %4 :!4; 9 I? & : ; 9 I '' ( : ; 9! ).?: ;9 'I< * : ; 9 I +.:!8;9!' , : ; 9 I -.?: ; 9!'I . : ; 9 I8 /.?:!4; 9!' 0.?: ;9!' 1 : ;9 I 2! I/ 3 4 : ;9! 5 :! ; 9!I8 6>! !I: ; 9 7 !:! ;9! 8.?:!4;9!'I 9 !: ; 9! : : ;9 ; : ; 9 <.?:!5;9!'< =.?:!5;9!'�< > :!4;9! ?% @$ > A B& C : ;9 I8 D : ;9 E5 I F : ;9 G> I: ;9 H4 : ; 9 I?< I.?: ; 9 'I< J.: ;9 'I K.: ; 9 'I L.?: ; 9 'I � K � < N d l u | � � 0% � K #.]f", � �� ��z ��v � �r ��n ��j �gf � v <�� � � �� ��x ��t � �p ��l ��h Xx �d e t e. XKvu.=�Kvu.=�� Ks� .XX�yX# � �y. J �< �X ;KK tv �tL Xf J��~JJX � < J � �=X;iY f ' Y - K � � �<�.�}�X v� � � X� ��}XJ1�tU��� Ks� .XX�yX# � �y. J �< �X ;KK tv �tL Xf J��}JJX � < K �� �=XeiY f J � � � �<�.�}<X � � X � . � � � z � .�$��}XJ1����z�K>L`K2k�<+ .$ rJ Jf X�K 6 =w.A / = = X , K =W X t t��t Ks� .XX�{X# � �{. J �< �X JJ<K �f <` x.��~�� J �~� � � J X � � �X �~.�< X. � * t J L � � <� s� �~( � �� ��~�<XX�iX� P. �{K /- J t�AK � X < u J X�L � 0 J , > ^�� Ks� .XX�{X# � �{. J �. �X ;K ;tgK L �f <L :Z,f J�L X�~�� � < J � �� � J J � ��WY�� f X . 2 � � t J L <) tKL�%�J<�t]t��~$� f ' Y - K t � e � �� . X � � � � � y � Xpw�(�NX�~���� Ks� .XX�{X# � �{. J �. �X tJ� �f<L :Z ,f J�LX � � J �~< � � < J � �! f X 7 Y - Y � X J L <) tKL�%�J<�t]t�"�~J�JY f ' Y - Y t � v � � � �~� � � � Xy<�� ��{XK @V� ;/ � 0+= = � 0+= / � I=Jr. <JJ�< Ks� .XX�yX# � �z. J �< �X Jtu �fZ Xf J��~J<X � J J � �X� � -/X � - Y - K � X J L <) tKL�%�J<�u\����~& f t � Y - Y t � v � � J � "�cX�~�<�|XK 9L O E/ WgzX /g / @ Ej@Z�� Ks� .XX�|X# � �|. �J �|< �< �<u IKK� ,< vX> � J��~J� � < J � �� �2��|�X� f J � � � �<��~��� [� t X � � XJX<X� t t � J ���|� X� � f JyXtXJ t � �XY�J/ ' � � e " X�EX�~� h J1��E�0�.�~�K�LY @8K � � �Y� H� ,X �= KXM 58Y =>z � �u ,X 0> K WU =O�} �J �}��J �}f<�� �}.�� wJ =Dw<KqJ <Y<[;] E=KL 9i K/^ �}f�J��}� �}�<��} < ��Xj[Y;f/ j� e JK <j:xf .Hx� <pJ f[YIk Jm���. ��s��/ us� .XX�zX# � �z. J �< �X�J= I= ;KK �,<<Wv Xf J��~JJX � J J � ���� f< " � t Y�Y� f J � � � �<�J �}J � W <� ��JKX� . � k � � � � X��~���%��~XE s��.w�. dX ��X��}<Kz 4 �}J�J9N* �} �X �}J �t�}X� �}�f� K; = W V J Yf tZW�=Z = 7 <5/-g uo JKn xX < .xJY(>� dYX�� J..CK �� < xJ Jg Y ftfY 8< N8K ; <J�<= vJ JKv f ��. Ks� .XX�zX# � �z. J �< �X ;KK tv �tL Xf J��~JJX � < J � � �� f X f � � J � � � �<��~J� X� f � y � V < �� . � y � � � � y � X�(��~X���&N .ft 2p j�X$Xt & -< uX � -< uX � �< uX � -< uX �0 q< uX # * & -< uX � -< uX � �< uX � -< uX � -< uX �/ r< uX # & -< uX � �< uX � -< uX � w.< tZH0 > HX u m �� � < z � P N =u � � � � , � � � � � � � � � � + � � l � � � � � " � � � � u � � � � � � � � X � 8 J � | � 9 ` ? d P � B u | l � � GNU GIMPLE 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -mtune=generic -march=x86-64-v2 -g -O2 -fno-openmp -fno-openacc -fcf-protection=full -fPIC -fstack-protector-strong -fltrans -fplugin=annobin __builtin_puts __stack_chk_fail __builtin_putchar Ilaststatval long long int old_parser subtr_ass_amg blku_oldsaveix Iorigargc Iorigargv si_errno keeper __pad0 tbl_arena_next _spent_size Iin_utf8_CTYPE_locale hostent ls_prev close_paren lex_stuff xpvgv Istatcache is_simple_pack Icompiling Idbargs new_perl blku_oldsp sub_error_count xpvhv PERL_CONTEXT _asctime_buffer Inumeric_standard prevcomppad Ie_script sv_u Ipreambleav XS_NetAddr__IP__Util_comp128 IDBcontrol memset xpvio xpviv tbl_max si_tid Imy_cxt_size blku_old_tmpsfloor Imain_root xcv_outside blku_type _PerlIO __locales he_valu Iutf8_totitle _spent_struct named_buff want_vtbl_hintselem extendipv4 h_length op_first Idoswitches _netent_size thrhook_proc_t next_branch Perl_POPMARK block_eval s_port __in6_u in_port_t gp_refcnt prev_mark Idef_layerlist saw_infix_sigil Irestartjmpenv save_lastloc Iwarn_locale _spent_buffer Icolors mg_obj je_old_delaymagic fallback_amg multi_end PerlIO_list_s PerlIO_list_t COPHH scream_pos Iargvgv despatch_signals_proc_t rshift_ass_amg xio_flags Isharehook tm_mday old_regmatch_state xcv_xsub nextword Iminus_E Icheckav pad_1 pad_2 Imarkstack Idump_re_max_len tm_zone Istatusvalue IDBsingle utf8_substr __u6_addr8 min_offset pmop st_atim sival_int Ilast_in_gv Ireg_curpm share_proc_t Ihash_rand_bits_enabled pw_gecos netswap_copy _call_addr long double op_private _isipv4 lex_formbrack SVt_LAST __ch sbu_dstr XS_NetAddr__IP__Util_bin2bcd Irunops Ipsig_pend _ctime_buffer Icomppad_name Imarkstack_max sbu_iters internal Ireentrant_retint saved_curcop max_amg_code __blkcnt_t PTR_TBL_t sig_seen xhv_max _protoent_size hent_hek _grent_ptr _getlogin_buffer xivu_eval_seen __locale_data pos_flags Istack_base exec Imax_intro_pending poscache op_pmstashstartu to_gv_amg group sbu_strend smart_amg re_scream_pos_data_s cop_stashoff s_addr st_size sge_amg pthread_key_t Iperldb lastparen si_addr_lsb Iinplace __locale_t _pkey tm_min IDBline want_vtbl_nkeys sin_amg Isv_arenaroot jump gp_egv newval padname states xio_bottom_gv Iphase yylen subbeg cos_amg _asctime_size tp128 Iblockhooks end_shift sbu_oldsaveix _pwent_ptr Iosname n_addrtype lex_casemods lex_brackstack numbered_buff_STORE Iefloatsize PADLIST Ipeepp PADNAME __printf_chk Iregex_pad retop xcv_padlist_u minmod sp_pwdp Iutf8_foldclosures Ilocale_utf8ness Isv_yes carry parenfloor branchlike JMPENV Imain_start qr_anoncv Istashpad _arch my_perl Ienvgv binary msk8 Iperlio Ipadname_const Perl_xs_boot_epilog __wchb pow_ass_amg mult_ass_amg Iregmatch_state prev_rex Iisarev Iutf8locale tm_mon XS_NetAddr__IP__Util_addconst op_opt c2_utf8 sa_family_t sockaddr_inarp subcoffset svu_fp yy_stack_frame Idebstash topword XS_NetAddr__IP__Util_add128 want_vtbl_ovrld reg_substr_datum si_stack xpadl_max Inomemok __uint8_t tm_hour firstpos want_vtbl_debugvar Imbrlen_ps Idiehook prev_recurse_locinput any_ptr Sighandler1_t CLONE_PARAMS Icompcv padnl concat_ass_amg _128x10 lex_repl timespec PerlInterpreter xpadnl_max_named ILatin1 Isighandler1p st_nlink Iminus_F re_eval_str Iscopestack_ix sp_max Iscopestack_max iter_amg Iminus_a any_pvp Iminus_c want_vtbl_arylen_p Iminus_l Iminus_n Iminus_p Iargvout_stack Iinitav Perl_newSVpvn sin6_family tm_yday tbl_items Perl_ophook_t cache_mask ap128 firstchars xpvlenu_rx Imaxsysfd Ilocalizing Isighandler3p lex_shared servent _crypt_struct_buffer rxfree ncmp_amg pw_name sp_lstchg curly _getlogin_size nomethod_amg add_amg Iunicode __fmt blku_sub qr_package neg_amg Irestartop ICCC_non0_non230 PL_thr_key gofs __mask_was_saved PERL_PHASE_CONSTRUCT Ilastgotoprobe cop_line Isecondgv __locale_struct Isavebegin want_vtbl_vec initialized XPVAV to_av_amg STRLEN n128 exitlistentry abs_amg op_ppaddr xpadnl_alloc Icheckav_save Idebug_pad __jmp_buf_tag concat_amg lex_flags Iendav blku_oldscopesp Iutf8_idcont Icomppad_name_fill my_op IHasMultiCharFold __mbstate_t tmpXSoff XPVCV add3 regnode Iperl_destruct_level si_cxix mg_virtual padnamelist interpreter PMOP Istashpadix Perl_xs_handshake st_uid longfold sp_min xcv_xsubany PADOFFSET sbxor_amg sbu_rflags xpv_cur xpadn_flags Istderrgv xio_page_len perl_memory_debug_header printf Iin_clean_all si_type mark_name Istashpadmax old_regmatch_slab is_hasbits __ino_t fastcomp128 reg_substr_data lex_super_state _grent_struct xcv_root_u curlym setting Icustom_op_descs si_prev XPVGV _addr_bnd sp_namp lex_starts Isavestack Sighandler3_t si_code Imodcount prev_curlyx Isortstash Istdingv svt_local sp_warn Icustom_ops sbor_ass_amg CHECKPOINT XPVHV any_av _grent_buffer sne_amg XS_NetAddr__IP__Util_ipv4to6 last_uni XPVIO sp_expire XPVIV __uint16_t is_shiftleft minlenret Iofsgv cnst TARGi_iv Idelaymagic_gid xcv_gv_u Iunderlying_numeric_obj Icollxfrm_mult tbl_arena_end Isavestack_ix want_vtbl_defelem sockaddr_x25 SVt_PVAV sin6_flowinfo have128 xmg_magic svu_gp any_dptr intuit Ibody_roots si_sigval hek_len Icollation_ix tokenbuf op_nextop line_t mgvtbl XS_NetAddr__IP__Util_hasbits Iutf8_xidcont si_cxstack yyerrstatus Siginfo_t _hostent_ptr sbu_rx xcv_padlist svt_get _Bool svu_iv sbu_rxtainted seq_amg div_ass_amg op_moresib c128 xpv_len_u Ipatchlevel badc _128x10plusbcd _pwent_struct nextval svu_pv any_gv memcpy not_amg Ihash_rand_bits sbu_orig _servent_struct __gid_t Iparser xpadlarr_dbg stack_max1 runops_proc_t any_hv Ipadlist_generation SVt_PVFM xpadnl_max Idefoutgv _lower Istatusvalue_posix _pwent_buffer Iutf8_tosimplefold __ctype_tolower siginfo_t Perl_newSViv any_iv sv_flags Ichopset Irpeepp oldcomppad sbu_rxres SVt_PVGV Iincgv si_markoff xpadnl_fill want_vtbl_arylen tv_nsec nexttype is_sub128 sig_slurpy want_vtbl_backref Icurpm_under SVt_PVHV lshift_ass_amg Sighandler_t pthread_getspecific svu_hash ISCX_invlist svu_nv sband_amg si_cxsubix lex_inpat last_lop tm_sec sockaddr_ax25 ptr_tbl_arena SVt_PVIO SVt_PVIV filtered Ilastfd _bcd2txt want_vtbl_collxfrm Bail Ieval_start ls_linestr PADNAMELIST SVt_PVCV PERL_PHASE_START __src xcv_hscxt any_u32 Perl_croak_nocontext _ctime_size repeat_ass_amg op_pmreplrootu Isavestack_max Ilocalpatches Isv_root SVt_PVLV p5rx op_next __saved_mask svu_rv copline sockaddr_eon any_op Icurstack SVt_PVMG Ipadix_floor si_status xpadl_arr h_addrtype _strerror_size Idelaymagic_euid bufend lex_inwhat any_pv atan2_amg xnv_nv sin_zero Iopfreehook ssize _protoent_ptr Iunitcheckav svu_uv PerlIOl sgt_amg to_hv_amg Isetlocale_bufsize protoent mg_len Imemory_debug_header SVt_IV Itop_env want_vtbl_sigelem netswap __blksize_t bcdn short unsigned int _spent_ptr bool__amg Itmps_stack yy_lexshared offs any_sv want_vtbl_substr Isv_undef Ipsig_name LEXSHARED clone_params perl_drand48_t Igensym Iregmatch_slab op_redoop rsfp _hostent_struct start_tmp xio_fmt_name svt_len cop_hints __len h_name Ierrors xpvlenu_len h_aliases _hostent_size op_pmreplstart hent_refcount saved_copy lex_sub_inwhat any_uv Itmps_floor Istrxfrm_is_behaved __wch xpadl_id dec_amg int_amg Ibasetime Iop_mask Isighandlerp unreferenced Isignalhook xpadnl_refcnt loceol IUpperLatin1 xio_ofp __value _hostent_buffer cop_seq multi_start op_pmreplroot SVt_NV IDBtrace maxlen pre_prefix op_targ Ibeginav je_ret resume_state is_ipv4to6 Isv_consts pw_dir lex_casestack op_lastop Isub_generation blku_eval float want_vtbl_isaelem __count unsigned char si_cxmax multi_open Perl_gimme_V _kill st_rdev LOOP ILB_invlist SVt_PV want_vtbl_dbline REENTR Imess_sv Iglobalstash Imin_intro_pending expect oldloc Icollxfrm_base want_vtbl_envelem copy_amg Iutf8_perl_idcont cx_blk Istatname RETVAL modulo_amg xnv_u __uid_t sin6_scope_id blku_gimme XSUBADDR_t st_ctim recheck_utf8_validity Iutf8_tofold xcv_root ISB_invlist block_format in_addr_t op_sibparent XS_NetAddr__IP__Util_ipanyto6 old_namesv log_amg xpadn_type_u IAssigned_invlist peep_t Iinternal_random_state Isv_no minlen __off_t perl_phase Iin_clean_objs is_mask4to6 Isv_zero cp128 PERL_PHASE_DESTRUCT in_pod Perl_stack_grow gp_io Imultideref_pc Iors_sv string_amg xpadn_protocv Ievalseq Iunlockhook regexp_engine mg_flags subtr_amg Icurstash gr_passwd _gmtime_struct gr_gid want_vtbl_checkcall si_overrun __clock_t SVt_NULL ls_bufptr Ibeginav_save __uint32_t Iorigfilename xmg_hash_index last_lop_op cop_warnings Icop_seqmax op_pmtargetgv form_lex_state XS_NetAddr__IP__Util_bcd2bin Istatgv Idestroyhook st_blocks max_offset GNU C17 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -march=x86-64-v2 -mtune=generic -g -g -O2 -flto -ffat-lto-objects -fexceptions -fstack-protector-strong -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection=full -fwrapv -fno-strict-aliasing -fPIC -fplugin=annobin sbu_m sbu_s save_curlyx Icomppad sub_no_recover lex_dojoin xmg_u gp_cvgen xcv_file SVt_PVNV itervar_u gp_flags xiou_dirp _servent_buffer paren_names Iregistered_mros si_uid pw_passwd is_ipanyto6 Iin_some_fold sqrt_amg lex_allbrackets opval Icurcopdb block_sub pos_magic gp_file_hek sv_refcnt sockaddr_in6 __nlink_t tbl_ary sband_ass_amg xav_alloc si_fd nparens xpadn_refcnt scmp_amg Ieval_root old_eval_root named_buff_iter st_gid Idowarn yychar Ifirstgv rshift_amg _countbits mg_moremagic op_pmoffset op_pmstashoff Inumeric_underlying_is_standard PERL_SI MGVTBL op_static MAGIC Perl_sv_newmortal Itmps_max want_vtbl_pack sockaddr_ipx Ithreadhook Badigits blku_givwhen gr_name op_type Iutf8_perl_idstart sublen blku_oldmarksp xivu_iv _netent_ptr want_vtbl_regexp Ipadname_undef preambling adder128 Inumeric_underlying _upper cx_u output IDBcv trie Ilockhook __ctype_toupper _xnvu xio_lines_left compflags sockaddr_iso want_vtbl_utf8 Iin_load_module xio_page sigjmp_buf pow_amg want_vtbl_hints tm_isdst div_amg Ilaststype __ctype_b h_addr_list Iutf8_charname_continue in_my_stash want_vtbl_regdata xpadn_len _strerror_buffer add_ass_amg dummy Iunitcheckav_save si_stime u_int32_t lastcloseparen short int ifmatch Idumpindent Ioldname preambled op_code_list xhv_keys itersave sbxor_ass_amg IAboveLatin1 Iutf8_mark _servent_size si_signo IDBgv __names sv_any blk_u xcv_start accepted gvval IWB_invlist olddepth Iutf8cache _localtime_struct _bounds prev_eval Ipadix defsv_save want_vtbl_lvref _netent_buffer xcv_stash YYSTYPE xcv_gv cop_hints_hash Icustom_op_names lex_sub_repl sle_amg xpadn_high re_scream_pos_data hek_hash _ttyname_buffer Iknown_layers _netent_errno Itainting Icurcop Istack_sp __ssize_t any_bool regmatch_info_aux PERL_PHASE_END Icollation_standard __glibc_reserved want_vtbl_taint lex_defer xmg_stash Iorigalen sbu_maxiters sockaddr Idebug __int32_t refcounted_he Icurpad printb128 __time_t st_mtim want_vtbl_uvar s_proto sbu_targ boot_NetAddr__IP__Util __dest logical Iforkprocess digit lex_brackets xio_top_gv Iutf8_tolower blku_oldcop Icurstackinfo Istart_env lex_fakeeof lex_sub_op stashes Istashcache xnv_lines mult_amg want_vtbl_packelem p_aliases _netent_struct in_my next_off xivu_uv sin_port Imodglobal sockaddr_at regmatch_info_aux_eval xcv_start_u want_vtbl_env basesp Igeneration IGCB_invlist Istrtab xpadl_outid xpadn_low block_givwhen regexp_paren_pair crypt_data pprivate cv_flags_t cur_top_env xpadn_typestash Iin_utf8_COLLATE_locale state_u PERL_PHASE_RUN _sigfault op_spare lex_op st_ino cop_features __pid_t parsed_sub op_last proto_perl want_vtbl_regdatum xio_type yylval sp_inact sockaddr_dl xav_fill hent_val Iorigenviron Idelaymagic_egid gp_av ftest_amg binmsk scream_olds mg_ptr maxpos sa_family ptr_tbl Inumeric_name lazyiv _sifields want_vtbl_pos SVt_REGEXP Ipsig_ptr gp_cv xgv_stash netent tv_sec tm_year blku_u16 Iprofiledata sbor_amg __sigset_t gp_line Imainstack Icurpm op_pmflags st_blksize xpadn_ourstash is_bcdn2bin ptr_tbl_ent _hostent_errno op_slabbed scompl_amg Isubline Iargvoutgv Iwatchaddr Idefgv hek_key PerlExitListEntry xio_bottom_name gp_form Perl_newXS_flags Ireentrant_buffer hent_next check_ix op_flags Iunsafe tm_wday Ihintgv sockaddr_in __jmp_buf IDBsignal Iutf8_charname_begin Ilanginfo_bufsize blku_format __dirstream sin_addr IXpv Iregex_padav blku_loop cache_offset wanted pw_uid _timer Istrxfrm_NUL_replacement IInMultiCharFold je_old_stack_hwm sig_elems bcd8 gr_mem Ixsubfilename gp_hv Ipad_reset_pending dfoutgv _sigchld xcv_depth Itaint_warn Imbrtowc_ps pw_shell si_next want_vtbl_nonelem _syscall Iexitlist Ilanginfo_buf Isubname any_i32 Ihv_fetch_ent_mh UNOP_AUX_item svt_dup xcv_flags Perl_sv_setiv_mg Inumeric_radix_sv globhook_t xcv_outside_seq Isplitstr xcv_hek svt_free sockaddr_ns long long unsigned int si_addr Ibody_arenas checkstr _grent_size addercon SVt_INVLIST want_vtbl_mglob Isortcop sin_family Isignals sbu_type si_pid mg_private dupe je_buf lazysv Iwcrtomb_ps Itoptarget Istrxfrm_max_cp Ierrgv Perl_sv_2pv_flags inc_amg _128x2 svt_clear PERL_PHASE_CHECK nexttoke Itmps_ix Isig_pending substrs any_svp intflags destroyable_proc_t Ifdpid xpadlarr_alloc ival any_dxptr n_net to_sv_amg Perl_croak_xs_usage op_pmtargetoff Icollation_name Iefloatbuf to_cv_amg extendmask4 magic_vtable_max _pwent_size oldval any_long xiou_any ITR_SPECIAL_HANDLING_UTF8 lshift_amg Iexit_flags c1_utf8 repeat_amg Icurlocales Iglobhook sin6_port dchar xio_top_name IPrivate_Use modulo_ass_amg Iptr_table Icolorset __jmpbuf Ifilemode __dev_t Iexitlistlen sockaddr_un numer_amg op_folded Idelaymagic Imarkstack_ptr block is_add128 pw_gid tm_gmtoff prev_yes_state s_name _protoent_struct op_comp gp_sv svu_array whilem IInBitmap mother_re __val n_aliases _sigsys is_bcd2bin is_maskanyto6 is_comp128 a128 extflags xio_fmt_gv xpadn_gen cop_file Icurstname cx_subst __u6_addr16 Isv_count svt_set Idefstash Itainted Ibodytarget oldoldbufptr xav_max xiv_u _protoent_buffer st_mode savearray _xivu leave_op Iutf8_xidstart is_ipv6to4 re_eval_start perl_debug_pad Istack_max st_dev hasdigits __u6_addr32 je_prev want_vtbl_sv Iclocktick Perl_sv_2iv_flags __syscall_slong_t IXPosix_ptrs IDBsub spwd Iutf8_idstart je_mustcatch numbered_buff_LENGTH bcdstuff yy_parser block_loop op_savefree Iscopestack Iformtarget pad_offset s_aliases lastcp Iconstpadix multi_close stat herelines Imy_cxt_list IPosix_ptrs xivu_namehek tmpc _ttyname_size sin6_addr Iwatchok p_proto Perl_sv_2mortal want_vtbl_isa svt_copy xnv_bm_tail sival_ptr mark_loc si_utime xpvav Isrand_called regexp_amg __mode_t sp_flag perl_key Ireplgv sa_data Ibreakable_sub_gen XS_NetAddr__IP__Util_notcontiguous rsfp_filters Iin_eval suboffset __sigval_t _servent_ptr lex_re_reparsing Iutf8_toupper linestart sig_optelems PERL_PHASE_INIT old_cxsubix Icv_has_eval mg_type xpvcv Isetlocale_buf numbered_buff_FETCH Irandom_state Iscopestack_name si_band xpadn_pv Icomppad_name_floor Idelaymagic_uid Iwarnhook _xmgu _sigpoll slt_amg xio_dirpu bcd2p Iin_utf8_turkic_locale cur_text blku_oldpm Imain_cv <artificial> /home/.cpan/build/NetAddr-IP-4.079-0/Lite/Util /usr/include/bits /usr/lib64/perl5/CORE Util.xs stdio2.h Util.c inline.h string_fortified.h <built-in> struct_stat.h intrpvar.h av.h __locale_t.h iperlsys.h handy.h perlvars.h sockaddr.h grp.h struct___jmp_buf_tag.h stdint-intn.h dirent.h __sigval_t.h util.h overload.h pwd.h /usr/lib/gcc/x86_64-redhat-linux/11/include crypt.h gv.h netdb.h pthread.h mg.h perlio.h /usr/include struct_timespec.h time_t.h regexp.h cv.h pthreadtypes.h cop.h hv.h stdint-uintn.h pad.h parser.h /usr/include/netinet __sigset_t.h reentr.h stdio2-decl.h proto.h perly.h mg_vtable.h socket.h sv.h /usr/include/sys __mbstate_t.h siginfo_t.h /usr/include/bits/types stddef.h struct_tm.h perl.h setjmp.h shadow.h in.h �! U��U� 0��V *��8 3=��8 FP��8 Yc��8 lv��8 ���8 ����8 �� P � ����8 ����8 ����8 ����8 ����8 ����8 ����8 ����8 ����8 ��T��t���t���t � ��T��t���t���t � ��U���U� ��T��_���T���_ ��V��v���V��V��V ��\��|���^��P��|� ��| $ &3$p"���| $ &3$p "� ��v | $ &3$ p 8� ��]��]��]��] ��P �� �� ��^��^��^ ��U��U��U��U ��Q��Q ��1���1� ��U�� �U� ��T�� _� � �T�� � _ �� V� � v�� � V� � V� � V� � V ��\��|���^��P� � |� ��| $ &3$p"���| $ &3$p "� ��v | $ &3$ p 8� �� ]� � ]� � ]� � ] ��P �� � � �� ^� � ^ � � ^� � U� � ^� � U� � ^� � ^� � ^ � � Q� � Q � � 1�� � 1� � � U� � u�� � u�� � u �� � u� � � R� � P� � P � � 3�� � xt2%#�� � xt2%#�� � xx2%#�� � xt2%#� � � u x "� � 0�� � t x "�y ����+��� � !t x "�t x "�u x "�" ����+��� � !t x "�t x "�u x "�" ����+�� � � t x "� � t x " � � Y� � t x "�u x "�"�� � t x "�u x "�"� � � U� � �U� � � T� � �T� � � Q� � �Q� � � R� � P� � t � � �R� � � @K$ �� � P� � �RO&� � � U� � u�� � u�� � u �� � u� ��U���U� ��T��]���T���] ��V��^��^ ��^��~���\��~���~���~���~� ��~ $ &3$p"���~ $ &3$p "� ��v ~ $ &3$ p 8� ��P ��\��\��\ ��U��U �� 8p ��Q ��\��\��\ ��V��V ��\��\��\ ��1���1� ��U��u���u���u � ��Q��r p ���p r "� ��U��p 2$u "��� p 2$u "#��� p2$u "#� ��T��p 2$t "��� p 2$t "#��� p2$t "#� ��U���U� ��T ��U��u|���U ��U���U� ��T��_���T���_���T� ��\��]��]��}���\��]��|���\��\��\ ��V��v���^��P��v���v� ��v $ &3$p"���v $ &3$p "���Q��Q ��| v $ &3$ p 8� ��R����~����~����~��R����~ ��P �� �� ��_��_ ��V��V ��_��T��_��_��_ ��V��V��V��V ��Q��Q ��P ��q 3��� p#"�3� ��P ��P��q( ��2� ��1� ��U��!�U� ��T�� ^� �!�T��!�!^�!�!�T� �� \� � |�� � |�� � \� � |�� �!\�!�!\�!�!\ ��V�� v�� � ]� � P� � v�� � v��!�!v� ��v $ &3$p"���v $ &3$p "��� Q�!�!Q ��| v $ &3$ p 8� ��P � � ^� �!^�!�!^ � � _� � _� �!_�!�!_ � � T�!�!T � � P � � q 3�� � p#"�3� � � P � � P� � q( � � 2� � � 1� �!�!U�!�"S�"�"�U� �!�!U�!�"S�"�"�U� �!�!u��!�"s��"�"�U#� �!�!u��!�"s��"�"�U#� �!�!u ��!�"s ��"�"�U# � �!�" ���"�"X�"�"x��"�"X �"�#U�#�(�U� �"�#T�#�$^�$�&�T��&�'^�'�'�T��'�(^ �#�#\�#�%_�%�%��&�&��&�&\�&�&|��&�'_�'�'|x��'�'��'�(\�(�(_ �#�#V�#�#v��#�#]�#�#P�'�(v� �#�#v $ &3$p"��#�#v $ &3$p "� �#�#| v $ &3$ p 8� �#�#P �#�$V�&�'V�(�(V �$�$T�(�(T �$�$P�$�%V�&�&V�'�'V �%�%P �%�%q 3��%�% p#"�3� �%�%P �%�%P�%�%q( �&�&2� �%�%1� �(�(U�(�(u� �(�(P�(�(p��(�(P�(�(p��(�(P �(�(T�(�(r @K$ ��(�(T �(�(0��(�(T�(�(T �)�)U�)�0�U� �)�)T�)�*V�*�/�T��/�/V�/�0�T� �)�*_�*�+V�+�+v��,�.V�.�/V�/�/V�/�/_�/�0V �)�)]�)�*Q�*�*���*�+}��,�,}��,�,���,�,}��,�-}��-�-}��-�.}��.�.}��/�/}��/�/Q�/�/���/�0}��0�0}� �)�+\�,�-\�-�-\�-�.\�/�/\�/�0\ �)�,^�,�/^�0�0^�0�0^ �)�)P �)�*P�*�*v �/�/P �*�*T�,�,T�,�,�� �*�+X�,�,X�,�,X�,�-���-�-���-�.X�.�.���/�/���/�0X�0�0X �0�0Q�0�0Q�0�0Q �-�-\�.�.\�.�.|��.�/\�0�0\ �*�+@� �*�+X �*�+����+�+] �-�-@� �-�-X �-�-����-�-] �+�,1��/�/1� �0�0U�0�1V�1�1Q�1�1�U� �0�0T�0�1\�1�1T�1�1�T� �0�0U�0�1V�1�1Q�1�1�U� �0�0T�0�1\�1�1T�1�1�T� �1�1U�1�1\�1�1Q�1�1�U� �1�1T�1�1V�1�1T�1�1�T� �1�1Q�1�1�Q� �1�1U�1�1\�1�1Q�1�1�U� �1�1T�1�1V�1�1T�1�1�T� �2�2U�2�3�U� �2�2T�2�2p��2�3�T� �2�2Q�2�3zh��3�3�Q� �2�2t��2�2P�2�2u �U ��2�2u �U � �2�2C��2�3X �2�21��2�2Y�2�2Y�2�31��3�3Y �2�2P�2�2P�2�2p 4$� �2�2q��2�3Z�3�3�Q#� �2�2U�2�3�U� �2�2D� �2�20� �2�2Z �3�3U�3�3^�3�5�U� �3�3T�3�3U�3�5�T� �3�3Q�3�3T�3�5�Q� �3�3R�3�5�R� �3�30��3�3v | "1 ��3�3V�3�3Q�4�4V�5�5Q �3�30��3�3_�3�31��3�4_�4�41��4�5_�5�5_ �3�3|��3�3\�3�40��4�4|��4�41��4�5|��5�5|� �3�4P �3�5^�5�5^ �3�3@� �3�30� �3�3T �3�3@� �3�30� �3�3Q �5�6U�6�=�U� �5�6T�6�6V�6�;�T��;�;V�;�=�T� �6�6]�6�9V�9�9v��9�;V�;�;V�;�;]�;�<V�<�=V �6�6\�6�6|��6�7^�7�7P�7�7|��7�8|��9�:|��:�:|��:�;|��;�<|��<�=|� �6�6| $ &3$p"��6�6| $ &3$p "��6�6P �6�9_�9�=_ �6�6P�6�6v #(�6�9��~�9�;��~�;�;P�;�<��~�<�=��~ �6�6P �6�6v �6�6�T�;�;v �7�7]�7�7 | $ &3$q "�9�:] �7�9]�:�;]�;�=] �:�:P�<�=P�=�=R�=�=P �<�<��~�<�<P�<�=Q�=�=P�=�=Q �9�91��<�<1� �=�>U�>�?^�?�?�U� �=�>T�>�?]�?�?X��?�?��H � �>�>U�>�?Q �>�>Q �>�?R �>�>x } ( 2%# $ $} "#�>�>x } ( 2%# $ $} "#�>�>P�>�>Q�>�?P �=�>0��>�>Y�>�>Q�>�>Y�>�?Q�?�?Q �?�? ~ q "����?�?\ �=�=0��=�>[�?�?[�?�?0��?�? �� �=�=0��=�?V�?�?v��?�?V �>�>4��>�> x } ( 2%#��>�> x } ( 2%#��>�> x } $ 2%#��>�> x } ( 2%#� �>�>8t ��>�>9t ��>�?8t � �=�=0��=�>�s ��?�?�s ��?�?�s � �=�=D� �=�=0� �=�=P �?�?U�?�@Z �?�?T�?�@[ �?�@p 4%��@�@Y�@�@p 4%��@�@p ?� �?�@P �?�?0��?�?R�?�?r��?�@R �?�?0��?�?U�?�@X�@�@U�@�@X �@�AU�A�F�U� �@�AT�A�B_�B�C�T��C�C_�C�D�T��D�E_�E�E�T��E�F_�F�F�T��F�F_ �A�CV�C�Cv��C�EV�E�EV�E�FV�F�FV�F�FV �A�A\�A�A|��A�B^�B�BP�F�F|� �A�A| $ &3$p"��A�A| $ &3$p "� �A�Av | $ &3$ p 8� �A�B]�C�D]�E�F]�F�F] �A�AP �A�A �F�F �B�B^�D�D^ �B�C^�C�D^�D�F^�F�F^ �C�C1��F�F1� �G�GU�G�N�U� �G�GT�G�N�T� �G�GP�G�NV�N�NT �H�HP�H�HP�H�HP�I�IP�I�IP�J�JP�K�KP�K�KP�K�KP�L�LP�L�LP�M�MP�M�MP�N�NP�N�NP �H�HP �H�HP �H�HP �I�IP �I�IP �J�JP �K�KP �K�KP �K�KP �L�LP �L�LP �M�MP �M�MP �N�NP �N�NP r ������ ���� �������� ���� ���� ���� � � � � ���� ���� ������ ���� ���������� ���� ���� � � � � � � � �! � � � � �#�#�#�# �#�#�#�%�&�'�(�( �&�&�&�& �)�)�)�)�)�) �*�*�*�*�*�+�,�/�/�0 �2�2�2�2�2�2�2�2 �3�3�3�3�3�3 �6�6�6�6 �6�6�6�9�9�;�;�<�<�= �=�=�=�=�=�=�=�=�=�> �A�A�A�A �A�A�A�C�C�F�F�F �G�G�G�N�N�N �H�H�H�H �H�H�H�H �H�H�H�H �I�I�I�I �I�I�I�I �J�J�J�J �K�K�K�K �K�K�K�K �K�K�K�K �L�L�L�L �L�L�L�L �M�M�M�M �M�M�M�M �N�N�N�N �N�N�N�N � � � � � � � P" p$ �L P �T �U @l Hl Pl Xl Hn p hp p� ! " # � p$ �$ ! �$ 7 hp C Hl j % v @l � � �& � ) t � 0, � �. � �2 P ' �6 � J �9 � g @ � � �E � � �Z � �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 �8 � � �L � Pl � �8 � Xl � �T � hp � Hn E � 1 E Xp R `p ] P. e u � , * � � 0% � � � p � (p � @p $ / 0p : Hp D V j �= \ r � � �H � � p � �C � p � �+ 6 � � �+ � � 6 n p. " % 7 Pp B p D �> M N �. ! V �& b `9 E i �+ u p � 8p � � � 0> � � �= > � � " � � �& crtstuff.c deregister_tm_clones __do_global_dtors_aux completed.0 __do_global_dtors_aux_fini_array_entry frame_dummy __frame_dummy_init_array_entry XS_NetAddr__IP__Util_ipv4to6 XS_NetAddr__IP__Util_ipanyto6 XS_NetAddr__IP__Util_hasbits XS_NetAddr__IP__Util_add128 XS_NetAddr__IP__Util_addconst XS_NetAddr__IP__Util_notcontiguous XS_NetAddr__IP__Util_comp128 XS_NetAddr__IP__Util_bcd2bin XS_NetAddr__IP__Util_bin2bcd __FRAME_END__ _fini __dso_handle Util.c.e14dc308 _DYNAMIC __GNU_EH_FRAME_HDR __TMC_END__ _GLOBAL_OFFSET_TABLE_ _init _bcd2txt Perl_sv_2iv_flags putchar@GLIBC_2.2.5 is_shiftleft is_ipv6to4 _isipv4 Perl_stack_grow _ITM_deregisterTMCloneTable have128 puts@GLIBC_2.2.5 printb128 pthread_getspecific@GLIBC_2.34 is_mask4to6 is_simple_pack __stack_chk_fail@GLIBC_2.4 is_add128 Perl_sv_setiv_mg PL_thr_key is_bcd2bin is_sub128 Perl_sv_2pv_flags Perl_xs_boot_epilog _128x10 __gmon_start__ Perl_croak_xs_usage boot_NetAddr__IP__Util is_ipv4to6 is_maskanyto6 adder128 Perl_croak_nocontext addercon Perl_newXS_flags Perl_sv_2mortal _countbits netswap_copy Perl_xs_handshake is_comp128 is_bcdn2bin netswap extendmask4 _128x2 fastcomp128 is_ipanyto6 is_hasbits _ITM_registerTMCloneTable Perl_newSViv _128x10plusbcd Perl_newSVpvn __cxa_finalize@GLIBC_2.2.5 Perl_sv_newmortal extendipv4 .symtab .strtab .shstrtab .note.gnu.property .note.gnu.build-id .gnu.hash .dynsym .dynstr .gnu.version .gnu.version_r .rela.dyn .rela.plt .init .plt.sec .text .fini .rodata .eh_frame_hdr .eh_frame .init_array .fini_array .data.rel.ro .dynamic .got .data .bss .comment .annobin.notes .gnu.build.attributes .debug_aranges .debug_info .debug_abbrev .debug_line .debug_str .debug_line_str .debug_loclists .debug_rnglists � � . � � $ A ���o � � � K � � ( S � [ ���o n h ���o � � @ w � � 0 � B � � 0 � � 0 � P" P" � p$ p$ &( � �L �L � 2 P P � � �T �T � � �U �U x � @l @\ � Hl H\ � Pl P\ � Xl X\ � � Hn H^ � � p ` h � hp h` 0 h` . 0 �` � p� a 2 @b 0 A pb 0� M � � [ � ! g 0 �. f9 r 0 h � � �j �! � z� v � � % � �� �� � PK � �[ ! arch/auto/NetAddr/IP/Util/.existsnu �[��� PK � �[)| 4i= i= lib/NetAddr/IP/UtilPP.pmnu ��6�$ #!/usr/bin/perl package NetAddr::IP::UtilPP; use strict; #use diagnostics; #use lib qw(blib lib); use AutoLoader qw(AUTOLOAD); use vars qw($VERSION @EXPORT_OK @ISA %EXPORT_TAGS); require Exporter; @ISA = qw(Exporter); $VERSION = do { my @r = (q$Revision: 1.9 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; @EXPORT_OK = qw( hasbits shiftleft addconst add128 sub128 notcontiguous ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 bin2bcd bcd2bin comp128 bin2bcdn bcdn2txt bcdn2bin simple_pack ); %EXPORT_TAGS = ( all => [@EXPORT_OK], ); sub DESTROY {}; 1; __END__ =head1 NAME NetAddr::IP::UtilPP -- pure Perl functions for NetAddr::IP::Util =head1 SYNOPSIS use NetAddr::IP::UtilPP qw( hasbits shiftleft addconst add128 sub128 notcontiguous ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 bin2bcd bcd2bin ); use NetAddr::IP::UtilPP qw(:all) $rv = hasbits($bits128); $bitsX2 = shiftleft($bits128,$n); $carry = addconst($ipv6naddr,$signed_32con); ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con); $carry = add128($ipv6naddr1,$ipv6naddr2); ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2); $carry = sub128($ipv6naddr1,$ipv6naddr2); ($spurious,$cidr) = notcontiguous($mask128); ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2); $ipv6naddr = ipv4to6($netaddr); $ipv6naddr = mask4to6($netaddr); $ipv6naddr = ipanyto6($netaddr); $ipv6naddr = maskanyto6($netaddr); $netaddr = ipv6to4($pv6naddr); $bcdtext = bin2bcd($bits128); $bits128 = bcd2bin($bcdtxt); =head1 DESCRIPTION B<NetAddr::IP::UtilPP> provides pure Perl functions for B<NetAddr::IP::Util> =over 4 =item * $rv = hasbits($bits128); This function returns true if there are one's present in the 128 bit string and false if all the bits are zero. i.e. if (hasbits($bits128)) { &do_something; } or if (hasbits($bits128 & $mask128) { &do_something; } This allows the implementation of logical functions of the form of: if ($bits128 & $mask128) { ... input: 128 bit IPv6 string returns: true if any bits are present =cut sub _deadlen { my($len,$should) = @_; $len *= 8; $should = 128 unless $should; my $sub = (caller(1))[3]; die "Bad argument length for $sub, is $len, should be $should"; } sub hasbits { _deadlen(length($_[0])) if length($_[0]) != 16; return 1 if vec($_[0],0,32); return 1 if vec($_[0],1,32); return 1 if vec($_[0],2,32); return 1 if vec($_[0],3,32); return 0; } #=item * $rv = isIPv4($bits128); # #This function returns true if there are no on bits present in the IPv6 #portion of the 128 bit string and false otherwise. # #=cut # #sub xisIPv4 { # _deadlen(length($_[0])) # if length($_[0]) != 16; # return 0 if vec($_[0],0,32); # return 0 if vec($_[0],1,32); # return 0 if vec($_[0],2,32); # return 1; #} =item * $bitsXn = shiftleft($bits128,$n); input: 128 bit string variable, number of shifts [optional] returns: bits X n shifts NOTE: input bits are returned if $n is not specified =cut # multiply x 2 # sub _128x2 { my $inp = shift; $$inp[0] = ($$inp[0] << 1 & 0xffffffff) + (($$inp[1] & 0x80000000) ? 1:0); $$inp[1] = ($$inp[1] << 1 & 0xffffffff) + (($$inp[2] & 0x80000000) ? 1:0); $$inp[2] = ($$inp[2] << 1 & 0xffffffff) + (($$inp[3] & 0x80000000) ? 1:0); $$inp[3] = $$inp[3] << 1 & 0xffffffff; } # multiply x 10 # sub _128x10 { my($a128p) = @_; _128x2($a128p); # x2 my @x2 = @$a128p; # save the x2 value _128x2($a128p); _128x2($a128p); # x8 _sa128($a128p,\@x2,0); # add for x10 } sub shiftleft { _deadlen(length($_[0])) if length($_[0]) != 16; my($bits,$shifts) = @_; return $bits unless $shifts; die "Bad arg value for ".__PACKAGE__.":shiftleft, length should be 0 thru 128" if $shifts < 0 || $shifts > 128; my @uint32t = unpack('N4',$bits); do { $bits = _128x2(\@uint32t); $shifts-- } while $shifts > 0; pack('N4',@uint32t); } sub slowadd128 { my @ua = unpack('N4',$_[0]); my @ub = unpack('N4',$_[1]); my $carry = _sa128(\@ua,\@ub,$_[2]); return ($carry,pack('N4',@ua)) if wantarray; return $carry; } sub _sa128 { my($uap,$ubp,$carry) = @_; if (($$uap[3] += $$ubp[3] + $carry) > 0xffffffff) { $$uap[3] -= 4294967296; # 0x1_00000000 $carry = 1; } else { $carry = 0; } if (($$uap[2] += $$ubp[2] + $carry) > 0xffffffff) { $$uap[2] -= 4294967296; $carry = 1; } else { $carry = 0; } if (($$uap[1] += $$ubp[1] + $carry) > 0xffffffff) { $$uap[1] -= 4294967296; $carry = 1; } else { $carry = 0; } if (($$uap[0] += $$ubp[0] + $carry) > 0xffffffff) { $$uap[0] -= 4294967296; $carry = 1; } else { $carry = 0; } $carry; } =item * addconst($ipv6naddr,$signed_32con); Add a signed constant to a 128 bit string variable. input: 128 bit IPv6 string, signed 32 bit integer returns: scalar carry array (carry, result) =cut sub addconst { my($a128,$const) = @_; _deadlen(length($a128)) if length($a128) != 16; unless ($const) { return (wantarray) ? ($const,$a128) : $const; } my $sign = ($const < 0) ? 0xffffffff : 0; my $b128 = pack('N4',$sign,$sign,$sign,$const); @_ = ($a128,$b128,0); # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &slowadd128; slowadd128(@_); } =item * add128($ipv6naddr1,$ipv6naddr2); Add two 128 bit string variables. input: 128 bit string var1, 128 bit string var2 returns: scalar carry array (carry, result) =cut sub add128 { my($a128,$b128) = @_; _deadlen(length($a128)) if length($a128) != 16; _deadlen(length($b128)) if length($b128) != 16; @_ = ($a128,$b128,0); # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &slowadd128; slowadd128(@_); } =item * sub128($ipv6naddr1,$ipv6naddr2); Subtract two 128 bit string variables. input: 128 bit string var1, 128 bit string var2 returns: scalar carry array (carry, result) Note: The carry from this operation is the result of adding the one's complement of ARG2 +1 to the ARG1. It is logically B<NOT borrow>. i.e. if ARG1 >= ARG2 then carry = 1 or if ARG1 < ARG2 then carry = 0 =cut sub sub128 { _deadlen(length($_[0])) if length($_[0]) != 16; _deadlen(length($_[1])) if length($_[1]) != 16; my $a128 = $_[0]; my $b128 = ~$_[1]; @_ = ($a128,$b128,1); # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &slowadd128; slowadd128(@_); } =item * ($spurious,$cidr) = notcontiguous($mask128); This function counts the bit positions remaining in the mask when the rightmost '0's are removed. input: 128 bit netmask returns true if there are spurious zero bits remaining in the mask, false if the mask is contiguous one's, 128 bit cidr =cut sub notcontiguous { _deadlen(length($_[0])) if length($_[0]) != 16; my @ua = unpack('N4', ~$_[0]); my $count; for ($count = 128;$count > 0; $count--) { last unless $ua[3] & 1; $ua[3] >>= 1; $ua[3] |= 0x80000000 if $ua[2] & 1; $ua[2] >>= 1; $ua[2] |= 0x80000000 if $ua[1] & 1; $ua[1] >>= 1; $ua[1] |= 0x80000000 if $ua[0] & 1; $ua[0] >>= 1; } my $spurious = $ua[0] | $ua[1] | $ua[2] | $ua[3]; return $spurious unless wantarray; return ($spurious,$count); } =item * $ipv6naddr = ipv4to6($netaddr); Convert an ipv4 network address into an ipv6 network address. input: 32 bit network address returns: 128 bit network address =cut sub ipv4to6 { _deadlen(length($_[0]),32) if length($_[0]) != 4; # return pack('L3H8',0,0,0,unpack('H8',$_[0])); return pack('L3a4',0,0,0,$_[0]); } =item * $ipv6naddr = mask4to6($netaddr); Convert an ipv4 netowrk address into an ipv6 network mask. input: 32 bit network/mask address returns: 128 bit network/mask address NOTE: returns the high 96 bits as one's =cut sub mask4to6 { _deadlen(length($_[0]),32) if length($_[0]) != 4; # return pack('L3H8',0xffffffff,0xffffffff,0xffffffff,unpack('H8',$_[0])); return pack('L3a4',0xffffffff,0xffffffff,0xffffffff,$_[0]); } =item * $ipv6naddr = ipanyto6($netaddr); Similar to ipv4to6 except that this function takes either an IPv4 or IPv6 input and always returns a 128 bit IPv6 network address. input: 32 or 128 bit network address returns: 128 bit network address =cut sub ipanyto6 { my $naddr = shift; my $len = length($naddr); return $naddr if $len == 16; # return pack('L3H8',0,0,0,unpack('H8',$naddr)) return pack('L3a4',0,0,0,$naddr) if $len == 4; _deadlen($len,'32 or 128'); } =item * $ipv6naddr = maskanyto6($netaddr); Similar to mask4to6 except that this function takes either an IPv4 or IPv6 netmask and always returns a 128 bit IPv6 netmask. input: 32 or 128 bit network mask returns: 128 bit network mask =cut sub maskanyto6 { my $naddr = shift; my $len = length($naddr); return $naddr if $len == 16; # return pack('L3H8',0xffffffff,0xffffffff,0xffffffff,unpack('H8',$naddr)) return pack('L3a4',0xffffffff,0xffffffff,0xffffffff,$naddr) if $len == 4; _deadlen($len,'32 or 128'); } =item * $netaddr = ipv6to4($pv6naddr); Truncate the upper 96 bits of a 128 bit address and return the lower 32 bits. Returns an IPv4 address as returned by inet_aton. input: 128 bit network address returns: 32 bit inet_aton network address =cut sub ipv6to4 { my $naddr = shift; _deadlen(length($naddr)) if length($naddr) != 16; @_ = unpack('L3H8',$naddr); return pack('H8',@{_}[3..10]); } =item * $bcdtext = bin2bcd($bits128); Convert a 128 bit binary string into binary coded decimal text digits. input: 128 bit string variable returns: string of bcd text digits =cut sub bin2bcd { _deadlen(length($_[0])) if length($_[0]) != 16; unpack("H40",&_bin2bcdn) =~ /^0*(.+)/; $1; } =item * $bits128 = bcd2bin($bcdtxt); Convert a bcd text string to 128 bit string variable input: string of bcd text digits returns: 128 bit string variable =cut sub bcd2bin { &_bcdcheck; # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &_bcd2bin; &_bcd2bin; } =pod =back =cut #=item * $onescomp = comp128($ipv6addr); # #This function is for testing, it is more efficient to use perl " ~ " #on the bit string directly. This interface to the B<C> routine is published for #module testing purposes because it is used internally in the B<sub128> routine. The #function is very fast, but calling if from perl directly is very slow. It is almost #33% faster to use B<sub128> than to do a 1's comp with perl and then call #B<add128>. In the PurePerl version, it is a call to # # sub {return ~ $_[0]}; # #=cut sub comp128 { _deadlen(length($_[0])) if length($_[0]) != 16; return ~ $_[0]; } #=item * $bcdpacked = bin2bcdn($bits128); # #Convert a 128 bit binary string into binary coded decimal digits. #This function is for testing only. # # input: 128 bit string variable # returns: string of packed decimal digits # # i.e. text = unpack("H*", $bcd); # #=cut sub bin2bcdn { _deadlen(length($_[0])) if length($_[0]) != 16; # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &_bin2bcdn; &_bin2bcdn; } sub _bin2bcdn { my($b128) = @_; my @binary = unpack('N4',$b128); my @nbcd = (0,0,0,0,0); # 5 - 32 bit registers my ($add3, $msk8, $bcd8, $carry, $tmp); my $j = 0; my $k = -1; my $binmsk = 0; foreach(0..127) { unless ($binmsk) { $binmsk = 0x80000000; $k++; } $carry = $binary[$k] & $binmsk; $binmsk >>= 1; next unless $carry || $j; # skip leading zeros foreach(4,3,2,1,0) { $bcd8 = $nbcd[$_]; $add3 = 3; $msk8 = 8; $j = 0; while ($j < 8) { $tmp = $bcd8 + $add3; if ($tmp & $msk8) { $bcd8 = $tmp; } $add3 <<= 4; $msk8 <<= 4; $j++; } $tmp = $bcd8 & 0x80000000; # propagate carry $bcd8 <<= 1; # x2 if ($carry) { $bcd8 += 1; } $nbcd[$_] = $bcd8; $carry = $tmp; } } pack('N5',@nbcd); } #=item * $bcdtext = bcdn2txt($bcdpacked); # #Convert a packed bcd string into text digits, suppress the leading zeros. #This function is for testing only. # # input: string of packed decimal digits # consisting of exactly 40 digits # returns: hexdecimal digits # #Similar to unpack("H*", $bcd); # #=cut sub bcdn2txt { die "Bad argument length for ".__PACKAGE__.":bcdn2txt, is ".(2 * length($_[0])).", should be exactly 40 digits" if length($_[0]) != 20; (unpack('H40',$_[0])) =~ /^0*(.+)/; $1; } #=item * $bits128 = bcdn2bin($bcdpacked,$ndigits); # # Convert a packed bcd string into a 128 bit string variable # # input: packed bcd string # number of digits in string # returns: 128 bit string variable # sub bcdn2bin { my($bcd,$dc) = @_; $dc = 0 unless $dc; die "Bad argument length for ".__PACKAGE__.":bcdn2txt, is ".(2 * length($bcd)).", should be 1 to 40 digits" if length($bcd) > 20; die "Bad digit count for ".__PACKAGE__.":bcdn2bin, is $dc, should be 1 to 40 digits" if $dc < 1 || $dc > 40; return _bcd2bin(unpack("H$dc",$bcd)); } sub _bcd2bin { my @bcd = split('',$_[0]); my @hbits = (0,0,0,0); my @digit = (0,0,0,0); my $found = 0; foreach(@bcd) { my $bcd = $_ & 0xf; # just the nibble unless ($found) { next unless $bcd; # skip leading zeros $found = 1; $hbits[3] = $bcd; # set the first digit, no x10 necessary next; } _128x10(\@hbits); $digit[3] = $bcd; _sa128(\@hbits,\@digit,0); } return pack('N4',@hbits); } #=item * $bcdpacked = simple_pack($bcdtext); # #Convert a numeric string into a packed bcd string, left fill with zeros #This function is for testing only. # # input: string of decimal digits # returns: string of packed decimal digits # #Similar to pack("H*", $bcdtext); # sub _bcdcheck { my($bcd) = @_;; my $sub = (caller(1))[3]; my $len = length($bcd); die "Bad bcd number length $_ ".__PACKAGE__.":simple_pack, should be 1 to 40 digits" if $len > 40 || $len < 1; die "Bad character in decimal input string '$1' for ".__PACKAGE__.":simple_pack" if $bcd =~ /(\D)/; } sub simple_pack { &_bcdcheck; my($bcd) = @_; while (length($bcd) < 40) { $bcd = '0'. $bcd; } return pack('H40',$bcd); } =head1 EXPORT_OK hasbits shiftleft addconst add128 sub128 notcontiguous ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 bin2bcd bcd2bin comp128 bin2bcdn bcdn2txt bcdn2bin simple_pack threads =head1 AUTHOR Michael Robinton E<lt>michael@bizsystems.comE<gt> =head1 COPYRIGHT Copyright 2003 - 2012, Michael Robinton E<lt>michael@bizsystems.comE<gt> All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or b) the "Artistic License" which comes with this distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA or visit their web page on the internet at: http://www.gnu.org/copyleft/gpl.html. =head1 AUTHOR Michael Robinton <michael@bizsystems.com> =cut 1; PK � �[ag�r�� �� lib/NetAddr/IP/Lite.pmnu ��6�$ #!/usr/bin/perl package NetAddr::IP::Lite; use Carp; use strict; #use diagnostics; #use warnings; use NetAddr::IP::InetBase qw( inet_any2n isIPv4 inet_n2dx inet_aton ipv6_aton ipv6_n2x fillIPv4 ); use NetAddr::IP::Util qw( addconst sub128 ipv6to4 notcontiguous shiftleft hasbits bin2bcd bcd2bin mask4to6 ipv4to6 naip_gethostbyname havegethostbyname2 ); use vars qw(@ISA @EXPORT_OK $VERSION $Accept_Binary_IP $Old_nth $NoFQDN $AUTOLOAD *Zero); $VERSION = do { my @r = (q$Revision: 1.57 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; require Exporter; @ISA = qw(Exporter); @EXPORT_OK = qw(Zeros Zero Ones V4mask V4net); # Set to true, to enable recognizing of ipV4 && ipV6 binary notation IP # addresses. Thanks to Steve Snodgrass for reporting. This can be done # at the time of use-ing the module. See docs for details. $Accept_Binary_IP = 0; $Old_nth = 0; *Zero = \&Zeros; =pod =encoding UTF-8 =head1 NAME NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets =head1 SYNOPSIS use NetAddr::IP::Lite qw( Zeros Ones V4mask V4net :aton DEPRECATED ! :old_nth :upper :lower :nofqdn ); my $ip = new NetAddr::IP::Lite '127.0.0.1'; or if your prefer my $ip = NetAddr::IP::Lite->new('127.0.0.1); or from a packed IPv4 address my $ip = new_from_aton NetAddr::IP::Lite (inet_aton('127.0.0.1')); or from an octal filtered IPv4 address my $ip = new_no NetAddr::IP::Lite '127.012.0.0'; print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ; if ($ip->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) { print "Is a loopback address\n"; } # This prints 127.0.0.1/32 print "You can also say $ip...\n"; The following four functions return ipV6 representations of: :: = Zeros(); FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones(); FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask(); ::FFFF:FFFF = V4net(); Will also return an ipV4 or ipV6 representation of a resolvable Fully Qualified Domanin Name (FQDN). =head1 INSTALLATION Un-tar the distribution in an appropriate directory and type: perl Makefile.PL make make test make install B<NetAddr::IP::Lite> depends on B<NetAddr::IP::Util> which installs by default with its primary functions compiled using Perl's XS extensions to build a 'C' library. If you do not have a 'C' complier available or would like the slower Pure Perl version for some other reason, then type: perl Makefile.PL -noxs make make test make install =head1 DESCRIPTION This module provides an object-oriented abstraction on top of IP addresses or IP subnets, that allows for easy manipulations. Most of the operations of NetAddr::IP are supported. This module will work with older versions of Perl and is compatible with Math::BigInt. * By default B<NetAddr::IP> functions and methods return string IPv6 addresses in uppercase. To change that to lowercase: NOTE: the AUGUST 2010 RFC5952 states: 4.3. Lowercase The characters "a", "b", "c", "d", "e", and "f" in an IPv6 address MUST be represented in lowercase. It is recommended that all NEW applications using NetAddr::IP::Lite be invoked as shown on the next line. use NetAddr::IP::Lite qw(:lower); * To ensure the current IPv6 string case behavior even if the default changes: use NetAddr::IP::Lite qw(:upper); The internal representation of all IP objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects may be freely mixed. The supported operations are described below: =cut # in the off chance that NetAddr::IP::Lite objects are created # and the caller later loads NetAddr::IP and expects to use # those objects, let the AUTOLOAD routine find and redirect # NetAddr::IP::Lite method and subroutine calls to NetAddr::IP. # my $parent = 'NetAddr::IP'; # test function # # input: subroutine name in NetAddr::IP # output: t/f if sub name exists in NetAddr::IP namespace # #sub sub_exists { # my $other = $parent .'::'; # return exists ${$other}{$_[0]}; #} sub DESTROY {}; sub AUTOLOAD { no strict; my ($pkg,$func) = ($AUTOLOAD =~ /(.*)::([^:]+)$/); my $other = $parent .'::'; if ($pkg =~ /^$other/o && exists ${$other}{$func}) { $other .= $func; goto &{$other}; } my @stack = caller(0); if ( $pkg eq ref $_[0] ) { $other = qq|Can't locate object method "$func" via|; } else { $other = qq|Undefined subroutine \&$AUTOLOAD not found in|; } die $other . qq| package "$parent" or "$pkg" (did you forgot to load a module?) at $stack[1] line $stack[2].\n|; } =head2 Overloaded Operators =cut # these really should be packed in Network Long order but since they are # symmetrical, that extra internal processing can be skipped my $_v4zero = pack('L',0); my $_zero = pack('L4',0,0,0,0); my $_ones = ~$_zero; my $_v4mask = pack('L4',0xffffffff,0xffffffff,0xffffffff,0); my $_v4net = ~ $_v4mask; my $_ipv4FFFF = pack('N4',0,0,0xffff,0); sub Zeros() { return $_zero; } sub Ones() { return $_ones; } sub V4mask() { return $_v4mask; } sub V4net() { return $_v4net; } ############################################# # These are the overload methods, placed here # for convenience. ############################################# use overload '+' => \&plus, '-' => \&minus, '++' => \&plusplus, '--' => \&minusminus, "=" => \©, '""' => sub { $_[0]->cidr(); }, 'eq' => sub { my $a = (UNIVERSAL::isa($_[0],__PACKAGE__)) ? $_[0]->cidr : $_[0]; my $b = (UNIVERSAL::isa($_[1],__PACKAGE__)) ? $_[1]->cidr : $_[1]; $a eq $b; }, 'ne' => sub { my $a = (UNIVERSAL::isa($_[0],__PACKAGE__)) ? $_[0]->cidr : $_[0]; my $b = (UNIVERSAL::isa($_[1],__PACKAGE__)) ? $_[1]->cidr : $_[1]; $a ne $b; }, '==' => sub { return 0 unless UNIVERSAL::isa($_[0],__PACKAGE__) && UNIVERSAL::isa($_[1],__PACKAGE__); $_[0]->cidr eq $_[1]->cidr; }, '!=' => sub { return 1 unless UNIVERSAL::isa($_[0],__PACKAGE__) && UNIVERSAL::isa($_[1],__PACKAGE__); $_[0]->cidr ne $_[1]->cidr; }, '>' => sub { return &comp_addr_mask > 0 ? 1 : 0; }, '<' => sub { return &comp_addr_mask < 0 ? 1 : 0; }, '>=' => sub { return &comp_addr_mask < 0 ? 0 : 1; }, '<=' => sub { return &comp_addr_mask > 0 ? 0 : 1; }, '<=>' => \&comp_addr_mask, 'cmp' => \&comp_addr_mask; sub comp_addr_mask { my($c,$rv) = sub128($_[0]->{addr},$_[1]->{addr}); return -1 unless $c; return 1 if hasbits($rv); ($c,$rv) = sub128($_[0]->{mask},$_[1]->{mask}); return -1 unless $c; return hasbits($rv) ? 1 : 0; } #sub comp_addr { # my($c,$rv) = sub128($_[0]->{addr},$_[1]->{addr}); # return -1 unless $c; # return hasbits($rv) ? 1 : 0; #} =pod =over =item B<Assignment (C<=>)> Has been optimized to copy one NetAddr::IP::Lite object to another very quickly. =item B<C<-E<gt>copy()>> The B<assignment (C<=>)> operation is only put in to operation when the copied object is further mutated by another overloaded operation. See L<overload> B<SPECIAL SYMBOLS FOR "use overload"> for details. B<C<-E<gt>copy()>> actually creates a new object when called. =cut sub copy { return _new($_[0],$_[0]->{addr}, $_[0]->{mask}); } =item B<Stringification> An object can be used just as a string. For instance, the following code my $ip = new NetAddr::IP::Lite '192.168.1.123'; print "$ip\n"; Will print the string 192.168.1.123/32. my $ip = new6 NetAddr::IP::Lite '192.168.1.123'; print "$ip\n"; Will print the string 0:0:0:0:0:0:C0A8:17B/128 =item B<Equality> You can test for equality with either C<eq>, C<ne>, C<==> or C<!=>. C<eq>, C<ne> allows the comparison with arbitrary strings as well as NetAddr::IP::Lite objects. The following example: if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8') { print "Yes\n"; } Will print out "Yes". Comparison with C<==> and C<!=> requires both operands to be NetAddr::IP::Lite objects. =item B<Comparison via E<gt>, E<lt>, E<gt>=, E<lt>=, E<lt>=E<gt> and C<cmp>> Internally, all network objects are represented in 128 bit format. The numeric representation of the network is compared through the corresponding operation. Comparisons are tried first on the address portion of the object and if that is equal then the NUMERIC cidr portion of the masks are compared. This leads to the counterintuitive result that /24 > /16 Comparison should not be done on netaddr objects with different CIDR as this may produce indeterminate - unexpected results, rather the determination of which netblock is larger or smaller should be done by comparing $ip1->masklen <=> $ip2->masklen =item B<Addition of a constant (C<+>)> Add a 32 bit signed constant to the address part of a NetAddr object. This operation changes the address part to point so many hosts above the current objects start address. For instance, this code: print NetAddr::IP::Lite->new('127.0.0.1/8') + 5; will output 127.0.0.6/8. The address will wrap around at the broadcast back to the network address. This code: print NetAddr::IP::Lite->new('10.0.0.1/24') + 255; outputs 10.0.0.0/24. Returns the the unchanged object when the constant is missing or out of range. 2147483647 <= constant >= -2147483648 =cut sub plus { my $ip = shift; my $const = shift; return $ip unless $const && $const < 2147483648 && $const > -2147483649; my $a = $ip->{addr}; my $m = $ip->{mask}; my $lo = $a & ~$m; my $hi = $a & $m; my $new = ((addconst($lo,$const))[1] & ~$m) | $hi; return _new($ip,$new,$m); } =item B<Subtraction of a constant (C<->)> The complement of the addition of a constant. =item B<Difference (C<->)> Returns the difference between the address parts of two NetAddr::IP::Lite objects address parts as a 32 bit signed number. Returns B<undef> if the difference is out of range. =cut my $_smsk = pack('L3N',0xffffffff,0xffffffff,0xffffffff,0x80000000); sub minus { my $ip = shift; my $arg = shift; unless (ref $arg) { return plus($ip, -$arg); } my($carry,$dif) = sub128($ip->{addr},$arg->{addr}); if ($carry) { # value is positive return undef if hasbits($dif & $_smsk); # all sign bits should be 0's return (unpack('L3N',$dif))[3]; } else { return undef if hasbits(($dif & $_smsk) ^ $_smsk); # sign is 1's return (unpack('L3N',$dif))[3] - 4294967296; } } # Auto-increment an object =item B<Auto-increment> Auto-incrementing a NetAddr::IP::Lite object causes the address part to be adjusted to the next host address within the subnet. It will wrap at the broadcast address and start again from the network address. =cut sub plusplus { my $ip = shift; my $a = $ip->{addr}; my $m = $ip->{mask}; my $lo = $a & ~ $m; my $hi = $a & $m; $ip->{addr} = ((addconst($lo,1))[1] & ~ $m) | $hi; return $ip; } =item B<Auto-decrement> Auto-decrementing a NetAddr::IP::Lite object performs exactly the opposite of auto-incrementing it, as you would expect. =cut sub minusminus { my $ip = shift; my $a = $ip->{addr}; my $m = $ip->{mask}; my $lo = $a & ~$m; my $hi = $a & $m; $ip->{addr} = ((addconst($lo,-1))[1] & ~$m) | $hi; return $ip; } ############################################# # End of the overload methods. ############################################# # Preloaded methods go here. # This is a variant to ->new() that # creates and blesses a new object # without the fancy parsing of # IP formats and shorthands. # return a blessed IP object without parsing # input: prototype, naddr, nmask # returns: blessed IP object # sub _new ($$$) { my $proto = shift; my $class = ref($proto) || die "reference required"; $proto = $proto->{isv6}; my $self = { addr => $_[0], mask => $_[1], isv6 => $proto, }; return bless $self, $class; } =pod =back =head2 Methods =over =item C<-E<gt>new([$addr, [ $mask|IPv6 ]])> =item C<-E<gt>new6([$addr, [ $mask]])> =item C<-E<gt>new6FFFF([$addr, [ $mask]])> =item C<-E<gt>new_no([$addr, [ $mask]])> =item C<-E<gt>new_from_aton($netaddr)> =item new_cis and new_cis6 are DEPRECATED =item C<-E<gt>new_cis("$addr $mask)> =item C<-E<gt>new_cis6("$addr $mask)> The first three methods create a new address with the supplied address in C<$addr> and an optional netmask C<$mask>, which can be omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses respectively. new6FFFF specifically returns an IPv4 address in IPv6 format according to RFC4291 new6 ::xxxx:xxxx new6FFFF ::FFFF:xxxx:xxxx The third method C<new_no> is exclusively for IPv4 addresses and filters improperly formatted dot quad strings for leading 0's that would normally be interpreted as octal format by NetAddr per the specifications for inet_aton. B<new_from_aton> takes a packed IPv4 address and assumes a /32 mask. This function replaces the DEPRECATED :aton functionality which is fundamentally broken. The last two methods B<new_cis> and B<new_cis6> differ from B<new> and B<new6> only in that they except the common Cisco address notation for address/mask pairs with a B<space> as a separator instead of a slash (/) These methods are DEPRECATED because the functionality is now included in the other "new" methods i.e. ->new_cis('1.2.3.0 24') or ->new_cis6('::1.2.3.0 120') C<-E<gt>new6> and C<-E<gt>new_cis6> mark the address as being in ipV6 address space even if the format would suggest otherwise. i.e. ->new6('1.2.3.4') will result in ::102:304 addresses submitted to ->new in ipV6 notation will remain in that notation permanently. i.e. ->new('::1.2.3.4') will result in ::102:304 whereas new('1.2.3.4') would print out as 1.2.3.4 See "STRINGIFICATION" below. C<$addr> can be almost anything that can be resolved to an IP address in all the notations I have seen over time. It can optionally contain the mask in CIDR notation. If the OPTIONAL perl module Socket6 is available in the local library it will autoload and ipV6 host6 names will be resolved as well as ipV4 hostnames. B<prefix> notation is understood, with the limitation that the range specified by the prefix must match with a valid subnet. Addresses in the same format returned by C<inet_aton> or C<gethostbyname> can also be understood, although no mask can be specified for them. The default is to not attempt to recognize this format, as it seems to be seldom used. ###### DEPRECATED, will be remove in version 5 ############ To accept addresses in that format, invoke the module as in use NetAddr::IP::Lite ':aton' ###### USE new_from_aton instead ########################## If called with no arguments, 'default' is assumed. If called with an empty string as the argument, returns 'undef' C<$addr> can be any of the following and possibly more... n.n n.n/mm n.n mm n.n.n n.n.n/mm n.n.n mm n.n.n.n n.n.n.n/mm 32 bit cidr notation n.n.n.n mm n.n.n.n/m.m.m.m n.n.n.n m.m.m.m loopback, localhost, broadcast, any, default x.x.x.x/host 0xABCDEF, 0b111111000101011110, (or a bcd number) a netaddr as returned by 'inet_aton' Any RFC1884 notation ::n.n.n.n ::n.n.n.n/mmm 128 bit cidr notation ::n.n.n.n/::m.m.m.m ::x:x ::x:x/mmm x:x:x:x:x:x:x:x x:x:x:x:x:x:x:x/mmm x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation loopback, localhost, unspecified, any, default ::x:x/host 0xABCDEF, 0b111111000101011110 within the limits of perl's number resolution 123456789012 a 'big' bcd number (bigger than perl likes) and Math::BigInt A Fully Qualified Domain Name which returns an ipV4 address or an ipV6 address, embodied in that order. This previously undocumented feature may be disabled with: use NetAddr::IP::Lite ':nofqdn'; If called with no arguments, 'default' is assumed. If called with and empty string as the argument, 'undef' is returned; =cut my $lbmask = inet_aton('255.0.0.0'); my $_p4broad = inet_any2n('255.255.255.255'); my $_p4loop = inet_any2n('127.0.0.1'); my $_p4mloop = inet_aton('255.0.0.0'); $_p4mloop = mask4to6($_p4mloop); my $_p6loop = inet_any2n('::1'); my %fip4 = ( default => Zeros, any => Zeros, broadcast => $_p4broad, loopback => $_p4loop, unspecified => undef, ); my %fip4m = ( default => Zeros, any => Zeros, broadcast => Ones, loopback => $_p4mloop, unspecified => undef, # not applicable for ipV4 host => Ones, ); my %fip6 = ( default => Zeros, any => Zeros, broadcast => undef, # not applicable for ipV6 loopback => $_p6loop, unspecified => Zeros, ); my %fip6m = ( default => Zeros, any => Zeros, broadcast => undef, # not applicable for ipV6 loopback => Ones, unspecified => Ones, host => Ones, ); my $ff000000 = pack('L3N',0xffffffff,0xffffffff,0xffffffff,0xFF000000); my $ffff0000 = pack('L3N',0xffffffff,0xffffffff,0xffffffff,0xFFFF0000); my $ffffff00 = pack('L3N',0xffffffff,0xffffffff,0xffffffff,0xFFFFFF00); sub _obits ($$) { my($lo,$hi) = @_; return 0xFF if $lo == $hi; return (~ ($hi ^ $lo)) & 0xFF; } sub new_no($;$$) { unshift @_, -1; goto &_xnew; } sub new($;$$) { unshift @_, 0; goto &_xnew; } sub new_from_aton($$) { my $proto = shift; my $class = ref $proto || $proto || __PACKAGE__; my $ip = shift; return undef unless defined $ip; my $addrlen = length($ip); return undef unless $addrlen == 4; my $self = { addr => ipv4to6($ip), mask => &Ones, isv6 => 0, }; return bless $self, $class; } sub new6($;$$) { unshift @_, 1; goto &_xnew; } sub new6FFFF($;$$) { my $ip = _xnew(1,@_); $ip->{addr} |= $_ipv4FFFF; return $ip; } sub new_cis($;$$) { my @in = @_; if ( $in[1] && $in[1] =~ m!^(.+)\s+(.+)$! ) { $in[1] = $1 .'/'. $2; } @_ = (0,@in); goto &_xnew; } sub new_cis6($;$$) { my @in = @_; if ( $in[1] && $in[1] =~ m!^(.+)\s+(.+)$! ) { $in[1] = $1 .'/'. $2; } @_ = (1,@in); goto &_xnew; } sub _no_octal { # $_[0] =~ m/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/; # return sprintf("%d.%d.%d.%d",$1,$2,$3,$4); (my $rv = $_[0]) =~ s#\b0*([1-9]\d*/?|0/?)#$1#g; # suppress leading zeros $rv; } sub _xnew($$;$$) { my $noctal = 0; my $isV6 = shift; if ($isV6 < 0) { # flag for no octal? $isV6 = 0; $noctal = 1; } my $proto = shift; my $class = ref $proto || $proto || __PACKAGE__; my $ip = shift; if ($ip && $noctal && $ip !~ m|(?:[^\s0123456789/. -])|) { # octal suppression required if not an IPv4 address $ip = _no_octal($ip); } # fix for bug #75976 return undef if defined $ip && $ip eq ''; $ip = 'default' unless defined $ip; $ip = _retMBIstring($ip) # treat as big bcd string if ref $ip && ref $ip eq 'Math::BigInt'; # can /CIDR notation my $hasmask = 1; my($mask,$tmp); # IP to lower case AFTER ref test for Math::BigInt. 'lc' strips blessing $ip = lc $ip; while (1) { # process IP's with no CIDR or that have the CIDR as part of the IP argument string unless (@_) { # if ($ip =~ m!^(.+)/(.+)$!) { if ($ip !~ /\D/) { # binary number notation $ip = bcd2bin($ip); $mask = Ones; last; } elsif ($ip =~ m!^([a-z0-9.:-]+)(?:/|\s+)([a-z0-9.:-]+)$! || $ip =~ m!^[\[]{1}([a-z0-9.:-]+)(?:/|\s+)([a-z0-9.:-]+)[\]]{1}$!) { $ip = $1; $mask = $2; } elsif (grep($ip eq $_,(qw(default any broadcast loopback unspecified)))) { $isV6 = 1 if $ip eq 'unspecified'; if ($isV6) { $mask = $fip6m{$ip}; return undef unless defined ($ip = $fip6{$ip}); } else { $mask = $fip4m{$ip}; return undef unless defined ($ip = $fip4{$ip}); } last; } } # process "ipv6" token and default IP's elsif (defined $_[0]) { if ($_[0] =~ /ipv6/i || $isV6) { if (grep($ip eq $_,(qw(default any loopback unspecified)))) { $mask = $fip6m{$ip}; $ip = $fip6{$ip}; last; } else { return undef unless $isV6; # add for ipv6 notation "12345, 1" } # $mask = lc $_[0]; # } else { # $mask = lc $_[0]; } # extract mask $mask = $_[0]; } ### ### process mask unless (defined $mask) { $hasmask = 0; $mask = 'host'; } # two kinds of IP's can turn on the isV6 flag # 1) big digits that are over the IPv4 boundry # 2) IPv6 IP syntax # # check these conditions and set isV6 as appropriate # my $try; $isV6 = 1 if # check big bcd and IPv6 rfc1884 ( $ip !~ /\D/ && # ip is all decimal (length($ip) > 3 || $ip > 255) && # exclude a single digit in the range of zero to 255, could be funny IPv4 ($try = bcd2bin($ip)) && ! isIPv4($try)) || # precedence so $try is not corrupted (index($ip,':') >= 0 && ($try = ipv6_aton($ip))); # fails if not an rfc1884 address # if either of the above conditions is true, $try contains the NetAddr 128 bit address # checkfor Math::BigInt mask $mask = _retMBIstring($mask) # treat as big bcd string if ref $mask && ref $mask eq 'Math::BigInt'; # MASK to lower case AFTER ref test for Math::BigInt, 'lc' strips blessing $mask = lc $mask; if ($mask !~ /\D/) { # bcd or CIDR notation my $isCIDR = length($mask) < 4 && $mask < 129; if ($isV6) { if ($isCIDR) { my($dq1,$dq2,$dq3,$dq4); if ($ip =~ /^(\d+)(?:|\.(\d+)(?:|\.(\d+)(?:|\.(\d+))))$/ && do {$dq1 = $1; $dq2 = $2 || 0; $dq3 = $3 || 0; $dq4 = $4 || 0; 1; } && $dq1 >= 0 && $dq1 < 256 && $dq2 >= 0 && $dq2 < 256 && $dq3 >= 0 && $dq3 < 256 && $dq4 >= 0 && $dq4 < 256 ) { # corner condition of IPv4 with isV6 $ip = join('.',$dq1,$dq2,$dq3,$dq4); $try = ipv4to6(inet_aton($ip)); if ($mask < 32) { $mask = shiftleft(Ones,32 -$mask); } elsif ($mask == 32) { $mask = Ones; } else { return undef; # undoubtably an error } } elsif ($mask < 128) { $mask = shiftleft(Ones,128 -$mask); # small cidr } else { $mask = Ones(); } } else { $mask = bcd2bin($mask); } } elsif ($isCIDR && $mask < 33) { # is V4 # if ($ip && $noctal && $ip !~ m|(?:[^\s0123456789.])|) { # octal suppression required if not an IPv4 address # $mask = _no_octal($mask); # } if ($mask < 32) { $mask = shiftleft(Ones,32 -$mask); } elsif ( $mask == 32) { $mask = Ones; } else { $mask = bcd2bin($mask); $mask |= $_v4mask; # v4 always } } else { # also V4 $mask = bcd2bin($mask); $mask |= $_v4mask; } if ($try) { # is a big number $ip = $try; last; } } elsif ($mask =~ m/^\d+\.\d+\.\d+\.\d+$/) { # ipv4 form of mask $mask = _no_octal($mask) if $noctal; # filter for octal return undef unless defined ($mask = inet_aton($mask)); $mask = mask4to6($mask); } elsif (grep($mask eq $_,qw(default any broadcast loopback unspecified host))) { if (index($ip,':') < 0 && ! $isV6) { return undef unless defined ($mask = $fip4m{$mask}); } else { return undef unless defined ($mask = $fip6m{$mask}); } } else { return undef unless defined ($mask = ipv6_aton($mask)); # try ipv6 form of mask } # process remaining IP's if (index($ip,':') < 0) { # ipv4 address if ($ip =~ m/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/) { ; # the common case } elsif (grep($ip eq $_,(qw(default any broadcast loopback)))) { return undef unless defined ($ip = $fip4{$ip}); last; } elsif ($ip =~ m/^(\d+)\.(\d+)$/) { $ip = ($hasmask) ? "${1}.${2}.0.0" : "${1}.0.0.${2}"; } elsif ($ip =~ m/^(\d+)\.(\d+)\.(\d+)$/) { $ip = ($hasmask) ? "${1}.${2}.${3}.0" : "${1}.${2}.0.${3}"; } elsif ($ip =~ /^(\d+)$/ && $hasmask && $1 >= 0 and $1 < 256) { # pure numeric $ip = sprintf("%d.0.0.0",$1); } # elsif ($ip =~ /^\d+$/ && !$hasmask) { # a big integer elsif ($ip =~ /^\d+$/ ) { # a big integer $ip = bcd2bin($ip); last; } # these next three might be broken??? but they have been in the code a long time and no one has complained elsif ($ip =~ /^0[xb]\d+$/ && $hasmask && (($tmp = eval "$ip") || 1) && $tmp >= 0 && $tmp < 256) { $ip = sprintf("%d.0.0.0",$tmp); } elsif ($ip =~ /^-?\d+$/) { $ip += 2 ** 32 if $ip < 0; $ip = pack('L3N',0,0,0,$ip); last; } elsif ($ip =~ /^-?0[xb]\d+$/) { $ip = eval "$ip"; $ip = pack('L3N',0,0,0,$ip); last; } # notations below include an implicit mask specification elsif ($ip =~ m/^(\d+)\.$/) { $ip = "${1}.0.0.0"; $mask = $ff000000; } elsif ($ip =~ m/^(\d+)\.(\d+)-(\d+)\.?$/ && $2 <= $3 && $3 < 256) { $ip = "${1}.${2}.0.0"; $mask = pack('L3C4',0xffffffff,0xffffffff,0xffffffff,255,_obits($2,$3),0,0); } elsif ($ip =~ m/^(\d+)-(\d+)\.?$/ and $1 <= $2 && $2 < 256) { $ip = "${1}.0.0.0"; $mask = pack('L3C4',0xffffffff,0xffffffff,0xffffffff,_obits($1,$2),0,0,0) } elsif ($ip =~ m/^(\d+)\.(\d+)\.$/) { $ip = "${1}.${2}.0.0"; $mask = $ffff0000; } elsif ($ip =~ m/^(\d+)\.(\d+)\.(\d+)-(\d+)\.?$/ && $3 <= $4 && $4 < 256) { $ip = "${1}.${2}.${3}.0"; $mask = pack('L3C4',0xffffffff,0xffffffff,0xffffffff,255,255,_obits($3,$4),0); } elsif ($ip =~ m/^(\d+)\.(\d+)\.(\d+)\.$/) { $ip = "${1}.${2}.${3}.0"; $mask = $ffffff00; } elsif ($ip =~ m/^(\d+)\.(\d+)\.(\d+)\.(\d+)-(\d+)$/ && $4 <= $5 && $5 < 256) { $ip = "${1}.${2}.${3}.${4}"; $mask = pack('L3C4',0xffffffff,0xffffffff,0xffffffff,255,255,255,_obits($4,$5)); } elsif ($ip =~ m/^(\d+\.\d+\.\d+\.\d+) \s*-\s*(\d+\.\d+\.\d+\.\d+)$/x) { # if ($noctal) { # return undef unless ($ip = inet_aton(_no_octal($1))); # return undef unless ($tmp = inet_aton(_no_octal($2))); # } else { return undef unless ($ip = inet_aton($1)); return undef unless ($tmp = inet_aton($2)); # } # check for left side greater than right side # save numeric difference in $mask return undef if ($tmp = unpack('N',$tmp) - unpack('N',$ip)) < 0; $ip = ipv4to6($ip); $tmp = pack('L3N',0,0,0,$tmp); $mask = ~$tmp; return undef if notcontiguous($mask); # check for non-aligned left side return undef if hasbits($ip & $tmp); last; } # check for resolvable IPv4 hosts elsif (! $NoFQDN && $ip !~ /[^a-zA-Z0-9\._-]/ && ($tmp = gethostbyname(fillIPv4($ip))) && $tmp ne $_v4zero && $tmp ne $_zero ) { $ip = ipv4to6($tmp); last; } # check for resolvable IPv6 hosts elsif (! $NoFQDN && $ip !~ /[^a-zA-Z0-9\._-]/ && havegethostbyname2() && ($tmp = naip_gethostbyname($ip))) { $ip = $tmp; $isV6 = 1; last; } elsif ($Accept_Binary_IP && ! $hasmask) { if (length($ip) == 4) { $ip = ipv4to6($ip); } elsif (length($ip) == 16) { $isV6 = 1; } else { return undef; } last; } else { return undef; } return undef unless defined ($ip = inet_aton($ip)); $ip = ipv4to6($ip); last; } ########## continuing else { # ipv6 address $isV6 = 1; $ip = $1 if $ip =~ /\[([^\]]+)\]/; # transform URI notation if (defined ($tmp = ipv6_aton($ip))) { $ip = $tmp; last; } last if grep($ip eq $_,(qw(default any loopback unspecified))) && defined ($ip = $fip6{$ip}); return undef; } } # end while (1) return undef if notcontiguous($mask); # invalid if not contiguous my $self = { addr => $ip, mask => $mask, isv6 => $isV6, }; return bless $self, $class; } =item C<-E<gt>broadcast()> Returns a new object referring to the broadcast address of a given subnet. The broadcast address has all ones in all the bit positions where the netmask has zero bits. This is normally used to address all the hosts in a given subnet. =cut sub broadcast ($) { my $ip = _new($_[0],$_[0]->{addr} | ~$_[0]->{mask},$_[0]->{mask}); $ip->{addr} &= V4net unless $ip->{isv6}; return $ip; } =item C<-E<gt>network()> Returns a new object referring to the network address of a given subnet. A network address has all zero bits where the bits of the netmask are zero. Normally this is used to refer to a subnet. =cut sub network ($) { return _new($_[0],$_[0]->{addr} & $_[0]->{mask},$_[0]->{mask}); } =item C<-E<gt>addr()> Returns a scalar with the address part of the object as an IPv4 or IPv6 text string as appropriate. This is useful for printing or for passing the address part of the NetAddr::IP::Lite object to other components that expect an IP address. If the object is an ipV6 address or was created using ->new6($ip) it will be reported in ipV6 hex format otherwise it will be reported in dot quad format only if it resides in ipV4 address space. =cut sub addr ($) { return ($_[0]->{isv6}) ? ipv6_n2x($_[0]->{addr}) : inet_n2dx($_[0]->{addr}); } =item C<-E<gt>mask()> Returns a scalar with the mask as an IPv4 or IPv6 text string as described above. =cut sub mask ($) { return ipv6_n2x($_[0]->{mask}) if $_[0]->{isv6}; my $mask = isIPv4($_[0]->{addr}) ? $_[0]->{mask} & V4net : $_[0]->{mask}; return inet_n2dx($mask); } =item C<-E<gt>masklen()> Returns a scalar the number of one bits in the mask. =cut sub masklen ($) { my $len = (notcontiguous($_[0]->{mask}))[1]; return 0 unless $len; return $len if $_[0]->{isv6}; return isIPv4($_[0]->{addr}) ? $len -96 : $len; } =item C<-E<gt>bits()> Returns the width of the address in bits. Normally 32 for v4 and 128 for v6. =cut sub bits { return $_[0]->{isv6} ? 128 : 32; } =item C<-E<gt>version()> Returns the version of the address or subnet. Currently this can be either 4 or 6. =cut sub version { my $self = shift; return $self->{isv6} ? 6 : 4; } =item C<-E<gt>cidr()> Returns a scalar with the address and mask in CIDR notation. A NetAddr::IP::Lite object I<stringifies> to the result of this function. (see comments about ->new6() and ->addr() for output formats) =cut sub cidr ($) { return $_[0]->addr . '/' . $_[0]->masklen; } =item C<-E<gt>aton()> Returns the address part of the NetAddr::IP::Lite object in the same format as the C<inet_aton()> or C<ipv6_aton> function respectively. If the object was created using ->new6($ip), the address returned will always be in ipV6 format, even for addresses in ipV4 address space. =cut sub aton { return $_[0]->{addr} if $_[0]->{isv6}; return isIPv4($_[0]->{addr}) ? ipv6to4($_[0]->{addr}) : $_[0]->{addr}; } =item C<-E<gt>range()> Returns a scalar with the base address and the broadcast address separated by a dash and spaces. This is called range notation. =cut sub range ($) { return $_[0]->network->addr . ' - ' . $_[0]->broadcast->addr; } =item C<-E<gt>numeric()> When called in a scalar context, will return a numeric representation of the address part of the IP address. When called in an array context, it returns a list of two elements. The first element is as described, the second element is the numeric representation of the netmask. This method is essential for serializing the representation of a subnet. =cut sub numeric ($) { if (wantarray) { if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) { return ( sprintf("%u",unpack('N',ipv6to4($_[0]->{addr}))), sprintf("%u",unpack('N',ipv6to4($_[0]->{mask})))); } else { return ( bin2bcd($_[0]->{addr}), bin2bcd($_[0]->{mask})); } } return (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) ? sprintf("%u",unpack('N',ipv6to4($_[0]->{addr}))) : bin2bcd($_[0]->{addr}); } =item C<-E<gt>bigint()> When called in a scalar context, will return a Math::BigInt representation of the address part of the IP address. When called in an array contest, it returns a list of two elements. The first element is as described, the second element is the Math::BigInt representation of the netmask. =cut my $biloaded; my $bi2strng; my $no_mbi_emu = 1; # function to force into test development mode # sub _force_bi_emu { undef $biloaded; undef $bi2strng; $no_mbi_emu = 0; print STDERR "\n\n\tWARNING: test development mode, this \tmessage SHOULD NEVER BE SEEN IN PRODUCTION! set my \$no_mbi_emu = 1 in t/bigint.t to remove this warning\n\n"; } # function to stringify various flavors of Math::BigInt objects # tests to see if the object is a hash or a signed scalar sub _bi_stfy { "$_[0]" =~ /(\d+)/; # stringify and remove '+' if present $1; } sub _fakebi2strg { ${$_[0]} =~ /(\d+)/; $1; } # fake new from bi string Math::BigInt 0.01 # sub _bi_fake { bless \('+'. $_[1]), 'Math::BigInt'; } # as of this writing there are three known flavors of Math::BigInt # v0.01 MBI::new returns a scalar ref # v1.?? - 1.69 CALC::_new takes a reference to a scalar, returns an array, MBI returns a hash ref # v1.70 and up CALC::_new takes a scalar, returns and array, MBI returns a hash ref sub _loadMBI { # load Math::BigInt on demand if (eval {$no_mbi_emu && require Math::BigInt}) { # any version should work, three known import Math::BigInt; $biloaded = \&Math::BigInt::new; $bi2strng = \&_bi_stfy; } else { $biloaded = \&_bi_fake; $bi2strng = \&_fakebi2strg; } } sub _retMBIstring { _loadMBI unless $biloaded; # load Math::BigInt on demand $bi2strng->(@_); } sub _biRef { _loadMBI unless $biloaded; # load Math::BigInt on demand $biloaded->('Math::BigInt',$_[0]); } sub bigint($) { my($addr,$mask); if (wantarray) { if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) { $addr = $_[0]->{addr} ? sprintf("%u",unpack('N',ipv6to4($_[0]->{addr}))) : 0; $mask = $_[0]->{mask} ? sprintf("%u",unpack('N',ipv6to4($_[0]->{mask}))) : 0; } else { $addr = $_[0]->{addr} ? bin2bcd($_[0]->{addr}) : 0; $mask = $_[0]->{mask} ? bin2bcd($_[0]->{mask}) : 0; } (_biRef($addr),_biRef($mask)); } else { # not wantarray if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) { $addr = $_[0]->{addr} ? sprintf("%u",unpack('N',ipv6to4($_[0]->{addr}))) : 0; } else { $addr = $_[0]->{addr} ? bin2bcd($_[0]->{addr}) : 0; } _biRef($addr); } } =item C<$me-E<gt>contains($other)> Returns true when C<$me> completely contains C<$other>. False is returned otherwise and C<undef> is returned if C<$me> and C<$other> are not both C<NetAddr::IP::Lite> objects. =cut sub contains ($$) { return within(@_[1,0]); } =item C<$me-E<gt>within($other)> The complement of C<-E<gt>contains()>. Returns true when C<$me> is completely contained within C<$other>, undef if C<$me> and C<$other> are not both C<NetAddr::IP::Lite> objects. =cut sub within ($$) { return 1 unless hasbits($_[1]->{mask}); # 0x0 contains everything my $netme = $_[0]->{addr} & $_[0]->{mask}; my $brdme = $_[0]->{addr} | ~ $_[0]->{mask}; my $neto = $_[1]->{addr} & $_[1]->{mask}; my $brdo = $_[1]->{addr} | ~ $_[1]->{mask}; return (sub128($netme,$neto) && sub128($brdo,$brdme)) ? 1 : 0; } =item C-E<gt>is_rfc1918()> Returns true when C<$me> is an RFC 1918 address. 10.0.0.0 - 10.255.255.255 (10/8 prefix) 172.16.0.0 - 172.31.255.255 (172.16/12 prefix) 192.168.0.0 - 192.168.255.255 (192.168/16 prefix) =cut my $ip_10 = NetAddr::IP::Lite->new('10.0.0.0/8'); my $ip_10n = $ip_10->{addr}; # already the right value my $ip_10b = $ip_10n | ~ $ip_10->{mask}; my $ip_172 = NetAddr::IP::Lite->new('172.16.0.0/12'); my $ip_172n = $ip_172->{addr}; # already the right value my $ip_172b = $ip_172n | ~ $ip_172->{mask}; my $ip_192 = NetAddr::IP::Lite->new('192.168.0.0/16'); my $ip_192n = $ip_192->{addr}; # already the right value my $ip_192b = $ip_192n | ~ $ip_192->{mask}; sub is_rfc1918 ($) { my $netme = $_[0]->{addr} & $_[0]->{mask}; my $brdme = $_[0]->{addr} | ~ $_[0]->{mask}; return 1 if (sub128($netme,$ip_10n) && sub128($ip_10b,$brdme)); return 1 if (sub128($netme,$ip_192n) && sub128($ip_192b,$brdme)); return (sub128($netme,$ip_172n) && sub128($ip_172b,$brdme)) ? 1 : 0; } =item C<-E<gt>is_local()> Returns true when C<$me> is a local network address. i.e. ipV4 127.0.0.0 - 127.255.255.255 or ipV6 === ::1 =cut my $_lclhost6 = NetAddr::IP::Lite->new('::1'); my $_lclnet = NetAddr::IP::Lite->new('127/8'); sub is_local ($) { return ($_[0]->{isv6}) ? $_[0] == $_lclhost6 : $_[0]->within($_lclnet); } =item C<-E<gt>first()> Returns a new object representing the first usable IP address within the subnet (ie, the first host address). =cut my $_cidr127 = pack('N4',0xffffffff,0xffffffff,0xffffffff,0xfffffffe); sub first ($) { if (hasbits($_[0]->{mask} ^ $_cidr127)) { return $_[0]->network + 1; } else { return $_[0]->network; } # return $_[0]->network + 1; } =item C<-E<gt>last()> Returns a new object representing the last usable IP address within the subnet (ie, one less than the broadcast address). =cut sub last ($) { if (hasbits($_[0]->{mask} ^ $_cidr127)) { return $_[0]->broadcast - 1; } else { return $_[0]->broadcast; } # return $_[0]->broadcast - 1; } =item C<-E<gt>nth($index)> Returns a new object representing the I<n>-th usable IP address within the subnet (ie, the I<n>-th host address). If no address is available (for example, when the network is too small for C<$index> hosts), C<undef> is returned. Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite implements C<-E<gt>nth($index)> and C<-E<gt>num()> exactly as the documentation states. Previous versions behaved slightly differently and not in a consistent manner. To use the old behavior for C<-E<gt>nth($index)> and C<-E<gt>num()>: use NetAddr::IP::Lite qw(:old_nth); old behavior: NetAddr::IP->new('10/32')->nth(0) == undef NetAddr::IP->new('10/32')->nth(1) == undef NetAddr::IP->new('10/31')->nth(0) == undef NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31 NetAddr::IP->new('10/30')->nth(0) == undef NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30 NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30 NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30 Note that in each case, the broadcast address is represented in the output set and that the 'zero'th index is alway undef except for a point-to-point /31 or /127 network where there are exactly two addresses in the network. new behavior: NetAddr::IP->new('10/32')->nth(0) == 10.0.0.0/32 NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32 NetAddr::IP->new('10/31')->nth(0) == 10.0.0.0/32 NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/32 NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30 NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30 NetAddr::IP->new('10/30')->nth(2) == undef Note that a /32 net always has 1 usable address while a /31 has exactly two usable addresses for point-to-point addressing. The first index (0) returns the address immediately following the network address except for a /31 or /127 when it return the network address. =cut sub nth ($$) { my $self = shift; my $count = shift; my $slash31 = ! hasbits($self->{mask} ^ $_cidr127); if ($Old_nth) { return undef if $slash31 && $count != 1; return undef if ($count < 1 or $count > $self->num ()); } elsif ($slash31) { return undef if ($count && $count != 1); # only index 0, 1 allowed for /31 } else { ++$count; return undef if ($count < 1 or $count > $self->num ()); } return $self->network + $count; } =item C<-E<gt>num()> As of version 4.42 of NetAddr::IP and version 1.27 of NetAddr::IP::Lite a /31 and /127 with return a net B<num> value of 2 instead of 0 (zero) for point-to-point networks. Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite return the number of usable IP addresses within the subnet, not counting the broadcast or network address. Previous versions worked only for ipV4 addresses, returned a maximum span of 2**32 and returned the number of IP addresses not counting the broadcast address. (one greater than the new behavior) To use the old behavior for C<-E<gt>nth($index)> and C<-E<gt>num()>: use NetAddr::IP::Lite qw(:old_nth); WARNING: NetAddr::IP will calculate and return a numeric string for network ranges as large as 2**128. These values are TEXT strings and perl can treat them as integers for numeric calculations. Perl on 32 bit platforms only handles integer numbers up to 2**32 and on 64 bit platforms to 2**64. If you wish to manipulate numeric strings returned by NetAddr::IP that are larger than 2**32 or 2**64, respectively, you must load additional modules such as Math::BigInt, bignum or some similar package to do the integer math. =cut sub num ($) { if ($Old_nth) { my @net = unpack('L3N',$_[0]->{mask} ^ Ones); # number of ip's less broadcast return 0xfffffffe if $net[0] || $net[1] || $net[2]; # 2**32 -1 return $net[3] if $net[3]; } else { # returns 1 for /32 /128, 2 for /31 /127 else n-2 up to 2**32 (undef, my $net) = addconst($_[0]->{mask},1); return 1 unless hasbits($net); # ipV4/32 or ipV6/128 $net = $net ^ Ones; return 2 unless hasbits($net); # ipV4/31 or ipV6/127 $net &= $_v4net unless $_[0]->{isv6}; return bin2bcd($net); } } # deprecated #sub num ($) { # my @net = unpack('L3N',$_[0]->{mask} ^ Ones); # if ($Old_nth) { ## number of ip's less broadcast # return 0xfffffffe if $net[0] || $net[1] || $net[2]; # 2**32 -1 # return $net[3] if $net[3]; # } else { # returns 1 for /32 /128, 0 for /31 /127 else n-2 up to 2**32 ## number of usable IP's === number of ip's less broadcast & network addys # return 0xfffffffd if $net[0] || $net[1] || $net[2]; # 2**32 -2 # return 1 unless $net[3]; # $net[3]--; # } # return $net[3]; #} =pod =back =cut sub import { if (grep { $_ eq ':aton' } @_) { $Accept_Binary_IP = 1; @_ = grep { $_ ne ':aton' } @_; } if (grep { $_ eq ':old_nth' } @_) { $Old_nth = 1; @_ = grep { $_ ne ':old_nth' } @_; } if (grep { $_ eq ':lower' } @_) { NetAddr::IP::Util::lower(); @_ = grep { $_ ne ':lower' } @_; } if (grep { $_ eq ':upper' } @_) { NetAddr::IP::Util::upper(); @_ = grep { $_ ne ':upper' } @_; } if (grep { $_ eq ':nofqdn' } @_) { $NoFQDN = 1; @_ = grep { $_ ne ':nofqdn' } @_; } NetAddr::IP::Lite->export_to_level(1, @_); } =head1 EXPORT_OK Zeros Ones V4mask V4net :aton DEPRECATED :old_nth :upper :lower :nofqdn =head1 AUTHORS Luis E. Muñoz E<lt>luismunoz@cpan.orgE<gt>, Michael Robinton E<lt>michael@bizsystems.comE<gt> =head1 WARRANTY This software comes with the same warranty as perl itself (ie, none), so by using it you accept any and all the liability. =head1 COPYRIGHT This software is (c) Luis E. Muñoz, 1999 - 2005 and (c) Michael Robinton, 2006 - 2014. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or b) the "Artistic License" which comes with this distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA or visit their web page on the internet at: http://www.gnu.org/copyleft/gpl.html. =head1 SEE ALSO NetAddr::IP(3), NetAddr::IP::Util(3), NetAddr::IP::InetBase(3) =cut 1; PK � �[:�W �W lib/NetAddr/IP/Util.pmnu ��6�$ #!/usr/bin/perl package NetAddr::IP::Util; use strict; #use diagnostics; #use lib qw(blib/lib); use vars qw($VERSION @EXPORT_OK @ISA %EXPORT_TAGS $Mode); use AutoLoader qw(AUTOLOAD); use NetAddr::IP::Util_IS; use NetAddr::IP::InetBase qw( :upper :all ); *NetAddr::IP::Util::upper = \&NetAddr::IP::InetBase::upper; *NetAddr::IP::Util::lower = \&NetAddr::IP::InetBase::lower; require DynaLoader; require Exporter; @ISA = qw(Exporter DynaLoader); $VERSION = do { my @r = (q$Revision: 1.53 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; @EXPORT_OK = qw( inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n hasbits isIPv4 isNewIPv4 isAnyIPv4 inet_n2dx inet_n2ad inet_pton inet_ntop inet_4map6 shiftleft addconst add128 sub128 notcontiguous bin2bcd bcd2bin mode ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 bin2bcdn bcdn2txt bcdn2bin simple_pack comp128 packzeros AF_INET AF_INET6 naip_gethostbyname havegethostbyname2 ); %EXPORT_TAGS = ( all => [@EXPORT_OK], inet => [qw( inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n inet_n2dx inet_n2ad inet_pton inet_ntop inet_4map6 ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 packzeros naip_gethostbyname )], math => [qw( shiftleft hasbits isIPv4 isNewIPv4 isAnyIPv4 addconst add128 sub128 notcontiguous bin2bcd bcd2bin )], ipv4 => [qw( inet_aton inet_ntoa )], ipv6 => [qw( ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n inet_n2dx inet_n2ad inet_pton inet_ntop inet_4map6 ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 packzeros naip_gethostbyname )], ); if (NetAddr::IP::Util_IS->not_pure) { eval { ## attempt to load 'C' version of utilities bootstrap NetAddr::IP::Util $VERSION; }; } if (NetAddr::IP::Util_IS->pure || $@) { ## load the pure perl version if 'C' lib missing require NetAddr::IP::UtilPP; import NetAddr::IP::UtilPP qw( :all ); # require Socket; # import Socket qw(inet_ntoa); # *yinet_aton = \&Socket::inet_aton; $Mode = 'Pure Perl'; } else { $Mode = 'CC XS'; } # if Socket lib is broken in some way, check for overange values # #my $overange = yinet_aton('256.1') ? 1:0; #my $overange = gethostbyname('256.1') ? 1:0; sub mode() { $Mode }; my $_newV4compat = pack('N4',0,0,0xffff,0); sub inet_4map6 { my $naddr = shift; if (length($naddr) == 4) { $naddr = ipv4to6($naddr); } elsif (length($naddr) == 16) { ; # is OK return undef unless isAnyIPv4($naddr); } else { return undef; } $naddr |= $_newV4compat; return $naddr; } sub DESTROY {}; my $havegethostbyname2 = 0; my $mygethostbyname; my $_Sock6ok = 1; # for testing gethostbyname sub havegethostbyname2 { return $_Sock6ok ? $havegethostbyname2 : 0; } sub import { if (grep { $_ eq ':noSock6' } @_) { $_Sock6ok = 0; @_ = grep { $_ ne ':noSock6' } @_; } NetAddr::IP::Util->export_to_level(1,@_); } package NetAddr::IP::UtilPolluted; # Socket pollutes the name space with all of its symbols. Since # we don't want them all, confine them to this name space. use strict; use Socket; my $_v4zero = pack('L',0); my $_zero = pack('L4',0,0,0,0); # invoke replacement subroutine for Perl's "gethostbyname" # if Socket6 is available. # # NOTE: in certain BSD implementations, Perl's gethostbyname is broken # we will use our own InetBase::inet_aton instead sub _end_gethostbyname { # my ($name,$aliases,$addrtype,$length,@addrs) = @_; my @rv = @_; # first ip address = rv[4] my $tip = $rv[4]; unless ($tip && $tip ne $_v4zero && $tip ne $_zero) { @rv = (); } # length = rv[3] elsif ($rv[3] && $rv[3] == 4) { foreach (4..$#rv) { $rv[$_] = NetAddr::IP::Util::inet_4map6(NetAddr::IP::Util::ipv4to6($rv[$_])); } $rv[3] = 16; # unconditionally set length to 16 } elsif ($rv[3] == 16) { ; # is ok } else { @rv = (); } return @rv; } unless ( eval { require Socket6 }) { $mygethostbyname = sub { # SEE NOTE above about broken BSD my @tip = gethostbyname(NetAddr::IP::InetBase::fillIPv4($_[0])); return &_end_gethostbyname(@tip); }; } else { import Socket6 qw( gethostbyname2 getipnodebyname ); my $try = eval { my @try = gethostbyname2('127.0.0.1',NetAddr::IP::Util::AF_INET()); $try[4] }; if (! $@ && $try && $try eq INADDR_LOOPBACK()) { *_ghbn2 = \&Socket6::gethostbyname2; $havegethostbyname2 = 1; } else { *_ghbn2 = sub { return () }; # use failure branch below } $mygethostbyname = sub { my @tip; unless ($_Sock6ok && (@tip = _ghbn2($_[0],NetAddr::IP::Util::AF_INET6())) && @tip > 1) { # SEE NOTE above about broken BSD @tip = gethostbyname(NetAddr::IP::InetBase::fillIPv4($_[0])); } return &_end_gethostbyname(@tip); }; } package NetAddr::IP::Util; sub naip_gethostbyname { # turn off complaint from Socket6 about missing numeric argument undef local $^W; my @rv = &$mygethostbyname($_[0]); return wantarray ? @rv : $rv[4]; } 1; __END__ =head1 NAME NetAddr::IP::Util -- IPv4/6 and 128 bit number utilities =head1 SYNOPSIS use NetAddr::IP::Util qw( inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n hasbits isIPv4 isNewIPv4 isAnyIPv4 inet_n2dx inet_n2ad inet_pton inet_ntop inet_4map6 ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 packzeros shiftleft addconst add128 sub128 notcontiguous bin2bcd bcd2bin mode AF_INET AF_INET6 naip_gethostbyname ); use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math) :inet => inet_aton, inet_ntoa, ipv6_aton ipv6_ntoa, ipv6_n2x, ipv6_n2d, inet_any2n, inet_n2dx, inet_n2ad, inet_pton, inet_ntop, inet_4map6, ipv4to6, mask4to6, ipanyto6, packzeros maskanyto6, ipv6to4, naip_gethostbyname :ipv4 => inet_aton, inet_ntoa :ipv6 => ipv6_aton, ipv6_ntoa, ipv6_n2x, ipv6_n2d, inet_any2n, inet_n2dx, inet_n2ad, inet_pton, inet_ntop, inet_4map6, ipv4to6, mask4to6, ipanyto6, maskanyto6, ipv6to4, packzeros, naip_gethostbyname :math => hasbits, isIPv4, isNewIPv4, isAnyIPv4, addconst, add128, sub128, notcontiguous, bin2bcd, bcd2bin, shiftleft $dotquad = inet_ntoa($netaddr); $netaddr = inet_aton($dotquad); $ipv6naddr = ipv6_aton($ipv6_text); $ipv6_text = ipvt_ntoa($ipv6naddr); $hex_text = ipv6_n2x($ipv6naddr); $dec_text = ipv6_n2d($ipv6naddr); $hex_text = packzeros($hex_text); $ipv6naddr = inet_any2n($dotquad or $ipv6_text); $ipv6naddr = inet_4map6($netaddr or $ipv6naddr); $rv = hasbits($bits128); $rv = isIPv4($bits128); $rv = isNewIPv4($bits128); $rv = isAnyIPv4($bits128); $dotquad or $hex_text = inet_n2dx($ipv6naddr); $dotquad or $dec_text = inet_n2ad($ipv6naddr); $netaddr = inet_pton($AF_family,$hex_text); $hex_text = inet_ntop($AF_family,$netaddr); $ipv6naddr = ipv4to6($netaddr); $ipv6naddr = mask4to6($netaddr); $ipv6naddr = ipanyto6($netaddr); $ipv6naddr = maskanyto6($netaddr); $netaddr = ipv6to4($pv6naddr); $bitsX2 = shiftleft($bits128,$n); $carry = addconst($ipv6naddr,$signed_32con); ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con); $carry = add128($ipv6naddr1,$ipv6naddr2); ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2); $carry = sub128($ipv6naddr1,$ipv6naddr2); ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2); ($spurious,$cidr) = notcontiguous($mask128); $bcdtext = bin2bcd($bits128); $bits128 = bcd2bin($bcdtxt); $modetext = mode; ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME); $trueif = havegethostbyname2(); NetAddr::IP::Util::lower(); NetAddr::IP::Util::upper(); =head1 INSTALLATION Un-tar the distribution in an appropriate directory and type: perl Makefile.PL make make test make install B<NetAddr::IP::Util> installs by default with its primary functions compiled using Perl's XS extensions to build a 'C' library. If you do not have a 'C' complier available or would like the slower Pure Perl version for some other reason, then type: perl Makefile.PL -noxs make make test make install =head1 DESCRIPTION B<NetAddr::IP::Util> provides a suite of tools for manipulating and converting IPv4 and IPv6 addresses into 128 bit string context and back to text. The strings can be manipulated with Perl's logical operators: and & or | xor ^ ~ compliment in the same manner as 'vec' strings. The IPv6 functions support all rfc1884 formats. i.e. x:x:x:x:x:x:x:x:x x:x:x:x:x:x:x:d.d.d.d ::x:x:x ::x:d.d.d.d and so on... =over 4 =item * $dotquad = inet_ntoa($netaddr); Convert a packed IPv4 network address to a dot-quad IP address. input: packed network address returns: IP address i.e. 10.4.12.123 =item * $netaddr = inet_aton($dotquad); Convert a dot-quad IP address into an IPv4 packed network address. input: IP address i.e. 192.5.16.32 returns: packed network address =item * $ipv6addr = ipv6_aton($ipv6_text); Takes an IPv6 address of the form described in rfc1884 and returns a 128 bit binary RDATA string. input: ipv6 text returns: 128 bit RDATA string =item * $ipv6_text = ipv6_ntoa($ipv6naddr); Convert a 128 bit binary IPv6 address to compressed rfc 1884 text representation. input: 128 bit RDATA string returns: ipv6 text =item * $hex_text = ipv6_n2x($ipv6addr); Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex address input: 128 bit RDATA string returns: x:x:x:x:x:x:x:x =item * $dec_text = ipv6_n2d($ipv6addr); Takes an IPv6 RDATA string and returns a mixed hex - decimal IPv6 address with the 6 uppermost chunks in hex and the lower 32 bits in dot-quad representation. input: 128 bit RDATA string returns: x:x:x:x:x:x:d.d.d.d =item * $ipv6naddr = inet_any2n($dotquad or $ipv6_text); This function converts a text IPv4 or IPv6 address in text format in any standard notation into a 128 bit IPv6 string address. It prefixes any dot-quad address (if found) with '::' and passes it to B<ipv6_aton>. input: dot-quad or rfc1844 address returns: 128 bit IPv6 string =item * $rv = hasbits($bits128); This function returns true if there are one's present in the 128 bit string and false if all the bits are zero. i.e. if (hasbits($bits128)) { &do_something; } or if (hasbits($bits128 & $mask128) { &do_something; } This allows the implementation of logical functions of the form of: if ($bits128 & $mask128) { ... input: 128 bit IPv6 string returns: true if any bits are present =item * $ipv6naddr = inet_4map6($netaddr or $ipv6naddr This function returns an ipV6 network address with the first 80 bits set to zero and the next 16 bits set to one, while the last 32 bits are filled with the ipV4 address. input: ipV4 netaddr or ipV6 netaddr returns: ipV6 netaddr returns: undef on error An ipV6 network address must be in one of the two compatible ipV4 mapped address spaces. i.e. ::ffff::d.d.d.d or ::d.d.d.d =item * $rv = isIPv4($bits128); This function returns true if there are no on bits present in the IPv6 portion of the 128 bit string and false otherwise. i.e. the address must be of the form - ::d.d.d.d Note: this is an old and deprecated ipV4 compatible ipV6 address =item * $rv = isNewIPv4($bits128); This function return true if the IPv6 128 bit string is of the form ::ffff::d.d.d.d =item * $rv = isAnyIPv4($bits128); This function return true if the IPv6 bit string is of the form ::d.d.d.d or ::ffff::d.d.d.d =item * $dotquad or $hex_text = inet_n2dx($ipv6naddr); This function B<does the right thing> and returns the text for either a dot-quad IPv4 or a hex notation IPv6 address. input: 128 bit IPv6 string returns: ddd.ddd.ddd.ddd or x:x:x:x:x:x:x:x =item * $dotquad or $dec_text = inet_n2ad($ipv6naddr); This function B<does the right thing> and returns the text for either a dot-quad IPv4 or a hex::decimal notation IPv6 address. input: 128 bit IPv6 string returns: ddd.ddd.ddd.ddd or x:x:x:x:x:x:ddd.ddd.ddd.dd =item * $netaddr = inet_pton($AF_family,$hex_text); This function takes an IP address in IPv4 or IPv6 text format and converts it into binary format. The type of IP address conversion is controlled by the FAMILY argument. =item * $hex_text = inet_ntop($AF_family,$netaddr); This function takes and IP address in binary format and converts it into text format. The type of IP address conversion is controlled by the FAMILY argument. NOTE: inet_ntop ALWAYS returns lowercase characters. =item * $hex_text = packzeros($hex_text); This function optimizes and rfc 1884 IPv6 hex address to reduce the number of long strings of zero bits as specified in rfc 1884, 2.2 (2) by substituting B<::> for the first occurence of the longest string of zeros in the address. =item * $ipv6naddr = ipv4to6($netaddr); Convert an ipv4 network address into an IPv6 network address. input: 32 bit network address returns: 128 bit network address =item * $ipv6naddr = mask4to6($netaddr); Convert an ipv4 network address/mask into an ipv6 network mask. input: 32 bit network/mask address returns: 128 bit network/mask address NOTE: returns the high 96 bits as one's =item * $ipv6naddr = ipanyto6($netaddr); Similar to ipv4to6 except that this function takes either an IPv4 or IPv6 input and always returns a 128 bit IPv6 network address. input: 32 or 128 bit network address returns: 128 bit network address =item * $ipv6naddr = maskanyto6($netaddr); Similar to mask4to6 except that this function takes either an IPv4 or IPv6 netmask and always returns a 128 bit IPv6 netmask. input: 32 or 128 bit network mask returns: 128 bit network mask =item * $netaddr = ipv6to4($pv6naddr); Truncate the upper 96 bits of a 128 bit address and return the lower 32 bits. Returns an IPv4 address as returned by inet_aton. input: 128 bit network address returns: 32 bit inet_aton network address =item * $bitsXn = shiftleft($bits128,$n); input: 128 bit string variable, number of shifts [optional] returns: bits X n shifts NOTE: a single shift is performed if $n is not specified =item * addconst($ipv6naddr,$signed_32con); Add a signed constant to a 128 bit string variable. input: 128 bit IPv6 string, signed 32 bit integer returns: scalar carry array (carry, result) =item * add128($ipv6naddr1,$ipv6naddr2); Add two 128 bit string variables. input: 128 bit string var1, 128 bit string var2 returns: scalar carry array (carry, result) =item * sub128($ipv6naddr1,$ipv6naddr2); Subtract two 128 bit string variables. input: 128 bit string var1, 128 bit string var2 returns: scalar carry array (carry, result) Note: The carry from this operation is the result of adding the one's complement of ARG2 +1 to the ARG1. It is logically B<NOT borrow>. i.e. if ARG1 >= ARG2 then carry = 1 or if ARG1 < ARG2 then carry = 0 =item * ($spurious,$cidr) = notcontiguous($mask128); This function counts the bit positions remaining in the mask when the rightmost '0's are removed. input: 128 bit netmask returns true if there are spurious zero bits remaining in the mask, false if the mask is contiguous one's, 128 bit cidr number =item * $bcdtext = bin2bcd($bits128); Convert a 128 bit binary string into binary coded decimal text digits. input: 128 bit string variable returns: string of bcd text digits =item * $bits128 = bcd2bin($bcdtxt); Convert a bcd text string to 128 bit string variable input: string of bcd text digits returns: 128 bit string variable =cut #=item * $onescomp=NetAddr::IP::Util::comp128($ipv6addr); # #This function is not exported because it is more efficient to use perl " ~ " #on the bit string directly. This interface to the B<C> routine is published for #module testing purposes because it is used internally in the B<sub128> routine. The #function is very fast, but calling if from perl directly is very slow. It is almost #33% faster to use B<sub128> than to do a 1's comp with perl and then call #B<add128>. # #=item * $bcdpacked = NetAddr::IP::Util::bin2bcdn($bits128); # #Convert a 128 bit binary string into binary coded decimal digits. #This function is not exported. # # input: 128 bit string variable # returns: string of packed decimal digits # # i.e. text = unpack("H*", $bcd); # #=item * $bcdtext = NetAddr::IP::Util::bcdn2txt($bcdpacked); # #Convert a packed bcd string into text digits, suppress the leading zeros. #This function is not exported. # # input: string of packed decimal digits # returns: hexadecimal digits # #Similar to unpack("H*", $bcd); # #=item * $bcdpacked = NetAddr::IP::Util::simple_pack($bcdtext); # #Convert a numeric string into a packed bcd string, left fill with zeros # # input: string of decimal digits # returns: string of packed decimal digits # #Similar to pack("H*", $bcdtext); =item * $modetext = mode; Returns the operating mode of this module. input: none returns: "Pure Perl" or "CC XS" =item * ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME); Replacement for Perl's gethostbyname if Socket6 is available In ARRAY context, returns a list of five elements, the hostname or NAME, a space separated list of C_NAMES, AF family, length of the address structure, and an array of one or more netaddr's In SCALAR context, returns the first netaddr. This function ALWAYS returns an IPv6 address, even on IPv4 only systems. IPv4 addresses are mapped into IPv6 space in the form: ::FFFF:FFFF:d.d.d.d This is NOT the expected result from Perl's gethostbyname2. It is instead equivalent to: On an IPv4 only system: $ipv6naddr = ipv4to6 scalar ( gethostbyname( name )); On a system with Socket6 and a working gethostbyname2: $ipv6naddr = gethostbyname2( name, AF_INET6 ); and if that fails, the IPv4 conversion above. For a gethostbyname2 emulator that behave like Socket6, see: L<Net::DNS::Dig> =item * $trueif = havegethostbyname2(); This function returns TRUE if Socket6 has a functioning B<gethostbyname2>, otherwise it returns FALSE. See the comments above about the behavior of B<naip_gethostbyname>. =item * NetAddr::IP::Util::lower(); Return IPv6 strings in lowercase. =item * NetAddr::IP::Util::upper(); Return IPv6 strings in uppercase. This is the default. =back =head1 EXAMPLES # convert any textual IP address into a 128 bit vector # sub text2vec { my($anyIP,$anyMask) = @_; # not IPv4 bit mask my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::'); my $vecip = inet_any2n($anyIP); my $mask = inet_any2n($anyMask); # extend mask bits for IPv4 my $bits = 128; # default unless (hasbits($mask & $notiv4)) { $mask |= $notiv4; $bits = 32; } return ($vecip, $mask, $bits); } ... alternate implementation, a little faster sub text2vec { my($anyIP,$anyMask) = @_; # not IPv4 bit mask my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::'); my $vecip = inet_any2n($anyIP); my $mask = inet_any2n($anyMask); # extend mask bits for IPv4 my $bits = 128; # default if (isIPv4($mask)) { $mask |= $notiv4; $bits = 32; } return ($vecip, $mask, $bits); } ... elsewhere $nip = { addr => $vecip, mask => $mask, bits => $bits, }; # return network and broadcast addresses from IP and Mask # sub netbroad { my($nip) = shift; my $notmask = ~ $nip->{mask}; my $bcast = $nip->{addr} | $notmask; my $network = $nip->{addr} & $nip->{mask}; return ($network, $broadcast); } # check if address is within a network # sub within { my($nip,$net) = @_; my $addr = $nip->{addr} my($nw,$bc) = netbroad($net); # arg1 >= arg2, sub128 returns true return (sub128($addr,$nw) && sub128($bc,$addr)) ? 1 : 0; } # truely hard way to do $ip++ # add a constant, wrapping at netblock boundaries # to subtract the constant, negate it before calling # 'addwrap' since 'addconst' will extend the sign bits # sub addwrap { my($nip,$const) = @_; my $addr = $nip->{addr}; my $mask = $nip->{mask}; my $bits = $nip->{bits}; my $notmask = ~ $mask; my $hibits = $addr & $mask; $addr = addconst($addr,$const); my $wraponly = $addr & $notmask; my $newip = { addr => $hibits | $wraponly, mask => $mask, bits => $bits, }; # bless $newip as appropriate return $newip; } # something more useful # increment a /24 net to the NEXT net at the boundry my $nextnet = 256; # for /24 LOOP: while (...continuing) { your code.... ... my $lastip = $ip-copy(); $ip++; if ($ip < $lastip) { # host part wrapped? # discard carry (undef, $ip->{addr} = addconst($ip->{addr}, $nextnet); } next LOOP; } =head1 EXPORT_OK inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n hasbits isIPv4 isNewIPv4 isAnyIPv4 inet_n2dx inet_n2ad inet_pton inet_ntop inet_4map6 ipv4to6 mask4to6 ipanyto6 maskanyto6 ipv6to4 packzeros shiftleft addconst add128 sub128 notcontiguous bin2bcd bcd2bin mode naip_gethostbyname havegethostbyname2 =head1 AUTHOR Michael Robinton <michael@bizsystems.com> =head1 COPYRIGHT Copyright 2003 - 2014, Michael Robinton E<lt>michael@bizsystems.comE<gt> All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or b) the "Artistic License" which comes with this distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA. or visit their web page on the internet at: http://www.gnu.org/copyleft/gpl.html. =head1 AUTHOR Michael Robinton <michael@bizsystems.com> =head1 SEE ALSO NetAddr::IP(3), NetAddr::IP::Lite(3), NetAddr::IP::InetBase(3) =cut 1; PK � �[�I� � lib/NetAddr/IP/Util_IS.pmnu ��6�$ #!/usr/bin/perl # # DO NOT ALTER THIS FILE # IT IS WRITTEN BY Makefile.PL # EDIT THAT INSTEAD # package NetAddr::IP::Util_IS; use vars qw($VERSION); $VERSION = 1.00; sub pure { return 0; } sub not_pure { return 1; } 1; __END__ =head1 NAME NetAddr::IP::Util_IS - Tell about Pure Perl =head1 SYNOPSIS use NetAddr::IP::Util_IS; $rv = NetAddr::IP::Util_IS->pure; $rv = NetAddr::IP::Util_IS->not_pure; =head1 DESCRIPTION Util_IS indicates whether or not B<NetAddr::IP::Util> was compiled in Pure Perl mode. =over 4 =item * $rv = NetAddr::IP::Util_IS->pure; Returns true if PurePerl mode, else false. =item * $rv = NetAddr::IP::Util_IS->not_pure; Returns true if NOT PurePerl mode, else false =back =cut 1; PK � �[ lib/NetAddr/IP/.existsnu �[��� PK � �[� K K lib/NetAddr/IP/InetBase.pmnu ��6�$ #!/usr/bin/perl package NetAddr::IP::InetBase; use strict; #use diagnostics; #use lib qw(blib lib); use vars qw($VERSION @EXPORT_OK @ISA %EXPORT_TAGS $Mode); use AutoLoader qw(AUTOLOAD); require Exporter; @ISA = qw(Exporter); $VERSION = do { my @r = (q$Revision: 0.08 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; @EXPORT_OK = qw( inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n inet_n2dx inet_n2ad inet_ntop inet_pton packzeros isIPv4 isNewIPv4 isAnyIPv4 AF_INET AF_INET6 fake_AF_INET6 fillIPv4 ); %EXPORT_TAGS = ( all => [@EXPORT_OK], ipv4 => [qw( inet_aton inet_ntoa fillIPv4 )], ipv6 => [qw( ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n inet_n2dx inet_n2ad inet_pton inet_ntop packzeros )], ); # prototypes sub inet_ntoa; sub ipv6_aton; sub ipv6_ntoa; sub inet_any2n($); sub inet_n2dx($); sub inet_n2ad($); sub _inet_ntop; sub _inet_pton; my $emulateAF_INET6 = 0; { no warnings 'once'; *packzeros = \&_packzeros; ## dynamic configuraton for IPv6 require Socket; *AF_INET = \&Socket::AF_INET; if (eval { AF_INET6() } ) { *AF_INET6 = \&Socket::AF_INET6; $emulateAF_INET6 = -1; # have it, remind below } if (eval{ require Socket6 } ) { import Socket6 qw( inet_pton inet_ntop ); unless ($emulateAF_INET6) { *AF_INET6 = \&Socket6::AF_INET6; } $emulateAF_INET6 = 0; # clear, have it from elsewhere or here } else { unless ($emulateAF_INET6) { # unlikely at this point if ($^O =~ /(?:free|dragon.+)bsd/i) { # FreeBSD, DragonFlyBSD $emulateAF_INET6 = 28; } elsif ($^O =~ /bsd/i) { # other BSD flavors like NetBDS, OpenBSD, BSD $emulateAF_INET6 = 24; } elsif ($^O =~ /(?:darwin|mac)/i) { # Mac OS X $emulateAF_INET6 = 30; } elsif ($^O =~ /win/i) { # Windows $emulateAF_INET6 = 23; } elsif ($^O =~ /(?:solaris|sun)/i) { # Sun box $emulateAF_INET6 = 26; } else { # use linux default $emulateAF_INET6 = 10; } *AF_INET6 = sub { $emulateAF_INET6; }; } else { $emulateAF_INET6 = 0; # clear, have it from elsewhere } *inet_pton = \&_inet_pton; *inet_ntop = \&_inet_ntop; } } # end no warnings 'once' sub fake_AF_INET6 { return $emulateAF_INET6; } # allow user to choose upper or lower case BEGIN { use vars qw($n2x_format $n2d_format); $n2x_format = "%x:%x:%x:%x:%x:%x:%x:%x"; $n2d_format = "%x:%x:%x:%x:%x:%x:%d.%d.%d.%d"; } my $case = 0; # default lower case sub upper { $n2x_format = uc($n2x_format); $n2d_format = uc($n2d_format); $case = 1; } sub lower { $n2x_format = lc($n2x_format); $n2d_format = lc($n2d_format); $case = 0; } sub ipv6_n2x { die "Bad arg length for 'ipv6_n2x', length is ". length($_[0]) ." should be 16" unless length($_[0]) == 16; return sprintf($n2x_format,unpack("n8",$_[0])); } sub ipv6_n2d { die "Bad arg length for 'ipv6_n2d', length is ". length($_[0]) ." should be 16" unless length($_[0]) == 16; my @hex = (unpack("n8",$_[0])); $hex[9] = $hex[7] & 0xff; $hex[8] = $hex[7] >> 8; $hex[7] = $hex[6] & 0xff; $hex[6] >>= 8; return sprintf($n2d_format,@hex); } # if Socket lib is broken in some way, check for overange values # #my $overange = yinet_aton('256.1') ? 1:0; #my $overange = gethostbyname('256.1') ? 1:0; #sub inet_aton { # unless (! $overange || $_[0] =~ /[^0-9\.]/) { # hostname # my @dq = split(/\./,$_[0]); # foreach (@dq) { # return undef if $_ > 255; # } # } # scalar gethostbyname($_[0]); #} sub fillIPv4 { my $host = $_[0]; return undef unless defined $host; if ($host =~ /^(\d+)(?:|\.(\d+)(?:|\.(\d+)(?:|\.(\d+))))$/) { if (defined $4) { return undef unless $1 >= 0 && $1 < 256 && $2 >= 0 && $2 < 256 && $3 >= 0 && $3 < 256 && $4 >= 0 && $4 < 256; $host = $1.'.'.$2.'.'.$3.'.'.$4; # return pack('C4',$1,$2,$3,$4); # $host = ($1 << 24) + ($2 << 16) + ($3 << 8) + $4; } elsif (defined $3) { return undef unless $1 >= 0 && $1 < 256 && $2 >= 0 && $2 < 256 && $3 >= 0 && $3 < 256; $host = $1.'.'.$2.'.0.'.$3 # return pack('C4',$1,$2,0,$3); # $host = ($1 << 24) + ($2 << 16) + $3; } elsif (defined $2) { return undef unless $1 >= 0 && $1 < 256 && $2 >= 0 && $2 < 256; $host = $1.'.0.0.'.$2; # return pack('C4',$1,0,0,$2); # $host = ($1 << 24) + $2; } else { $host = '0.0.0.'.$1; # return pack('C4',0,0,0,$1); # $host = $1; } # return pack('N',$host); } $host; } sub inet_aton { my $host = fillIPv4($_[0]); return $host ? scalar gethostbyname($host) : undef; } #sub inet_aton { # my $host = $_[0]; # return undef unless defined $host; # if ($host =~ /^(\d+)(?:|\.(\d+)(?:|\.(\d+)(?:|\.(\d+))))$/) { # if (defined $4) { # return undef unless # $1 >= 0 && $1 < 256 && # $2 >= 0 && $2 < 256 && # $3 >= 0 && $3 < 256 && # $4 >= 0 && $4 < 256; # return pack('C4',$1,$2,$3,$4); ## $host = ($1 << 24) + ($2 << 16) + ($3 << 8) + $4; # } elsif (defined $3) { # return undef unless # $1 >= 0 && $1 < 256 && # $2 >= 0 && $2 < 256 && # $3 >= 0 && $3 < 256; # return pack('C4',$1,$2,0,$3); ## $host = ($1 << 24) + ($2 << 16) + $3; # } elsif (defined $2) { # return undef unless # $1 >= 0 && $1 < 256 && # $2 >= 0 && $2 < 256; # return pack('C4',$1,0,0,$2); ## $host = ($1 << 24) + $2; # } else { # return pack('C4',0,0,0,$1); ## $host = $1; # } ## return pack('N',$host); # } # scalar gethostbyname($host); #} my $_zero = pack('L4',0,0,0,0); my $_ipv4mask = pack('L4',0xffffffff,0xffffffff,0xffffffff,0); sub isIPv4 { if (length($_[0]) != 16) { my $sub = (caller(1))[3] || (caller(0))[3]; die "Bad arg length for $sub, length is ". (length($_[0]) *8) .", should be 128"; } return ($_[0] & $_ipv4mask) eq $_zero ? 1 : 0; } my $_newV4compat = pack('N4',0,0,0xffff,0); sub isNewIPv4 { my $naddr = $_[0] ^ $_newV4compat; return isIPv4($naddr); } sub isAnyIPv4 { my $naddr = $_[0]; my $rv = isIPv4($_[0]); return $rv if $rv; return isNewIPv4($naddr); } sub DESTROY {}; sub import { if (grep { $_ eq ':upper' } @_) { upper(); @_ = grep { $_ ne ':upper' } @_; } NetAddr::IP::InetBase->export_to_level(1,@_); } 1; __END__ =head1 NAME NetAddr::IP::InetBase -- IPv4 and IPV6 utilities =head1 SYNOPSIS use NetAddr::IP::Base qw( :upper inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n inet_n2dx inet_n2ad inet_pton inet_ntop packzeros isIPv4 isNewIPv4 isAnyIPv4 AF_INET AF_INET6 fake_AF_INET6 fillIPv4 ); use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math) :ipv4 => inet_aton, inet_ntoa, fillIPv4 :ipv6 => ipv6_aton, ipv6_ntoa,ipv6_n2x, ipv6_n2d, inet_any2n, inet_n2dx, inet_n2ad inet_pton, inet_ntop, packzeros $dotquad = inet_ntoa($netaddr); $netaddr = inet_aton($dotquad); $ipv6naddr = ipv6_aton($ipv6_text); $ipv6_text = ipv6_ntoa($ipv6naddr); $hex_text = ipv6_n2x($ipv6naddr); $dec_text = ipv6_n2d($ipv6naddr); $ipv6naddr = inet_any2n($dotquad or $ipv6_text); $dotquad or $hex_text = inet_n2dx($ipv6naddr); $dotquad or $dec_text = inet_n2ad($ipv6naddr); $netaddr = inet_pton($AF_family,$text_addr); $text_addr = inet_ntop($AF_family,$netaddr); $hex_text = packzeros($hex_text); $rv = isIPv4($bits128); $rv = isNewIPv4($bits128); $rv = isAnyIPv4($bits128); $constant = AF_INET(); $constant = AF_INET6(); $trueif = fake_AF_INET6(); $ip_filled = fillIPv4($shortIP); NetAddr::IP::InetBase::lower(); NetAddr::IP::InetBase::upper(); =head1 INSTALLATION Un-tar the distribution in an appropriate directory and type: perl Makefile.PL make make test make install =head1 DESCRIPTION B<NetAddr::IP::InetBase> provides a suite network of conversion functions written in pure Perl for converting both IPv4 and IPv6 addresses to and from network address format and text format. The IPv6 functions support all rfc1884 formats. i.e. x:x:x:x:x:x:x:x:x x:x:x:x:x:x:x:d.d.d.d ::x:x:x ::x:d.d.d.d and so on... =over 4 =item * $dotquad = inet_ntoa($netaddr); Convert a packed IPv4 network address to a dot-quad IP address. input: packed network address returns: IP address i.e. 10.4.12.123 =cut sub inet_ntoa { die 'Bad arg length for '. __PACKAGE__ ."::inet_ntoa, length is ". length($_[0]) ." should be 4" unless length($_[0]) == 4; my @hex = (unpack("n2",$_[0])); $hex[3] = $hex[1] & 0xff; $hex[2] = $hex[1] >> 8; $hex[1] = $hex[0] & 0xff; $hex[0] >>= 8; return sprintf("%d.%d.%d.%d",@hex); } =item * $netaddr = inet_aton($dotquad); Convert a dot-quad IP address into an IPv4 packed network address. input: IP address i.e. 192.5.16.32 returns: packed network address =item * $ipv6addr = ipv6_aton($ipv6_text); Takes an IPv6 address of the form described in rfc1884 and returns a 128 bit binary RDATA string. input: ipv6 text returns: 128 bit RDATA string =cut sub ipv6_aton { my($ipv6) = @_; return undef unless $ipv6; local($1,$2,$3,$4,$5); if ($ipv6 =~ /^(.*:)(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/) { # mixed hex, dot-quad return undef if $2 > 255 || $3 > 255 || $4 > 255 || $5 > 255; $ipv6 = sprintf("%s%X%02X:%X%02X",$1,$2,$3,$4,$5); # convert to pure hex } my $c; return undef if $ipv6 =~ /[^:0-9a-fA-F]/ || # non-hex character (($c = $ipv6) =~ s/::/x/ && $c =~ /(?:x|:):/) || # double :: ::? $ipv6 =~ /[0-9a-fA-F]{5,}/; # more than 4 digits $c = $ipv6 =~ tr/:/:/; # count the colons return undef if $c < 7 && $ipv6 !~ /::/; if ($c > 7) { # strip leading or trailing :: return undef unless $ipv6 =~ s/^::/:/ || $ipv6 =~ s/::$/:/; return undef if --$c > 7; } while ($c++ < 7) { # expand compressed fields $ipv6 =~ s/::/:::/; } $ipv6 .= 0 if $ipv6 =~ /:$/; my @hex = split(/:/,$ipv6); foreach(0..$#hex) { $hex[$_] = hex($hex[$_] || 0); } pack("n8",@hex); } =item * $ipv6text = ipv6_ntoa($ipv6naddr); Convert a 128 bit binary IPv6 address to compressed rfc 1884 text representation. input: 128 bit RDATA string returns: ipv6 text =cut sub ipv6_ntoa { return inet_ntop(AF_INET6(),$_[0]); } =item * $hex_text = ipv6_n2x($ipv6addr); Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex address input: 128 bit RDATA string returns: x:x:x:x:x:x:x:x Note: this function does NOT compress adjacent strings of 0:0:0:0 into the :: format =item * $dec_text = ipv6_n2d($ipv6addr); Takes an IPv6 RDATA string and returns a mixed hex - decimal IPv6 address with the 6 uppermost chunks in hex and the lower 32 bits in dot-quad representation. input: 128 bit RDATA string returns: x:x:x:x:x:x:d.d.d.d Note: this function does NOT compress adjacent strings of 0:0:0:0 into the :: format =item * $ipv6naddr = inet_any2n($dotquad or $ipv6_text); This function converts a text IPv4 or IPv6 address in text format in any standard notation into a 128 bit IPv6 string address. It prefixes any dot-quad address (if found) with '::' and passes it to B<ipv6_aton>. input: dot-quad or rfc1844 address returns: 128 bit IPv6 string =cut sub inet_any2n($) { my($addr) = @_; $addr = '' unless $addr; $addr = '::' . $addr unless $addr =~ /:/; return ipv6_aton($addr); } =item * $dotquad or $hex_text = inet_n2dx($ipv6naddr); This function B<does the right thing> and returns the text for either a dot-quad IPv4 or a hex notation IPv6 address. input: 128 bit IPv6 string returns: ddd.ddd.ddd.ddd or x:x:x:x:x:x:x:x Note: this function does NOT compress adjacent strings of 0:0:0:0 into the :: format =cut sub inet_n2dx($) { my($nadr) = @_; if (isAnyIPv4($nadr)) { local $1; ipv6_n2d($nadr) =~ /([^:]+)$/; return $1; } return ipv6_n2x($nadr); } =item * $dotquad or $dec_text = inet_n2ad($ipv6naddr); This function B<does the right thing> and returns the text for either a dot-quad IPv4 or a hex::decimal notation IPv6 address. input: 128 bit IPv6 string returns: ddd.ddd.ddd.ddd or x:x:x:x:x:x:ddd.ddd.ddd.dd Note: this function does NOT compress adjacent strings of 0:0:0:0 into the :: format =cut sub inet_n2ad($) { my($nadr) = @_; my $addr = ipv6_n2d($nadr); return $addr unless isAnyIPv4($nadr); local $1; $addr =~ /([^:]+)$/; return $1; } =item * $netaddr = inet_pton($AF_family,$text_addr); This function takes an IP address in IPv4 or IPv6 text format and converts it into binary format. The type of IP address conversion is controlled by the FAMILY argument. NOTE: inet_pton, inet_ntop and AF_INET6 come from the Socket6 library if it is present on this host. =cut sub _inet_pton { my($af,$ip) = @_; die 'Bad address family for '. __PACKAGE__ ."::inet_pton, got $af" unless $af == AF_INET6() || $af == AF_INET(); if ($af == AF_INET()) { inet_aton($ip); } else { ipv6_aton($ip); } } =item * $text_addr = inet_ntop($AF_family,$netaddr); This function takes and IP address in binary format and converts it into text format. The type of IP address conversion is controlled by the FAMILY argument. NOTE: inet_ntop ALWAYS returns lowercase characters. NOTE: inet_pton, inet_ntop and AF_INET6 come from the Socket6 library if it is present on this host. =cut sub _inet_ntop { my($af,$naddr) = @_; die 'Unsupported address family for '. __PACKAGE__ ."::inet_ntop, af is $af" unless $af == AF_INET6() || $af == AF_INET(); if ($af == AF_INET()) { inet_ntoa($naddr); } else { return ($case) ? lc packzeros(ipv6_n2x($naddr)) : _packzeros(ipv6_n2x($naddr)); } } =item * $hex_text = packzeros($hex_text); This function optimizes and rfc 1884 IPv6 hex address to reduce the number of long strings of zero bits as specified in rfc 1884, 2.2 (2) by substituting B<::> for the first occurence of the longest string of zeros in the address. =cut sub _packzeros { my $x6 = shift; if ($x6 =~ /\:\:/) { # already contains :: # then re-optimize $x6 = ($x6 =~ /\:\d+\.\d+\.\d+\.\d+/) # ipv4 notation ? ? ipv6_n2d(ipv6_aton($x6)) : ipv6_n2x(ipv6_aton($x6)); } $x6 = ':'. lc $x6; # prefix : & always lower case my $d = ''; if ($x6 =~ /(.+\:)(\d+\.\d+\.\d+\.\d+)/) { # if contains dot quad $x6 = $1; # save hex piece $d = $2; # and dot quad piece } $x6 .= ':'; # suffix : $x6 =~ s/\:0+/\:0/g; # compress strings of 0's to single '0' $x6 =~ s/\:0([1-9a-f]+)/\:$1/g; # eliminate leading 0's in hex strings my @x = $x6 =~ /(?:\:0)*/g; # split only strings of :0:0..." my $m = 0; my $i = 0; for (0..$#x) { # find next longest pattern :0:0:0... my $len = length($x[$_]); next unless $len > $m; $m = $len; $i = $_; # index to first longest pattern } if ($m > 2) { # there was a string of 2 or more zeros $x6 =~ s/$x[$i]/\:/; # replace first longest :0:0:0... with "::" unless ($i) { # if it is the first match, $i = 0 $x6 = substr($x6,0,-1); # keep the leading ::, remove trailing ':' } else { $x6 = substr($x6,1,-1); # else remove leading & trailing ':' } $x6 .= ':' unless $x6 =~ /\:\:/; # restore ':' if match and we can't see it, implies trailing '::' } else { # there was no match $x6 = substr($x6,1,-1); # remove leading & trailing ':' } $x6 .= $d; # append digits if any return $case ? uc $x6 : $x6; } =item * $ipv6naddr = ipv4to6($netaddr); Convert an ipv4 network address into an ipv6 network address. input: 32 bit network address returns: 128 bit network address =item * $rv = isIPv4($bits128); This function returns true if there are no on bits present in the IPv6 portion of the 128 bit string and false otherwise. i.e. the address must be of the form - ::d.d.d.d Note: this is an old and deprecated ipV4 compatible ipV6 address =item * $rv = isNewIPv4($bits128); This function return true if the IPv6 128 bit string is of the form ::ffff:d.d.d.d =item * $rv = isAnyIPv4($bits128); This function return true if the IPv6 bit string is of the form ::d.d.d.d or ::ffff:d.d.d.d =item * NetAddr::IP::InetBase::lower(); Return IPv6 strings in lowercase. This is the default. =item * NetAddr::IP::InetBase::upper(); Return IPv6 strings in uppercase. The default may be set to uppercase when the module is loaded by invoking the TAG :upper. i.e. use NetAddr::IP::InetBase qw( :upper ); =item * $constant = AF_INET; This function returns the system value for AF_INET. =item * $constant = AF_INET6; AF_INET6 is sometimes present in the Socket library and always present in the Socket6 library. When the Socket library does not contain AF_INET6 and when Socket6 is not present, a place holder value is C<guessed> based on the underlying host operating system. See B<fake_AF_INET6> below. NOTE: inet_pton, inet_ntop and AF_INET6 come from the Socket6 library if it is present on this host. =item * $trueif = fake_AF_INET6; This function return FALSE if AF_INET6 is provided by Socket or Socket6. Otherwise, it returns the best guess value based on name of the host operating system. =item * $ip_filled = fillIPv4($shortIP); This function converts IPv4 addresses of the form 127.1 to the long form 127.0.0.1 If the function is passed an argument that does not match the form of an IP address, the original argument is returned. i.e. pass it a hostname or a short IP and it will return a hostname or a filled IP. =back =head1 EXPORT_OK :upper inet_aton inet_ntoa ipv6_aton ipv6_ntoa ipv6_n2x ipv6_n2d inet_any2n inet_n2dx inet_n2ad inet_pton inet_ntop packzeros isIPv4 isNewIPv4 isAnyIPv4 AF_INET AF_INET6 fake_AF_INET6 fillIPv4 =head1 %EXPORT_TAGS :all :ipv4 :ipv6 :upper =head1 AUTHOR Michael Robinton <michael@bizsystems.com> =head1 COPYRIGHT Copyright 2003 - 2012, Michael Robinton E<lt>michael@bizsystems.comE<gt> All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or b) the "Artistic License" which comes with this distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA or visit their web page on the internet at: http://www.gnu.org/copyleft/gpl.html. =head1 AUTHOR Michael Robinton <michael@bizsystems.com> =head1 SEE ALSO NetAddr::IP(3), NetAddr::IP::Lite(3), NetAddr::IP::Util(3) =cut 1; PK � �[O���C� C� lib/NetAddr/IP.pmnu ��6�$ #!/usr/bin/perl -w package NetAddr::IP; use strict; #use diagnostics; use Carp; use NetAddr::IP::Lite 1.57 qw(Zero Zeros Ones V4mask V4net); use NetAddr::IP::Util 1.53 qw( sub128 inet_aton inet_any2n ipv6_aton isIPv4 ipv4to6 mask4to6 shiftleft addconst hasbits notcontiguous ); use AutoLoader qw(AUTOLOAD); use vars qw( @EXPORT_OK @EXPORT_FAIL @ISA $VERSION $_netlimit $rfc3021 ); require Exporter; @EXPORT_OK = qw(Compact Coalesce Zero Zeros Ones V4mask V4net netlimit); @EXPORT_FAIL = qw($_netlimit); @ISA = qw(Exporter NetAddr::IP::Lite); $VERSION = do { sprintf " %d.%03d", (q$Revision: 4.79 $ =~ /\d+/g) }; $rfc3021 = 0; =pod =encoding UTF-8 =head1 NAME NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets =head1 SYNOPSIS use NetAddr::IP qw( Compact Coalesce Zeros Ones V4mask V4net netlimit :aton DEPRECATED :lower :upper :old_storable :old_nth :rfc3021 :nofqdn ); NOTE: NetAddr::IP::Util has a full complement of network address utilities to convert back and forth between binary and text. inet_aton, inet_ntoa, ipv6_aton, ipv6_ntoa ipv6_n2x, ipv6_n2d inet_any2d, inet_n2dx, inet_n2ad, inetanyto6, ipv6to4 See L<NetAddr::IP::Util> my $ip = new NetAddr::IP '127.0.0.1'; or if you prefer my $ip = NetAddr::IP->new('127.0.0.1); or from a packed IPv4 address my $ip = new_from_aton NetAddr::IP (inet_aton('127.0.0.1')); or from an octal filtered IPv4 address my $ip = new_no NetAddr::IP '127.012.0.0'; print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ; if ($ip->within(new NetAddr::IP "127.0.0.0", "255.0.0.0")) { print "Is a loopback address\n"; } # This prints 127.0.0.1/32 print "You can also say $ip...\n"; * The following four functions return ipV6 representations of: :: = Zeros(); FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones(); FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask(); ::FFFF:FFFF = V4net(); Will also return an ipV4 or ipV6 representation of a resolvable Fully Qualified Domanin Name (FQDN). ###### DEPRECATED, will be remove in version 5 ############ * To accept addresses in the format as returned by inet_aton, invoke the module as: use NetAddr::IP qw(:aton); ###### USE new_from_aton instead ########################## * To enable usage of legacy data files containing NetAddr::IP objects stored using the L<Storable> module. use NetAddr::IP qw(:old_storable); * To compact many smaller subnets (see: C<$me-E<gt>compact($addr1,$addr2,...)> @compacted_object_list = Compact(@object_list) * Return a reference to list of C<NetAddr::IP> subnets of C<$masklen> mask length, when C<$number> or more addresses from C<@list_of_subnets> are found to be contained in said subnet. $arrayref = Coalesce($masklen, $number, @list_of_subnets) * By default B<NetAddr::IP> functions and methods return string IPv6 addresses in uppercase. To change that to lowercase: NOTE: the AUGUST 2010 RFC5952 states: 4.3. Lowercase The characters "a", "b", "c", "d", "e", and "f" in an IPv6 address MUST be represented in lowercase. It is recommended that all NEW applications using NetAddr::IP be invoked as shown on the next line. use NetAddr::IP qw(:lower); * To ensure the current IPv6 string case behavior even if the default changes: use NetAddr::IP qw(:upper); * To set a limit on the size of B<nets> processed or returned by NetAddr::IP. Set the maximum number of nets beyond which NetAddr::IP will return an error as a power of 2 (default 16 or 65536 nets). Each 2**16 consumes approximately 4 megs of memory. A 2**20 consumes 64 megs of memory, A 2**24 consumes 1 gigabyte of memory. use NetAddr::IP qw(netlimit); netlimit 20; The maximum B<netlimit> allowed is 2**24. Attempts to set limits below the default of 16 or above the maximum of 24 are ignored. Returns true on success, otherwise C<undef>. =cut $_netlimit = 2 ** 16; # default sub netlimit($) { return undef unless $_[0]; return undef if $_[0] =~ /\D/; return undef if $_[0] < 16; return undef if $_[0] > 24; $_netlimit = 2 ** $_[0]; }; =head1 INSTALLATION Un-tar the distribution in an appropriate directory and type: perl Makefile.PL make make test make install B<NetAddr::IP> depends on B<NetAddr::IP::Util> which installs by default with its primary functions compiled using Perl's XS extensions to build a C library. If you do not have a C complier available or would like the slower Pure Perl version for some other reason, then type: perl Makefile.PL -noxs make make test make install =head1 DESCRIPTION This module provides an object-oriented abstraction on top of IP addresses or IP subnets that allows for easy manipulations. Version 4.xx of NetAddr::IP will work with older versions of Perl and is compatible with Math::BigInt. The internal representation of all IP objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects may be freely mixed. =head2 Overloaded Operators Many operators have been overloaded, as described below: =cut ############################################# # These are the overload methods, placed here # for convenience. ############################################# use overload '@{}' => sub { return [ $_[0]->hostenum ]; }; =pod =over =item B<Assignment (C<=>)> Has been optimized to copy one NetAddr::IP object to another very quickly. =item B<C<-E<gt>copy()>> The B<assignment (C<=>)> operation is only put in to operation when the copied object is further mutated by another overloaded operation. See L<overload> B<SPECIAL SYMBOLS FOR "use overload"> for details. B<C<-E<gt>copy()>> actually creates a new object when called. =item B<Stringification> An object can be used just as a string. For instance, the following code my $ip = new NetAddr::IP '192.168.1.123'; print "$ip\n"; Will print the string 192.168.1.123/32. =item B<Equality> You can test for equality with either C<eq> or C<==>. C<eq> allows comparison with arbitrary strings as well as NetAddr::IP objects. The following example: if (NetAddr::IP->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8') { print "Yes\n"; } will print out "Yes". Comparison with C<==> requires both operands to be NetAddr::IP objects. In both cases, a true value is returned if the CIDR representation of the operands is equal. =item B<Comparison via E<gt>, E<lt>, E<gt>=, E<lt>=, E<lt>=E<gt> and C<cmp>> Internally, all network objects are represented in 128 bit format. The numeric representation of the network is compared through the corresponding operation. Comparisons are tried first on the address portion of the object and if that is equal then the NUMERIC cidr portion of the masks are compared. This leads to the counterintuitive result that /24 > /16 Comparison should not be done on netaddr objects with different CIDR as this may produce indeterminate - unexpected results, rather the determination of which netblock is larger or smaller should be done by comparing $ip1->masklen <=> $ip2->masklen =item B<Addition of a constant (C<+>)> Add a 32 bit signed constant to the address part of a NetAddr object. This operation changes the address part to point so many hosts above the current objects start address. For instance, this code: print NetAddr::IP->new('127.0.0.1/8') + 5; will output 127.0.0.6/8. The address will wrap around at the broadcast back to the network address. This code: print NetAddr::IP->new('10.0.0.1/24') + 255; outputs 10.0.0.0/24. Returns the the unchanged object when the constant is missing or out of range. 2147483647 <= constant >= -2147483648 =item B<Subtraction of a constant (C<->)> The complement of the addition of a constant. =item B<Difference (C<->)> Returns the difference between the address parts of two NetAddr::IP objects address parts as a 32 bit signed number. Returns B<undef> if the difference is out of range. (See range restrictions on Addition above) =item B<Auto-increment> Auto-incrementing a NetAddr::IP object causes the address part to be adjusted to the next host address within the subnet. It will wrap at the broadcast address and start again from the network address. =item B<Auto-decrement> Auto-decrementing a NetAddr::IP object performs exactly the opposite of auto-incrementing it, as you would expect. =cut ############################################# # End of the overload methods. ############################################# # Preloaded methods go here. =pod =back =head2 Serializing and Deserializing This module defines hooks to collaborate with L<Storable> for serializing C<NetAddr::IP> objects, through compact and human readable strings. You can revert to the old format by invoking this module as use NetAddr::IP ':old_storable'; You must do this if you have legacy data files containing NetAddr::IP objects stored using the L<Storable> module. =cut my $full_format = "%04X:%04X:%04X:%04X:%04X:%04X:%D.%D.%D.%D"; my $full6_format = "%04X:%04X:%04X:%04X:%04X:%04X:%04X:%04X"; sub import { if (grep { $_ eq ':old_storable' } @_) { @_ = grep { $_ ne ':old_storable' } @_; } else { *{STORABLE_freeze} = sub { my $self = shift; return $self->cidr(); # use stringification }; *{STORABLE_thaw} = sub { my $self = shift; my $cloning = shift; # Not used my $serial = shift; my $ip = new NetAddr::IP $serial; $self->{addr} = $ip->{addr}; $self->{mask} = $ip->{mask}; $self->{isv6} = $ip->{isv6}; return; }; } if (grep { $_ eq ':aton' } @_) { $NetAddr::IP::Lite::Accept_Binary_IP = 1; @_ = grep { $_ ne ':aton' } @_; } if (grep { $_ eq ':old_nth' } @_) { $NetAddr::IP::Lite::Old_nth = 1; @_ = grep { $_ ne ':old_nth' } @_; } if (grep { $_ eq ':nofqdn'} @_) { $NetAddr::IP::NetAddr::IP::Lite::NoFQDN = 1; @_ = grep { $_ ne ':nofqdn' } @_; } if (grep { $_ eq ':lower' } @_) { $full_format = lc($full_format); $full6_format = lc($full6_format); NetAddr::IP::Util::lower(); @_ = grep { $_ ne ':lower' } @_; } if (grep { $_ eq ':upper' } @_) { $full_format = uc($full_format); $full6_format = uc($full6_format); NetAddr::IP::Util::upper(); @_ = grep { $_ ne ':upper' } @_; } if (grep { $_ eq ':rfc3021' } @_) { $rfc3021 = 1; @_ = grep { $_ ne ':rfc3021' } @_; } NetAddr::IP->export_to_level(1, @_); } sub compact { return (ref $_[0] eq 'ARRAY') ? compactref($_[0]) # Compact(\@list) : @{compactref(\@_)}; # Compact(@list) or ->compact(@list) } *Compact = \&compact; sub Coalesce { return &coalesce; } sub hostenumref($) { my $r = _splitref(0,$_[0]); unless ((notcontiguous($_[0]->{mask}))[1] == 128 || ($rfc3021 && $_[0]->masklen == 31) ) { splice(@$r, 0, 1); splice(@$r, scalar @$r - 1, 1); } return $r; } sub splitref { unshift @_, 0; # mark as no reverse # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &_splitref; &_splitref; } sub rsplitref { unshift @_, 1; # mark as reversed # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &_splitref; &_splitref; } sub split { unshift @_, 0; # mark as no reverse my $rv = &_splitref; return $rv ? @$rv : (); } sub rsplit { unshift @_, 1; # mark as reversed my $rv = &_splitref; return $rv ? @$rv : (); } sub full($) { if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) { my @hex = (unpack("n8",$_[0]->{addr})); $hex[9] = $hex[7] & 0xff; $hex[8] = $hex[7] >> 8; $hex[7] = $hex[6] & 0xff; $hex[6] >>= 8; return sprintf($full_format,@hex); } else { &full6; } } sub full6($) { my @hex = (unpack("n8",$_[0]->{addr})); return sprintf($full6_format,@hex); } sub full6m($) { my @hex = (unpack("n8",$_[0]->{mask})); return sprintf($full6_format,@hex); } sub DESTROY {}; 1; __END__ sub do_prefix ($$$) { my $mask = shift; my $faddr = shift; my $laddr = shift; if ($mask > 24) { return "$faddr->[0].$faddr->[1].$faddr->[2].$faddr->[3]-$laddr->[3]"; } elsif ($mask == 24) { return "$faddr->[0].$faddr->[1].$faddr->[2]."; } elsif ($mask > 16) { return "$faddr->[0].$faddr->[1].$faddr->[2]-$laddr->[2]."; } elsif ($mask == 16) { return "$faddr->[0].$faddr->[1]."; } elsif ($mask > 8) { return "$faddr->[0].$faddr->[1]-$laddr->[1]."; } elsif ($mask == 8) { return "$faddr->[0]."; } else { return "$faddr->[0]-$laddr->[0]"; } } =pod =head2 Methods =over =item C<-E<gt>new([$addr, [ $mask|IPv6 ]])> =item C<-E<gt>new6([$addr, [ $mask]])> =item C<-E<gt>new_no([$addr, [ $mask]])> =item C<-E<gt>new_from_aton($netaddr)> =item new_cis and new_cis6 are DEPRECATED =item C<-E<gt>new_cis("$addr $mask)> =item C<-E<gt>new_cis6("$addr $mask)> The first two methods create a new address with the supplied address in C<$addr> and an optional netmask C<$mask>, which can be omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses respectively. The third method C<new_no> is exclusively for IPv4 addresses and filters improperly formatted dot quad strings for leading 0's that would normally be interpreted as octal format by NetAddr per the specifications for inet_aton. B<new_from_aton> takes a packed IPv4 address and assumes a /32 mask. This function replaces the DEPRECATED :aton functionality which is fundamentally broken. The last two methods B<new_cis> and B<new_cis6> differ from B<new> and B<new6> only in that they except the common Cisco address notation for address/mask pairs with a B<space> as a separator instead of a slash (/) These methods are DEPRECATED because the functionality is now included in the other "new" methods i.e. ->new_cis('1.2.3.0 24') or ->new_cis6('::1.2.3.0 120') C<-E<gt>new6> and C<-E<gt>new_cis6> mark the address as being in ipV6 address space even if the format would suggest otherwise. i.e. ->new6('1.2.3.4') will result in ::102:304 addresses submitted to ->new in ipV6 notation will remain in that notation permanently. i.e. ->new('::1.2.3.4') will result in ::102:304 whereas new('1.2.3.4') would print out as 1.2.3.4 See "STRINGIFICATION" below. C<$addr> can be almost anything that can be resolved to an IP address in all the notations I have seen over time. It can optionally contain the mask in CIDR notation. B<prefix> notation is understood, with the limitation that the range specified by the prefix must match with a valid subnet. Addresses in the same format returned by C<inet_aton> or C<gethostbyname> can also be understood, although no mask can be specified for them. The default is to not attempt to recognize this format, as it seems to be seldom used. To accept addresses in that format, invoke the module as in use NetAddr::IP ':aton' If called with no arguments, 'default' is assumed. If called with an empty string as the argument, returns 'undef' C<$addr> can be any of the following and possibly more... n.n n.n/mm n.n.n n.n.n/mm n.n.n.n n.n.n.n/mm 32 bit cidr notation n.n.n.n/m.m.m.m loopback, localhost, broadcast, any, default x.x.x.x/host 0xABCDEF, 0b111111000101011110, (a bcd number) a netaddr as returned by 'inet_aton' Any RFC1884 notation ::n.n.n.n ::n.n.n.n/mmm 128 bit cidr notation ::n.n.n.n/::m.m.m.m ::x:x ::x:x/mmm x:x:x:x:x:x:x:x x:x:x:x:x:x:x:x/mmm x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation loopback, localhost, unspecified, any, default ::x:x/host 0xABCDEF, 0b111111000101011110 within the limits of perl's number resolution 123456789012 a 'big' bcd number (bigger than perl likes) and Math::BigInt A Fully Qualified Domain Name which returns an ipV4 address or an ipV6 address, embodied in that order. This previously undocumented feature may be disabled with: use NetAddr::IP::Lite ':nofqdn'; If called with no arguments, 'default' is assumed. If called with an empty string as the argument, returns 'undef' =item C<-E<gt>broadcast()> Returns a new object referring to the broadcast address of a given subnet. The broadcast address has all ones in all the bit positions where the netmask has zero bits. This is normally used to address all the hosts in a given subnet. =item C<-E<gt>network()> Returns a new object referring to the network address of a given subnet. A network address has all zero bits where the bits of the netmask are zero. Normally this is used to refer to a subnet. =item C<-E<gt>addr()> Returns a scalar with the address part of the object as an IPv4 or IPv6 text string as appropriate. This is useful for printing or for passing the address part of the NetAddr::IP object to other components that expect an IP address. If the object is an ipV6 address or was created using ->new6($ip) it will be reported in ipV6 hex format otherwise it will be reported in dot quad format only if it resides in ipV4 address space. =item C<-E<gt>mask()> Returns a scalar with the mask as an IPv4 or IPv6 text string as described above. =item C<-E<gt>masklen()> Returns a scalar the number of one bits in the mask. =item C<-E<gt>bits()> Returns the width of the address in bits. Normally 32 for v4 and 128 for v6. =item C<-E<gt>version()> Returns the version of the address or subnet. Currently this can be either 4 or 6. =item C<-E<gt>cidr()> Returns a scalar with the address and mask in CIDR notation. A NetAddr::IP object I<stringifies> to the result of this function. (see comments about ->new6() and ->addr() for output formats) =item C<-E<gt>aton()> Returns the address part of the NetAddr::IP object in the same format as the C<inet_aton()> or C<ipv6_aton> function respectively. If the object was created using ->new6($ip), the address returned will always be in ipV6 format, even for addresses in ipV4 address space. =item C<-E<gt>range()> Returns a scalar with the base address and the broadcast address separated by a dash and spaces. This is called range notation. =item C<-E<gt>prefix()> Returns a scalar with the address and mask in ipV4 prefix representation. This is useful for some programs, which expect its input to be in this format. This method will include the broadcast address in the encoding. =cut # only applicable to ipV4 sub prefix($) { return undef if $_[0]->{isv6}; my $mask = (notcontiguous($_[0]->{mask}))[1]; return $_[0]->addr if $mask == 128; $mask -= 96; my @faddr = split (/\./, $_[0]->first->addr); my @laddr = split (/\./, $_[0]->broadcast->addr); return do_prefix $mask, \@faddr, \@laddr; } =item C<-E<gt>nprefix()> Just as C<-E<gt>prefix()>, but does not include the broadcast address. =cut # only applicable to ipV4 sub nprefix($) { return undef if $_[0]->{isv6}; my $mask = (notcontiguous($_[0]->{mask}))[1]; return $_[0]->addr if $mask == 128; $mask -= 96; my @faddr = split (/\./, $_[0]->first->addr); my @laddr = split (/\./, $_[0]->last->addr); return do_prefix $mask, \@faddr, \@laddr; } =pod =item C<-E<gt>numeric()> When called in a scalar context, will return a numeric representation of the address part of the IP address. When called in an array contest, it returns a list of two elements. The first element is as described, the second element is the numeric representation of the netmask. This method is essential for serializing the representation of a subnet. =item C<-E<gt>bigint()> When called in scalar context, will return a Math::BigInt representation of the address part of the IP address. When called in an array context, it returns a list of two elements, The first element is as described, the second element is the Math::BigInt representation of the netmask. =item C<-E<gt>wildcard()> When called in a scalar context, returns the wildcard bits corresponding to the mask, in dotted-quad or ipV6 format as applicable. When called in an array context, returns a two-element array. The first element, is the address part. The second element, is the wildcard translation of the mask. =cut sub wildcard($) { my $copy = $_[0]->copy; $copy->{addr} = ~ $copy->{mask}; $copy->{addr} &= V4net unless $copy->{isv6}; if (wantarray) { return ($_[0]->addr, $copy->addr); } return $copy->addr; } =pod =item C<-E<gt>short()> Returns the address part in a short or compact notation. (ie, 127.0.0.1 becomes 127.1). Works with both, V4 and V6. =cut sub _compact_v6 ($) { my $addr = shift; my @o = split /:/, $addr; return $addr unless @o and grep { $_ =~ m/^0+$/ } @o; my @candidates = (); my $start = undef; for my $i (0 .. $#o) { if (defined $start) { if ($o[$i] !~ m/^0+$/) { push @candidates, [ $start, $i - $start ]; $start = undef; } } else { $start = $i if $o[$i] =~ m/^0+$/; } } push @candidates, [$start, 8 - $start] if defined $start; my $l = (sort { $b->[1] <=> $a->[1] } @candidates)[0]; return $addr unless defined $l; $addr = $l->[0] == 0 ? '' : join ':', @o[0 .. $l->[0] - 1]; $addr .= '::'; $addr .= join ':', @o[$l->[0] + $l->[1] .. $#o]; $addr =~ s/(^|:)0{1,3}/$1/g; return $addr; } #sub _old_compV6 { # my @addr = split(':',shift); # my $found = 0; # my $v; # foreach(0..$#addr) { # ($v = $addr[$_]) =~ s/^0+//; # $addr[$_] = $v || 0; # } # @_ = reverse(1..$#addr); # foreach(@_) { # if ($addr[$_] || $addr[$_ -1]) { # last if $found; # next; # } # $addr[$_] = $addr[$_ -1] = ''; # $found = '1'; # } # (my $rv = join(':',@addr)) =~ s/:+:/::/; # return $rv; #} # thanks to Rob Riepel <riepel@networking.Stanford.EDU> # for this faster and more compact solution 11-17-08 sub _compV6 ($) { my $ip = shift; return $ip unless my @candidates = $ip =~ /((?:^|:)0(?::0)+(?::|$))/g; my $longest = (sort { length($b) <=> length($a) } @candidates)[0]; $ip =~ s/$longest/::/; return $ip; } sub short($) { my $addr = $_[0]->addr; if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) { my @o = split(/\./, $addr, 4); splice(@o, 1, 2) if $o[1] == 0 and $o[2] == 0; return join '.', @o; } return _compV6($addr); } =item C<-E<gt>canon()> Returns the address part in canonical notation as a string. For ipV4, this is dotted quad, and is the same as the return value from "->addr()". For ipV6 it is as per RFC5952, and is the same as the LOWER CASE value returned by "->short()". =cut sub canon($) { my $addr = $_[0]->addr; return $_[0]->{isv6} ? lc _compV6($addr) : $addr; } =item C<-E<gt>full()> Returns the address part in FULL notation for ipV4 and ipV6 respectively. i.e. for ipV4 0000:0000:0000:0000:0000:0000:127.0.0.1 for ipV6 0000:0000:0000:0000:0000:0000:0000:0000 To force ipV4 addresses into full ipV6 format use: =item C<-E<gt>full6()> Returns the address part in FULL ipV6 notation =item C<-E<gt>full6m()> Returns the mask part in FULL ipV6 notation =item C<$me-E<gt>contains($other)> Returns true when C<$me> completely contains C<$other>. False is returned otherwise and C<undef> is returned if C<$me> and C<$other> are not both C<NetAddr::IP> objects. =item C<$me-E<gt>within($other)> The complement of C<-E<gt>contains()>. Returns true when C<$me> is completely contained within C<$other>. Note that C<$me> and C<$other> must be C<NetAddr::IP> objects. =item C-E<gt>is_rfc1918()> Returns true when C<$me> is an RFC 1918 address. 10.0.0.0 - 10.255.255.255 (10/8 prefix) 172.16.0.0 - 172.31.255.255 (172.16/12 prefix) 192.168.0.0 - 192.168.255.255 (192.168/16 prefix) =item C<-E<gt>is_local()> Returns true when C<$me> is a local network address. i.e. ipV4 127.0.0.0 - 127.255.255.255 or ipV6 === ::1 =item C<-E<gt>splitref($bits,[optional $bits1,$bits2,...])> Returns a reference to a list of objects, representing subnets of C<bits> mask produced by splitting the original object, which is left unchanged. Note that C<$bits> must be longer than the original mask in order for it to be splittable. ERROR conditions: ->splitref will DIE with the message 'netlimit exceeded' if the number of return objects exceeds 'netlimit'. See function 'netlimit' above (default 2**16 or 65536 nets). ->splitref returns undef when C<bits> or the (bits list) will not fit within the original object. ->splitref returns undef if a supplied ipV4, ipV6, or NetAddr mask in inappropriately formatted, B<bits> may be a CIDR mask, a dot quad or ipV6 string or a NetAddr::IP object. If C<bits> is missing, the object is split for into all available addresses within the ipV4 or ipV6 object ( auto-mask of CIDR 32, 128 respectively ). With optional additional C<bits> list, the original object is split into parts sized based on the list. NOTE: a short list will replicate the last item. If the last item is too large to for what remains of the object after splitting off the first parts of the list, a "best fits" list of remaining objects will be returned based on an increasing sort of the CIDR values of the C<bits> list. i.e. my $ip = new NetAddr::IP('192.168.0.0/24'); my $objptr = $ip->split(28, 29, 28, 29, 26); has split plan 28 29 28 29 26 26 26 28 and returns this list of objects 192.168.0.0/28 192.168.0.16/29 192.168.0.24/28 192.168.0.40/29 192.168.0.48/26 192.168.0.112/26 192.168.0.176/26 192.168.0.240/28 NOTE: that /26 replicates twice beyond the original request and /28 fills the remaining return object requirement. =item C<-E<gt>rsplitref($bits,[optional $bits1,$bits2,...])> C<-E<gt>rsplitref> is the same as C<-E<gt>splitref> above except that the split plan is applied to the original object in reverse order. i.e. my $ip = new NetAddr::IP('192.168.0.0/24'); my @objects = $ip->split(28, 29, 28, 29, 26); has split plan 28 26 26 26 29 28 29 28 and returns this list of objects 192.168.0.0/28 192.168.0.16/26 192.168.0.80/26 192.168.0.144/26 192.168.0.208/29 192.168.0.216/28 192.168.0.232/29 192.168.0.240/28 =item C<-E<gt>split($bits,[optional $bits1,$bits2,...])> Similar to C<-E<gt>splitref> above but returns the list rather than a list reference. You may not want to use this if a large number of objects is expected. =item C<-E<gt>rsplit($bits,[optional $bits1,$bits2,...])> Similar to C<-E<gt>rsplitref> above but returns the list rather than a list reference. You may not want to use this if a large number of objects is expected. =cut # input: $naip, # @bits, list of masks for splits # # returns: empty array request will not fit in submitted net # (\@bits,undef) if there is just one plan item i.e. return original net # (\@bits,\%masks) for a real plan # sub _splitplan { my($ip,@bits) = @_; my $addr = $ip->addr(); my $isV6 = $ip->{isv6}; unless (@bits) { $bits[0] = $isV6 ? 128 : 32; } my $basem = $ip->masklen(); my(%nets,$dif); my $denom = 0; my($x,$maddr); foreach(@bits) { if (ref $_) { # is a NetAddr::IP $x = $_->{isv6} ? $_->{addr} : $_->{addr} | V4mask; ($x,$maddr) = notcontiguous($x); return () if $x; # spurious bits $_ = $isV6 ? $maddr : $maddr - 96; } elsif ( $_ =~ /^d+$/ ) { # is a negative number of the form -nnnn ; } elsif ($_ = NetAddr::IP->new($addr,$_,$isV6)) { # will be undefined if bad mask and will fall into oops! $_ = $_->masklen(); } else { return (); # oops! } $dif = $_ - $basem; # for normalization return () if $dif < 0; # overange nets not allowed return (\@bits,undef) unless ($dif || $#bits); # return if original net = mask alone $denom = $dif if $dif > $denom; next if exists $nets{$_}; $nets{$_} = $_ - $basem; # for normalization } # $denom is the normalization denominator, since these are all exponents # normalization can use add/subtract to accomplish normalization # # keys of %nets are the masks used by this split # values of %nets are the normalized weighting for # calculating when the split is "full" or complete # %masks values contain the actual masks for each split subnet # @bits contains the masks in the order the user actually wants them # my %masks; # calculate masks my $maskbase = $isV6 ? 128 : 32; foreach( keys %nets ) { $nets{$_} = 2 ** ($denom - $nets{$_}); $masks{$_} = shiftleft(Ones, $maskbase - $_); } my @plan; my $idx = 0; $denom = 2 ** $denom; PLAN: while ($denom > 0) { # make a net plan my $nexmask = ($idx < $#bits) ? $bits[$idx] : $bits[$#bits]; ++$idx; unless (($denom -= $nets{$nexmask}) < 0) { return () if (push @plan, $nexmask) > $_netlimit; next; } # a fractional net is needed that is not in the mask list or the replicant $denom += $nets{$nexmask}; # restore mistake TRY: foreach (sort { $a <=> $b } keys %nets) { next TRY if $nexmask > $_; do { next TRY if $denom - $nets{$_} < 0; return () if (push @plan, $_) > $_netlimit; $denom -= $nets{$_}; } while $denom; } die 'ERROR: miscalculated weights' if $denom; } return () if $idx < @bits; # overrange original subnet request return (\@plan,\%masks); } # input: $rev, # t/f # $naip, # @bits # list of masks for split # sub _splitref { my $rev = shift; my($plan,$masks) = &_splitplan; # bug report 82719 croak("netmask error: overrange or spurious bits") unless defined $plan; # return undef unless $plan; my $net = $_[0]->network(); return [$net] unless $masks; my $addr = $net->{addr}; my $isV6 = $net->{isv6}; my @plan = $rev ? reverse @$plan : @$plan; # print "plan @plan\n"; # create splits my @ret; while ($_ = shift @plan) { my $mask = $masks->{$_}; push @ret, $net->_new($addr,$mask,$isV6); last unless @plan; $addr = (sub128($addr,$mask))[1]; } return \@ret; } =pod =item C<-E<gt>hostenum()> Returns the list of hosts within a subnet. ERROR conditions: ->hostenum will DIE with the message 'netlimit exceeded' if the number of return objects exceeds 'netlimit'. See function 'netlimit' above (default 2**16 or 65536 nets). =cut sub hostenum ($) { return @{$_[0]->hostenumref}; } =pod =item C<-E<gt>hostenumref()> Faster version of C<-E<gt>hostenum()>, returning a reference to a list. NOTE: hostenum and hostenumref report zero (0) useable hosts in a /31 network. This is the behavior expected prior to RFC 3021. To report 2 useable hosts for use in point-to-point networks, use B<:rfc3021> tag. use NetAddr::IP qw(:rfc3021); This will cause hostenum and hostenumref to return two (2) useable hosts in a /31 network. =item C<$me-E<gt>compact($addr1, $addr2, ...)> =item C<@compacted_object_list = Compact(@object_list)> Given a list of objects (including C<$me>), this method will compact all the addresses and subnets into the largest (ie, least specific) subnets possible that contain exactly all of the given objects. Note that in versions prior to 3.02, if fed with the same IP subnets multiple times, these subnets would be returned. From 3.02 on, a more "correct" approach has been adopted and only one address would be returned. Note that C<$me> and all C<$addr>'s must be C<NetAddr::IP> objects. =item C<$me-E<gt>compactref(\@list)> =item C<$compacted_object_list = Compact(\@list)> As usual, a faster version of C<-E<gt>compact()> that returns a reference to a list. Note that this method takes a reference to a list instead. Note that C<$me> must be a C<NetAddr::IP> object. =cut sub compactref($) { # my @r = sort { NetAddr::IP::Lite::comp_addr_mask($a,$b) } @{$_[0]} # use overload 'cmp' function # or return []; # return [] unless @r; my @r; { my $unr = []; my $args = $_[0]; if (ref $_[0] eq __PACKAGE__ and ref $_[1] eq 'ARRAY') { # ->compactref(\@list) # $unr = [$_[0], @{$_[1]}]; # keeping structures intact } else { # Compact(@list) or ->compact(@list) or Compact(\@list) # $unr = $args; } return [] unless @$unr; foreach(@$unr) { $_->{addr} = $_->network->{addr}; } @r = sort @$unr; } my $changed; do { $changed = 0; for(my $i=0; $i <= $#r -1;$i++) { if ($r[$i]->contains($r[$i +1])) { splice(@r,$i +1,1); ++$changed; --$i; } elsif ((notcontiguous($r[$i]->{mask}))[1] == (notcontiguous($r[$i +1]->{mask}))[1]) { # masks the same if (hasbits($r[$i]->{addr} ^ $r[$i +1]->{addr})) { # if not the same netblock my $upnet = $r[$i]->copy; $upnet->{mask} = shiftleft($upnet->{mask},1); if ($upnet->contains($r[$i +1])) { # adjacent nets in next net up $r[$i] = $upnet; splice(@r,$i +1,1); ++$changed; --$i; } } else { # identical nets splice(@r,$i +1,1); ++$changed; --$i; } } } } while $changed; return \@r; } =pod =item C<$me-E<gt>coalesce($masklen, $number, @list_of_subnets)> =item C<$arrayref = Coalesce($masklen,$number,@list_of_subnets)> Will return a reference to list of C<NetAddr::IP> subnets of C<$masklen> mask length, when C<$number> or more addresses from C<@list_of_subnets> are found to be contained in said subnet. Subnets from C<@list_of_subnets> with a mask shorter than C<$masklen> are passed "as is" to the return list. Subnets from C<@list_of_subnets> with a mask longer than C<$masklen> will be counted (actually, the number of IP addresses is counted) towards C<$number>. Called as a method, the array will include C<$me>. WARNING: the list of subnet must be the same type. i.e ipV4 or ipV6 =cut sub coalesce { my $masklen = shift; if (ref $masklen && ref $masklen eq __PACKAGE__ ) { # if called as a method push @_,$masklen; $masklen = shift; } my $number = shift; # Addresses are at @_ return [] unless @_; my %ret = (); my $type = $_[0]->{isv6}; return [] unless defined $type; for my $ip (@_) { return [] unless $ip->{isv6} == $type; $type = $ip->{isv6}; my $n = NetAddr::IP->new($ip->addr . '/' . $masklen)->network; if ($ip->masklen > $masklen) { $ret{$n} += $ip->num + $NetAddr::IP::Lite::Old_nth; } } my @ret = (); # Add to @ret any arguments with netmasks longer than our argument for my $c (sort { $a->masklen <=> $b->masklen } grep { $_->masklen <= $masklen } @_) { next if grep { $_->contains($c) } @ret; push @ret, $c->network; } # Now add to @ret all the subnets with more than $number hits for my $c (map { new NetAddr::IP $_ } grep { $ret{$_} >= $number } keys %ret) { next if grep { $_->contains($c) } @ret; push @ret, $c; } return \@ret; } =pod =item C<-E<gt>first()> Returns a new object representing the first usable IP address within the subnet (ie, the first host address). =item C<-E<gt>last()> Returns a new object representing the last usable IP address within the subnet (ie, one less than the broadcast address). =item C<-E<gt>nth($index)> Returns a new object representing the I<n>-th usable IP address within the subnet (ie, the I<n>-th host address). If no address is available (for example, when the network is too small for C<$index> hosts), C<undef> is returned. Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite implements C<-E<gt>nth($index)> and C<-E<gt>num()> exactly as the documentation states. Previous versions behaved slightly differently and not in a consistent manner. See the README file for details. To use the old behavior for C<-E<gt>nth($index)> and C<-E<gt>num()>: use NetAddr::IP::Lite qw(:old_nth); old behavior: NetAddr::IP->new('10/32')->nth(0) == undef NetAddr::IP->new('10/32')->nth(1) == undef NetAddr::IP->new('10/31')->nth(0) == undef NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31 NetAddr::IP->new('10/30')->nth(0) == undef NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30 NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30 NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30 Note that in each case, the broadcast address is represented in the output set and that the 'zero'th index is alway undef except for a point-to-point /31 or /127 network where there are exactly two addresses in the network. new behavior: NetAddr::IP->new('10/32')->nth(0) == 10.0.0.0/32 NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32 NetAddr::IP->new('10/31')->nth(0) == 10.0.0.0/31 NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31 NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30 NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30 NetAddr::IP->new('10/30')->nth(2) == undef Note that a /32 net always has 1 usable address while a /31 has exactly two usable addresses for point-to-point addressing. The first index (0) returns the address immediately following the network address except for a /31 or /127 when it return the network address. =item C<-E<gt>num()> As of version 4.42 of NetAddr::IP and version 1.27 of NetAddr::IP::Lite a /31 and /127 with return a net B<num> value of 2 instead of 0 (zero) for point-to-point networks. Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite return the number of usable IP addresses within the subnet, not counting the broadcast or network address. Previous versions worked only for ipV4 addresses, returned a maximum span of 2**32 and returned the number of IP addresses not counting the broadcast address. (one greater than the new behavior) To use the old behavior for C<-E<gt>nth($index)> and C<-E<gt>num()>: use NetAddr::IP::Lite qw(:old_nth); WARNING: NetAddr::IP will calculate and return a numeric string for network ranges as large as 2**128. These values are TEXT strings and perl can treat them as integers for numeric calculations. Perl on 32 bit platforms only handles integer numbers up to 2**32 and on 64 bit platforms to 2**64. If you wish to manipulate numeric strings returned by NetAddr::IP that are larger than 2**32 or 2**64, respectively, you must load additional modules such as Math::BigInt, bignum or some similar package to do the integer math. =item C<-E<gt>re()> Returns a Perl regular expression that will match an IP address within the given subnet. Defaults to ipV4 notation. Will return an ipV6 regex if the address in not in ipV4 space. =cut sub re ($) { return &re6 unless isIPv4($_[0]->{addr}); my $self = shift->network; # Insure a "zero" host part my ($addr, $mlen) = ($self->addr, $self->masklen); my @o = split('\.', $addr, 4); my $octet= '(?:[0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'; my @r = @o; my $d; # for my $i (0 .. $#o) # { # warn "# $self: $r[$i] == $o[$i]\n"; # } if ($mlen != 32) { if ($mlen > 24) { $d = 2 ** (32 - $mlen) - 1; $r[3] = '(?:' . join('|', ($o[3]..$o[3] + $d)) . ')'; } else { $r[3] = $octet; if ($mlen > 16) { $d = 2 ** (24 - $mlen) - 1; $r[2] = '(?:' . join('|', ($o[2]..$o[2] + $d)) . ')'; } else { $r[2] = $octet; if ($mlen > 8) { $d = 2 ** (16 - $mlen) - 1; $r[1] = '(?:' . join('|', ($o[1]..$o[1] + $d)) . ')'; } else { $r[1] = $octet; if ($mlen > 0) { $d = 2 ** (8 - $mlen) - 1; $r[0] = '(?:' . join('|', ($o[0] .. $o[0] + $d)) . ')'; } else { $r[0] = $octet; } } } } } ### no digit before nor after (look-behind, look-ahead) return "(?:(?<![0-9])$r[0]\\.$r[1]\\.$r[2]\\.$r[3](?![0-9]))"; } =item C<-E<gt>re6()> Returns a Perl regular expression that will match an IP address within the given subnet. Always returns an ipV6 regex. =cut sub re6($) { my @net = split('',sprintf("%04X%04X%04X%04X%04X%04X%04X%04X",unpack('n8',$_[0]->network->{addr}))); my @brd = split('',sprintf("%04X%04X%04X%04X%04X%04X%04X%04X",unpack('n8',$_[0]->broadcast->{addr}))); my @dig; foreach(0..$#net) { my $n = $net[$_]; my $b = $brd[$_]; my $m; if ($n.'' eq $b.'') { if ($n =~ /\d/) { push @dig, $n; } else { push @dig, '['.(lc $n).$n.']'; } } else { my $n = $net[$_]; my $b = $brd[$_]; if ($n.'' eq 0 && $b =~ /F/) { push @dig, 'x'; } elsif ($n =~ /\d/ && $b =~ /\d/) { push @dig, '['.$n.'-'.$b.']'; } elsif ($n =~ /[A-F]/ && $b =~ /[A-F]/) { $n .= '-'.$b; push @dig, '['.(lc $n).$n.']'; } elsif ($n =~ /\d/ && $b =~ /[A-F]/) { $m = ($n == 9) ? 9 : $n .'-9'; if ($b =~ /A/) { $m .= 'aA'; } else { $b = 'A-'. $b; $m .= (lc $b). $b; } push @dig, '['.$m.']'; } elsif ($n =~ /[A-F]/ && $b =~ /\d/) { if ($n =~ /A/) { $m = 'aA'; } else { $n .= '-F'; $m = (lc $n).$n; } if ($b == 9) { $m .= 9; } else { $m .= $b .'-9'; } push @dig, '['.$m.']'; } } } my @grp; do { my $grp = join('',splice(@dig,0,4)); if ($grp =~ /^(0+)/) { my $l = length($1); if ($l == 4) { $grp = '0{1,4}'; } else { $grp =~ s/^${1}/0\{0,$l\}/; } } if ($grp =~ /(x+)$/) { my $l = length($1); if ($l == 4) { $grp = '[0-9a-fA-F]{1,4}'; } else { $grp =~ s/x+/\[0\-9a\-fA\-F\]\{$l\}/; } } push @grp, $grp; } while @dig > 0; return '('. join(':',@grp) .')'; } sub mod_version { return $VERSION; &Compact; # suppress warnings about these symbols &Coalesce; &STORABLE_freeze; &STORABLE_thaw; } =pod =back =head1 EXPORT_OK Compact Coalesce Zeros Ones V4mask V4net netlimit =head1 NOTES / BUGS ... FEATURES NetAddr::IP only runs in Pure Perl mode on Windows boxes because I don't have the resources or know how to get the "configure" stuff working in the Windows environment. Volunteers WELCOME to port the "C" portion of this module to Windows. =head1 HISTORY =over 4 See the Changes file =back =head1 AUTHORS Luis E. Muñoz E<lt>luismunoz@cpan.orgE<gt>, Michael Robinton E<lt>michael@bizsystems.comE<gt> =head1 WARRANTY This software comes with the same warranty as Perl itself (ie, none), so by using it you accept any and all the liability. =head1 COPYRIGHT This software is (c) Luis E. Muñoz, 1999 - 2007, and (c) Michael Robinton, 2006 - 2014. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or b) the "Artistic License" which comes with this distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA. or visit their web page on the internet at: http://www.gnu.org/copyleft/gpl.html. =head1 SEE ALSO perl(1) L<NetAddr::IP::Lite>, L<NetAddr::IP::Util>, L<NetAddr::IP::InetBase> =cut 1; PK � �[ lib/NetAddr/.existsnu �[��� PK � �[~t�� � ! lib/auto/NetAddr/IP/compactref.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1191 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/compactref.al)" sub compactref($) { # my @r = sort { NetAddr::IP::Lite::comp_addr_mask($a,$b) } @{$_[0]} # use overload 'cmp' function # or return []; # return [] unless @r; my @r; { my $unr = []; my $args = $_[0]; if (ref $_[0] eq __PACKAGE__ and ref $_[1] eq 'ARRAY') { # ->compactref(\@list) # $unr = [$_[0], @{$_[1]}]; # keeping structures intact } else { # Compact(@list) or ->compact(@list) or Compact(\@list) # $unr = $args; } return [] unless @$unr; foreach(@$unr) { $_->{addr} = $_->network->{addr}; } @r = sort @$unr; } my $changed; do { $changed = 0; for(my $i=0; $i <= $#r -1;$i++) { if ($r[$i]->contains($r[$i +1])) { splice(@r,$i +1,1); ++$changed; --$i; } elsif ((notcontiguous($r[$i]->{mask}))[1] == (notcontiguous($r[$i +1]->{mask}))[1]) { # masks the same if (hasbits($r[$i]->{addr} ^ $r[$i +1]->{addr})) { # if not the same netblock my $upnet = $r[$i]->copy; $upnet->{mask} = shiftleft($upnet->{mask},1); if ($upnet->contains($r[$i +1])) { # adjacent nets in next net up $r[$i] = $upnet; splice(@r,$i +1,1); ++$changed; --$i; } } else { # identical nets splice(@r,$i +1,1); ++$changed; --$i; } } } } while $changed; return \@r; } # end of NetAddr::IP::compactref 1; PK � �[y���I I lib/auto/NetAddr/IP/hostenum.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1145 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/hostenum.al)" sub hostenum ($) { return @{$_[0]->hostenumref}; } # end of NetAddr::IP::hostenum 1; PK � �[ lib/auto/NetAddr/IP/Lite/.existsnu �[��� PK � �[C�� � � lib/auto/NetAddr/IP/_splitref.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1103 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/_splitref.al)" # input: $rev, # t/f # $naip, # @bits # list of masks for split # sub _splitref { my $rev = shift; my($plan,$masks) = &_splitplan; # bug report 82719 croak("netmask error: overrange or spurious bits") unless defined $plan; # return undef unless $plan; my $net = $_[0]->network(); return [$net] unless $masks; my $addr = $net->{addr}; my $isV6 = $net->{isv6}; my @plan = $rev ? reverse @$plan : @$plan; # print "plan @plan\n"; # create splits my @ret; while ($_ = shift @plan) { my $mask = $masks->{$_}; push @ret, $net->_new($addr,$mask,$isV6); last unless @plan; $addr = (sub128($addr,$mask))[1]; } return \@ret; } # end of NetAddr::IP::_splitref 1; PK � �[�_��V V lib/auto/NetAddr/IP/re6.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1485 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/re6.al)" sub re6($) { my @net = split('',sprintf("%04X%04X%04X%04X%04X%04X%04X%04X",unpack('n8',$_[0]->network->{addr}))); my @brd = split('',sprintf("%04X%04X%04X%04X%04X%04X%04X%04X",unpack('n8',$_[0]->broadcast->{addr}))); my @dig; foreach(0..$#net) { my $n = $net[$_]; my $b = $brd[$_]; my $m; if ($n.'' eq $b.'') { if ($n =~ /\d/) { push @dig, $n; } else { push @dig, '['.(lc $n).$n.']'; } } else { my $n = $net[$_]; my $b = $brd[$_]; if ($n.'' eq 0 && $b =~ /F/) { push @dig, 'x'; } elsif ($n =~ /\d/ && $b =~ /\d/) { push @dig, '['.$n.'-'.$b.']'; } elsif ($n =~ /[A-F]/ && $b =~ /[A-F]/) { $n .= '-'.$b; push @dig, '['.(lc $n).$n.']'; } elsif ($n =~ /\d/ && $b =~ /[A-F]/) { $m = ($n == 9) ? 9 : $n .'-9'; if ($b =~ /A/) { $m .= 'aA'; } else { $b = 'A-'. $b; $m .= (lc $b). $b; } push @dig, '['.$m.']'; } elsif ($n =~ /[A-F]/ && $b =~ /\d/) { if ($n =~ /A/) { $m = 'aA'; } else { $n .= '-F'; $m = (lc $n).$n; } if ($b == 9) { $m .= 9; } else { $m .= $b .'-9'; } push @dig, '['.$m.']'; } } } my @grp; do { my $grp = join('',splice(@dig,0,4)); if ($grp =~ /^(0+)/) { my $l = length($1); if ($l == 4) { $grp = '0{1,4}'; } else { $grp =~ s/^${1}/0\{0,$l\}/; } } if ($grp =~ /(x+)$/) { my $l = length($1); if ($l == 4) { $grp = '[0-9a-fA-F]{1,4}'; } else { $grp =~ s/x+/\[0\-9a\-fA\-F\]\{$l\}/; } } push @grp, $grp; } while @dig > 0; return '('. join(':',@grp) .')'; } # end of NetAddr::IP::re6 1; PK � �[Ed�f f lib/auto/NetAddr/IP/coalesce.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1274 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/coalesce.al)" sub coalesce { my $masklen = shift; if (ref $masklen && ref $masklen eq __PACKAGE__ ) { # if called as a method push @_,$masklen; $masklen = shift; } my $number = shift; # Addresses are at @_ return [] unless @_; my %ret = (); my $type = $_[0]->{isv6}; return [] unless defined $type; for my $ip (@_) { return [] unless $ip->{isv6} == $type; $type = $ip->{isv6}; my $n = NetAddr::IP->new($ip->addr . '/' . $masklen)->network; if ($ip->masklen > $masklen) { $ret{$n} += $ip->num + $NetAddr::IP::Lite::Old_nth; } } my @ret = (); # Add to @ret any arguments with netmasks longer than our argument for my $c (sort { $a->masklen <=> $b->masklen } grep { $_->masklen <= $masklen } @_) { next if grep { $_->contains($c) } @ret; push @ret, $c->network; } # Now add to @ret all the subnets with more than $number hits for my $c (map { new NetAddr::IP $_ } grep { $ret{$_} >= $number } keys %ret) { next if grep { $_->contains($c) } @ret; push @ret, $c; } return \@ret; } # end of NetAddr::IP::coalesce 1; PK � �[�� � � " lib/auto/NetAddr/IP/mod_version.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1564 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/mod_version.al)" sub mod_version { return $VERSION; &Compact; # suppress warnings about these symbols &Coalesce; &STORABLE_freeze; &STORABLE_thaw; } 1; 1; # end of NetAddr::IP::mod_version PK � �[â � ! lib/auto/NetAddr/IP/_splitplan.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1015 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/_splitplan.al)" # input: $naip, # @bits, list of masks for splits # # returns: empty array request will not fit in submitted net # (\@bits,undef) if there is just one plan item i.e. return original net # (\@bits,\%masks) for a real plan # sub _splitplan { my($ip,@bits) = @_; my $addr = $ip->addr(); my $isV6 = $ip->{isv6}; unless (@bits) { $bits[0] = $isV6 ? 128 : 32; } my $basem = $ip->masklen(); my(%nets,$dif); my $denom = 0; my($x,$maddr); foreach(@bits) { if (ref $_) { # is a NetAddr::IP $x = $_->{isv6} ? $_->{addr} : $_->{addr} | V4mask; ($x,$maddr) = notcontiguous($x); return () if $x; # spurious bits $_ = $isV6 ? $maddr : $maddr - 96; } elsif ( $_ =~ /^d+$/ ) { # is a negative number of the form -nnnn ; } elsif ($_ = NetAddr::IP->new($addr,$_,$isV6)) { # will be undefined if bad mask and will fall into oops! $_ = $_->masklen(); } else { return (); # oops! } $dif = $_ - $basem; # for normalization return () if $dif < 0; # overange nets not allowed return (\@bits,undef) unless ($dif || $#bits); # return if original net = mask alone $denom = $dif if $dif > $denom; next if exists $nets{$_}; $nets{$_} = $_ - $basem; # for normalization } # $denom is the normalization denominator, since these are all exponents # normalization can use add/subtract to accomplish normalization # # keys of %nets are the masks used by this split # values of %nets are the normalized weighting for # calculating when the split is "full" or complete # %masks values contain the actual masks for each split subnet # @bits contains the masks in the order the user actually wants them # my %masks; # calculate masks my $maskbase = $isV6 ? 128 : 32; foreach( keys %nets ) { $nets{$_} = 2 ** ($denom - $nets{$_}); $masks{$_} = shiftleft(Ones, $maskbase - $_); } my @plan; my $idx = 0; $denom = 2 ** $denom; PLAN: while ($denom > 0) { # make a net plan my $nexmask = ($idx < $#bits) ? $bits[$idx] : $bits[$#bits]; ++$idx; unless (($denom -= $nets{$nexmask}) < 0) { return () if (push @plan, $nexmask) > $_netlimit; next; } # a fractional net is needed that is not in the mask list or the replicant $denom += $nets{$nexmask}; # restore mistake TRY: foreach (sort { $a <=> $b } keys %nets) { next TRY if $nexmask > $_; do { next TRY if $denom - $nets{$_} < 0; return () if (push @plan, $_) > $_netlimit; $denom -= $nets{$_}; } while $denom; } die 'ERROR: miscalculated weights' if $denom; } return () if $idx < @bits; # overrange original subnet request return (\@plan,\%masks); } # end of NetAddr::IP::_splitplan 1; PK � �[�'�e� � lib/auto/NetAddr/IP/wildcard.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 767 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/wildcard.al)" sub wildcard($) { my $copy = $_[0]->copy; $copy->{addr} = ~ $copy->{mask}; $copy->{addr} &= V4net unless $copy->{isv6}; if (wantarray) { return ($_[0]->addr, $copy->addr); } return $copy->addr; } # end of NetAddr::IP::wildcard 1; PK � �[綵�� � * lib/auto/NetAddr/IP/InetBase/inet_any2n.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 485 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/inet_any2n.al)" sub inet_any2n($) { my($addr) = @_; $addr = '' unless $addr; $addr = '::' . $addr unless $addr =~ /:/; return ipv6_aton($addr); } # end of NetAddr::IP::InetBase::inet_any2n 1; PK � �[ ܥ�� � ) lib/auto/NetAddr/IP/InetBase/inet_ntoa.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 378 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/inet_ntoa.al)" sub inet_ntoa { die 'Bad arg length for '. __PACKAGE__ ."::inet_ntoa, length is ". length($_[0]) ." should be 4" unless length($_[0]) == 4; my @hex = (unpack("n2",$_[0])); $hex[3] = $hex[1] & 0xff; $hex[2] = $hex[1] >> 8; $hex[1] = $hex[0] & 0xff; $hex[0] >>= 8; return sprintf("%d.%d.%d.%d",@hex); } # end of NetAddr::IP::InetBase::inet_ntoa 1; PK � �[�B B * lib/auto/NetAddr/IP/InetBase/_inet_pton.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 551 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/_inet_pton.al)" sub _inet_pton { my($af,$ip) = @_; die 'Bad address family for '. __PACKAGE__ ."::inet_pton, got $af" unless $af == AF_INET6() || $af == AF_INET(); if ($af == AF_INET()) { inet_aton($ip); } else { ipv6_aton($ip); } } # end of NetAddr::IP::InetBase::_inet_pton 1; PK � �[G�~V� � ) lib/auto/NetAddr/IP/InetBase/inet_n2dx.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 507 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/inet_n2dx.al)" sub inet_n2dx($) { my($nadr) = @_; if (isAnyIPv4($nadr)) { local $1; ipv6_n2d($nadr) =~ /([^:]+)$/; return $1; } return ipv6_n2x($nadr); } # end of NetAddr::IP::InetBase::inet_n2dx 1; PK � �[1�Д � * lib/auto/NetAddr/IP/InetBase/_inet_ntop.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 575 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/_inet_ntop.al)" sub _inet_ntop { my($af,$naddr) = @_; die 'Unsupported address family for '. __PACKAGE__ ."::inet_ntop, af is $af" unless $af == AF_INET6() || $af == AF_INET(); if ($af == AF_INET()) { inet_ntoa($naddr); } else { return ($case) ? lc packzeros(ipv6_n2x($naddr)) : _packzeros(ipv6_n2x($naddr)); } } # end of NetAddr::IP::InetBase::_inet_ntop 1; PK � �[��1F F * lib/auto/NetAddr/IP/InetBase/_packzeros.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 596 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/_packzeros.al)" sub _packzeros { my $x6 = shift; if ($x6 =~ /\:\:/) { # already contains :: # then re-optimize $x6 = ($x6 =~ /\:\d+\.\d+\.\d+\.\d+/) # ipv4 notation ? ? ipv6_n2d(ipv6_aton($x6)) : ipv6_n2x(ipv6_aton($x6)); } $x6 = ':'. lc $x6; # prefix : & always lower case my $d = ''; if ($x6 =~ /(.+\:)(\d+\.\d+\.\d+\.\d+)/) { # if contains dot quad $x6 = $1; # save hex piece $d = $2; # and dot quad piece } $x6 .= ':'; # suffix : $x6 =~ s/\:0+/\:0/g; # compress strings of 0's to single '0' $x6 =~ s/\:0([1-9a-f]+)/\:$1/g; # eliminate leading 0's in hex strings my @x = $x6 =~ /(?:\:0)*/g; # split only strings of :0:0..." my $m = 0; my $i = 0; for (0..$#x) { # find next longest pattern :0:0:0... my $len = length($x[$_]); next unless $len > $m; $m = $len; $i = $_; # index to first longest pattern } if ($m > 2) { # there was a string of 2 or more zeros $x6 =~ s/$x[$i]/\:/; # replace first longest :0:0:0... with "::" unless ($i) { # if it is the first match, $i = 0 $x6 = substr($x6,0,-1); # keep the leading ::, remove trailing ':' } else { $x6 = substr($x6,1,-1); # else remove leading & trailing ':' } $x6 .= ':' unless $x6 =~ /\:\:/; # restore ':' if match and we can't see it, implies trailing '::' } else { # there was no match $x6 = substr($x6,1,-1); # remove leading & trailing ':' } $x6 .= $d; # append digits if any return $case ? uc $x6 : $x6; } 1; 1; # end of NetAddr::IP::InetBase::_packzeros PK � �[7�X�� � ) lib/auto/NetAddr/IP/InetBase/inet_n2ad.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 531 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/inet_n2ad.al)" sub inet_n2ad($) { my($nadr) = @_; my $addr = ipv6_n2d($nadr); return $addr unless isAnyIPv4($nadr); local $1; $addr =~ /([^:]+)$/; return $1; } # end of NetAddr::IP::InetBase::inet_n2ad 1; PK � �[�'�=� � ) lib/auto/NetAddr/IP/InetBase/ipv6_ntoa.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 448 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/ipv6_ntoa.al)" sub ipv6_ntoa { return inet_ntop(AF_INET6(),$_[0]); } # end of NetAddr::IP::InetBase::ipv6_ntoa 1; PK � �[S}a2 2 ) lib/auto/NetAddr/IP/InetBase/ipv6_aton.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/InetBase.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::InetBase; #line 406 "../../blib/lib/NetAddr/IP/InetBase.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/InetBase/ipv6_aton.al)" sub ipv6_aton { my($ipv6) = @_; return undef unless $ipv6; local($1,$2,$3,$4,$5); if ($ipv6 =~ /^(.*:)(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/) { # mixed hex, dot-quad return undef if $2 > 255 || $3 > 255 || $4 > 255 || $5 > 255; $ipv6 = sprintf("%s%X%02X:%X%02X",$1,$2,$3,$4,$5); # convert to pure hex } my $c; return undef if $ipv6 =~ /[^:0-9a-fA-F]/ || # non-hex character (($c = $ipv6) =~ s/::/x/ && $c =~ /(?:x|:):/) || # double :: ::? $ipv6 =~ /[0-9a-fA-F]{5,}/; # more than 4 digits $c = $ipv6 =~ tr/:/:/; # count the colons return undef if $c < 7 && $ipv6 !~ /::/; if ($c > 7) { # strip leading or trailing :: return undef unless $ipv6 =~ s/^::/:/ || $ipv6 =~ s/::$/:/; return undef if --$c > 7; } while ($c++ < 7) { # expand compressed fields $ipv6 =~ s/::/:::/; } $ipv6 .= 0 if $ipv6 =~ /:$/; my @hex = split(/:/,$ipv6); foreach(0..$#hex) { $hex[$_] = hex($hex[$_] || 0); } pack("n8",@hex); } # end of NetAddr::IP::InetBase::ipv6_aton 1; PK � �[9��* * ) lib/auto/NetAddr/IP/InetBase/autosplit.ixnu �[��� # Index created by AutoSplit for ../../blib/lib/NetAddr/IP/InetBase.pm # (file acts as timestamp) package NetAddr::IP::InetBase; sub inet_ntoa ; sub ipv6_aton ; sub ipv6_ntoa ; sub inet_any2n ($); sub inet_n2dx ($); sub inet_n2ad ($); sub _inet_pton ; sub _inet_ntop ; sub _packzeros ; 1; PK � �[(��ې � ' lib/auto/NetAddr/IP/UtilPP/_bcdcheck.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 625 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_bcdcheck.al)" #=item * $bcdpacked = simple_pack($bcdtext); # #Convert a numeric string into a packed bcd string, left fill with zeros #This function is for testing only. # # input: string of decimal digits # returns: string of packed decimal digits # #Similar to pack("H*", $bcdtext); # sub _bcdcheck { my($bcd) = @_;; my $sub = (caller(1))[3]; my $len = length($bcd); die "Bad bcd number length $_ ".__PACKAGE__.":simple_pack, should be 1 to 40 digits" if $len > 40 || $len < 1; die "Bad character in decimal input string '$1' for ".__PACKAGE__.":simple_pack" if $bcd =~ /(\D)/; } # end of NetAddr::IP::UtilPP::_bcdcheck 1; PK � �[�I��� � $ lib/auto/NetAddr/IP/UtilPP/_sa128.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 207 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_sa128.al)" sub _sa128 { my($uap,$ubp,$carry) = @_; if (($$uap[3] += $$ubp[3] + $carry) > 0xffffffff) { $$uap[3] -= 4294967296; # 0x1_00000000 $carry = 1; } else { $carry = 0; } if (($$uap[2] += $$ubp[2] + $carry) > 0xffffffff) { $$uap[2] -= 4294967296; $carry = 1; } else { $carry = 0; } if (($$uap[1] += $$ubp[1] + $carry) > 0xffffffff) { $$uap[1] -= 4294967296; $carry = 1; } else { $carry = 0; } if (($$uap[0] += $$ubp[0] + $carry) > 0xffffffff) { $$uap[0] -= 4294967296; $carry = 1; } else { $carry = 0; } $carry; } # end of NetAddr::IP::UtilPP::_sa128 1; PK � �[�/� & lib/auto/NetAddr/IP/UtilPP/mask4to6.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 381 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/mask4to6.al)" sub mask4to6 { _deadlen(length($_[0]),32) if length($_[0]) != 4; # return pack('L3H8',0xffffffff,0xffffffff,0xffffffff,unpack('H8',$_[0])); return pack('L3a4',0xffffffff,0xffffffff,0xffffffff,$_[0]); } # end of NetAddr::IP::UtilPP::mask4to6 1; PK � �[ {�)f f ( lib/auto/NetAddr/IP/UtilPP/maskanyto6.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 418 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/maskanyto6.al)" sub maskanyto6 { my $naddr = shift; my $len = length($naddr); return $naddr if $len == 16; # return pack('L3H8',0xffffffff,0xffffffff,0xffffffff,unpack('H8',$naddr)) return pack('L3a4',0xffffffff,0xffffffff,0xffffffff,$naddr) if $len == 4; _deadlen($len,'32 or 128'); } # end of NetAddr::IP::UtilPP::maskanyto6 1; PK � �[M3�c� � $ lib/auto/NetAddr/IP/UtilPP/_128x2.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 145 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_128x2.al)" #=item * $rv = isIPv4($bits128); # #This function returns true if there are no on bits present in the IPv6 #portion of the 128 bit string and false otherwise. # #=cut # #sub xisIPv4 { # _deadlen(length($_[0])) # if length($_[0]) != 16; # return 0 if vec($_[0],0,32); # return 0 if vec($_[0],1,32); # return 0 if vec($_[0],2,32); # return 1; #} # multiply x 2 # sub _128x2 { my $inp = shift; $$inp[0] = ($$inp[0] << 1 & 0xffffffff) + (($$inp[1] & 0x80000000) ? 1:0); $$inp[1] = ($$inp[1] << 1 & 0xffffffff) + (($$inp[2] & 0x80000000) ? 1:0); $$inp[2] = ($$inp[2] << 1 & 0xffffffff) + (($$inp[3] & 0x80000000) ? 1:0); $$inp[3] = $$inp[3] << 1 & 0xffffffff; } # end of NetAddr::IP::UtilPP::_128x2 1; PK � �[��ps ( lib/auto/NetAddr/IP/UtilPP/slowadd128.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 198 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/slowadd128.al)" sub slowadd128 { my @ua = unpack('N4',$_[0]); my @ub = unpack('N4',$_[1]); my $carry = _sa128(\@ua,\@ub,$_[2]); return ($carry,pack('N4',@ua)) if wantarray; return $carry; } # end of NetAddr::IP::UtilPP::slowadd128 1; PK � �[ɘ� % lib/auto/NetAddr/IP/UtilPP/_128x10.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 172 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_128x10.al)" # multiply x 10 # sub _128x10 { my($a128p) = @_; _128x2($a128p); # x2 my @x2 = @$a128p; # save the x2 value _128x2($a128p); _128x2($a128p); # x8 _sa128($a128p,\@x2,0); # add for x10 } # end of NetAddr::IP::UtilPP::_128x10 1; PK � �[�4�4 4 + lib/auto/NetAddr/IP/UtilPP/notcontiguous.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 333 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/notcontiguous.al)" sub notcontiguous { _deadlen(length($_[0])) if length($_[0]) != 16; my @ua = unpack('N4', ~$_[0]); my $count; for ($count = 128;$count > 0; $count--) { last unless $ua[3] & 1; $ua[3] >>= 1; $ua[3] |= 0x80000000 if $ua[2] & 1; $ua[2] >>= 1; $ua[2] |= 0x80000000 if $ua[1] & 1; $ua[1] >>= 1; $ua[1] |= 0x80000000 if $ua[0] & 1; $ua[0] >>= 1; } my $spurious = $ua[0] | $ua[1] | $ua[2] | $ua[3]; return $spurious unless wantarray; return ($spurious,$count); } # end of NetAddr::IP::UtilPP::notcontiguous 1; PK � �[-�;� � % lib/auto/NetAddr/IP/UtilPP/ipv4to6.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 363 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/ipv4to6.al)" sub ipv4to6 { _deadlen(length($_[0]),32) if length($_[0]) != 4; # return pack('L3H8',0,0,0,unpack('H8',$_[0])); return pack('L3a4',0,0,0,$_[0]); } # end of NetAddr::IP::UtilPP::ipv4to6 1; PK � �[F ,C� � & lib/auto/NetAddr/IP/UtilPP/addconst.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 250 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/addconst.al)" sub addconst { my($a128,$const) = @_; _deadlen(length($a128)) if length($a128) != 16; unless ($const) { return (wantarray) ? ($const,$a128) : $const; } my $sign = ($const < 0) ? 0xffffffff : 0; my $b128 = pack('N4',$sign,$sign,$sign,$const); @_ = ($a128,$b128,0); # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &slowadd128; slowadd128(@_); } # end of NetAddr::IP::UtilPP::addconst 1; PK � �[x�>B� � & lib/auto/NetAddr/IP/UtilPP/_deadlen.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 117 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_deadlen.al)" sub _deadlen { my($len,$should) = @_; $len *= 8; $should = 128 unless $should; my $sub = (caller(1))[3]; die "Bad argument length for $sub, is $len, should be $should"; } # end of NetAddr::IP::UtilPP::_deadlen 1; PK � �[�'�� � % lib/auto/NetAddr/IP/UtilPP/comp128.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 484 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/comp128.al)" #=item * $onescomp = comp128($ipv6addr); # #This function is for testing, it is more efficient to use perl " ~ " #on the bit string directly. This interface to the B<C> routine is published for #module testing purposes because it is used internally in the B<sub128> routine. The #function is very fast, but calling if from perl directly is very slow. It is almost #33% faster to use B<sub128> than to do a 1's comp with perl and then call #B<add128>. In the PurePerl version, it is a call to # # sub {return ~ $_[0]}; # #=cut sub comp128 { _deadlen(length($_[0])) if length($_[0]) != 16; return ~ $_[0]; } # end of NetAddr::IP::UtilPP::comp128 1; PK � �[n�dO� � % lib/auto/NetAddr/IP/UtilPP/ipv6to4.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 438 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/ipv6to4.al)" sub ipv6to4 { my $naddr = shift; _deadlen(length($naddr)) if length($naddr) != 16; @_ = unpack('L3H8',$naddr); return pack('H8',@{_}[3..10]); } # end of NetAddr::IP::UtilPP::ipv6to4 1; PK � �[uc�� � ) lib/auto/NetAddr/IP/UtilPP/simple_pack.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 645 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/simple_pack.al)" sub simple_pack { &_bcdcheck; my($bcd) = @_; while (length($bcd) < 40) { $bcd = '0'. $bcd; } return pack('H40',$bcd); } 1; 1; # end of NetAddr::IP::UtilPP::simple_pack PK � �[����� � ' lib/auto/NetAddr/IP/UtilPP/_bin2bcdn.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 523 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_bin2bcdn.al)" sub _bin2bcdn { my($b128) = @_; my @binary = unpack('N4',$b128); my @nbcd = (0,0,0,0,0); # 5 - 32 bit registers my ($add3, $msk8, $bcd8, $carry, $tmp); my $j = 0; my $k = -1; my $binmsk = 0; foreach(0..127) { unless ($binmsk) { $binmsk = 0x80000000; $k++; } $carry = $binary[$k] & $binmsk; $binmsk >>= 1; next unless $carry || $j; # skip leading zeros foreach(4,3,2,1,0) { $bcd8 = $nbcd[$_]; $add3 = 3; $msk8 = 8; $j = 0; while ($j < 8) { $tmp = $bcd8 + $add3; if ($tmp & $msk8) { $bcd8 = $tmp; } $add3 <<= 4; $msk8 <<= 4; $j++; } $tmp = $bcd8 & 0x80000000; # propagate carry $bcd8 <<= 1; # x2 if ($carry) { $bcd8 += 1; } $nbcd[$_] = $bcd8; $carry = $tmp; } } pack('N5',@nbcd); } # end of NetAddr::IP::UtilPP::_bin2bcdn 1; PK � �[��� � ' lib/auto/NetAddr/IP/UtilPP/shiftleft.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 183 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/shiftleft.al)" sub shiftleft { _deadlen(length($_[0])) if length($_[0]) != 16; my($bits,$shifts) = @_; return $bits unless $shifts; die "Bad arg value for ".__PACKAGE__.":shiftleft, length should be 0 thru 128" if $shifts < 0 || $shifts > 128; my @uint32t = unpack('N4',$bits); do { $bits = _128x2(\@uint32t); $shifts-- } while $shifts > 0; pack('N4',@uint32t); } # end of NetAddr::IP::UtilPP::shiftleft 1; PK � �[� � & lib/auto/NetAddr/IP/UtilPP/_bcd2bin.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 605 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/_bcd2bin.al)" sub _bcd2bin { my @bcd = split('',$_[0]); my @hbits = (0,0,0,0); my @digit = (0,0,0,0); my $found = 0; foreach(@bcd) { my $bcd = $_ & 0xf; # just the nibble unless ($found) { next unless $bcd; # skip leading zeros $found = 1; $hbits[3] = $bcd; # set the first digit, no x10 necessary next; } _128x10(\@hbits); $digit[3] = $bcd; _sa128(\@hbits,\@digit,0); } return pack('N4',@hbits); } # end of NetAddr::IP::UtilPP::_bcd2bin 1; PK � �[�f^�* * & lib/auto/NetAddr/IP/UtilPP/ipanyto6.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 398 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/ipanyto6.al)" sub ipanyto6 { my $naddr = shift; my $len = length($naddr); return $naddr if $len == 16; # return pack('L3H8',0,0,0,unpack('H8',$naddr)) return pack('L3a4',0,0,0,$naddr) if $len == 4; _deadlen($len,'32 or 128'); } # end of NetAddr::IP::UtilPP::ipanyto6 1; PK � �[1V�V % lib/auto/NetAddr/IP/UtilPP/hasbits.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 125 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/hasbits.al)" sub hasbits { _deadlen(length($_[0])) if length($_[0]) != 16; return 1 if vec($_[0],0,32); return 1 if vec($_[0],1,32); return 1 if vec($_[0],2,32); return 1 if vec($_[0],3,32); return 0; } # end of NetAddr::IP::UtilPP::hasbits 1; PK � �[�e�0� � & lib/auto/NetAddr/IP/UtilPP/bin2bcdn.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 503 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/bin2bcdn.al)" #=item * $bcdpacked = bin2bcdn($bits128); # #Convert a 128 bit binary string into binary coded decimal digits. #This function is for testing only. # # input: 128 bit string variable # returns: string of packed decimal digits # # i.e. text = unpack("H*", $bcd); # #=cut sub bin2bcdn { _deadlen(length($_[0])) if length($_[0]) != 16; # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &_bin2bcdn; &_bin2bcdn; } # end of NetAddr::IP::UtilPP::bin2bcdn 1; PK � �[k,qQN N $ lib/auto/NetAddr/IP/UtilPP/add128.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 276 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/add128.al)" sub add128 { my($a128,$b128) = @_; _deadlen(length($a128)) if length($a128) != 16; _deadlen(length($b128)) if length($b128) != 16; @_ = ($a128,$b128,0); # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &slowadd128; slowadd128(@_); } # end of NetAddr::IP::UtilPP::add128 1; PK � �[c:N�t t & lib/auto/NetAddr/IP/UtilPP/bcdn2bin.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 586 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/bcdn2bin.al)" #=item * $bits128 = bcdn2bin($bcdpacked,$ndigits); # # Convert a packed bcd string into a 128 bit string variable # # input: packed bcd string # number of digits in string # returns: 128 bit string variable # sub bcdn2bin { my($bcd,$dc) = @_; $dc = 0 unless $dc; die "Bad argument length for ".__PACKAGE__.":bcdn2txt, is ".(2 * length($bcd)).", should be 1 to 40 digits" if length($bcd) > 20; die "Bad digit count for ".__PACKAGE__.":bcdn2bin, is $dc, should be 1 to 40 digits" if $dc < 1 || $dc > 40; return _bcd2bin(unpack("H$dc",$bcd)); } # end of NetAddr::IP::UtilPP::bcdn2bin 1; PK � �[ֹKԸ � % lib/auto/NetAddr/IP/UtilPP/bin2bcd.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 455 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/bin2bcd.al)" sub bin2bcd { _deadlen(length($_[0])) if length($_[0]) != 16; unpack("H40",&_bin2bcdn) =~ /^0*(.+)/; $1; } # end of NetAddr::IP::UtilPP::bin2bcd 1; PK � �[:OP�# # ' lib/auto/NetAddr/IP/UtilPP/autosplit.ixnu �[��� # Index created by AutoSplit for ../../blib/lib/NetAddr/IP/UtilPP.pm # (file acts as timestamp) package NetAddr::IP::UtilPP; sub _deadlen ; sub hasbits ; sub _128x2 ; sub _128x10 ; sub shiftleft ; sub slowadd128 ; sub _sa128 ; sub addconst ; sub add128 ; sub sub128 ; sub notcontiguous ; sub ipv4to6 ; sub mask4to6 ; sub ipanyto6 ; sub maskanyto6 ; sub ipv6to4 ; sub bin2bcd ; sub bcd2bin ; sub comp128 ; sub bin2bcdn ; sub _bin2bcdn ; sub bcdn2txt ; sub bcdn2bin ; sub _bcd2bin ; sub _bcdcheck ; sub simple_pack ; 1; PK � �[�)>R_ _ $ lib/auto/NetAddr/IP/UtilPP/sub128.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 306 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/sub128.al)" sub sub128 { _deadlen(length($_[0])) if length($_[0]) != 16; _deadlen(length($_[1])) if length($_[1]) != 16; my $a128 = $_[0]; my $b128 = ~$_[1]; @_ = ($a128,$b128,1); # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &slowadd128; slowadd128(@_); } # end of NetAddr::IP::UtilPP::sub128 1; PK � �[Y�z%C C & lib/auto/NetAddr/IP/UtilPP/bcdn2txt.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 566 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/bcdn2txt.al)" #=item * $bcdtext = bcdn2txt($bcdpacked); # #Convert a packed bcd string into text digits, suppress the leading zeros. #This function is for testing only. # # input: string of packed decimal digits # consisting of exactly 40 digits # returns: hexdecimal digits # #Similar to unpack("H*", $bcd); # #=cut sub bcdn2txt { die "Bad argument length for ".__PACKAGE__.":bcdn2txt, is ".(2 * length($_[0])).", should be exactly 40 digits" if length($_[0]) != 20; (unpack('H40',$_[0])) =~ /^0*(.+)/; $1; } # end of NetAddr::IP::UtilPP::bcdn2txt 1; PK � �[� W� � % lib/auto/NetAddr/IP/UtilPP/bcd2bin.alnu �[��� # NOTE: Derived from ../../blib/lib/NetAddr/IP/UtilPP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP::UtilPP; #line 471 "../../blib/lib/NetAddr/IP/UtilPP.pm (autosplit into ../../blib/lib/auto/NetAddr/IP/UtilPP/bcd2bin.al)" sub bcd2bin { &_bcdcheck; # perl 5.8.4 fails with this operation. see perl bug [ 23429] # goto &_bcd2bin; &_bcd2bin; } # end of NetAddr::IP::UtilPP::bcd2bin 1; PK � �[�#� " lib/auto/NetAddr/IP/_compact_v6.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 789 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/_compact_v6.al)" sub _compact_v6 ($) { my $addr = shift; my @o = split /:/, $addr; return $addr unless @o and grep { $_ =~ m/^0+$/ } @o; my @candidates = (); my $start = undef; for my $i (0 .. $#o) { if (defined $start) { if ($o[$i] !~ m/^0+$/) { push @candidates, [ $start, $i - $start ]; $start = undef; } } else { $start = $i if $o[$i] =~ m/^0+$/; } } push @candidates, [$start, 8 - $start] if defined $start; my $l = (sort { $b->[1] <=> $a->[1] } @candidates)[0]; return $addr unless defined $l; $addr = $l->[0] == 0 ? '' : join ':', @o[0 .. $l->[0] - 1]; $addr .= '::'; $addr .= join ':', @o[$l->[0] + $l->[1] .. $#o]; $addr =~ s/(^|:)0{1,3}/$1/g; return $addr; } # end of NetAddr::IP::_compact_v6 1; PK � �[Zj�[ [ lib/auto/NetAddr/IP/nprefix.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 724 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/nprefix.al)" # only applicable to ipV4 sub nprefix($) { return undef if $_[0]->{isv6}; my $mask = (notcontiguous($_[0]->{mask}))[1]; return $_[0]->addr if $mask == 128; $mask -= 96; my @faddr = split (/\./, $_[0]->first->addr); my @laddr = split (/\./, $_[0]->last->addr); return do_prefix $mask, \@faddr, \@laddr; } # end of NetAddr::IP::nprefix 1; PK � �[ lib/auto/NetAddr/IP/.existsnu �[��� PK � �[I�2 � � lib/auto/NetAddr/IP/re.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 1421 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/re.al)" sub re ($) { return &re6 unless isIPv4($_[0]->{addr}); my $self = shift->network; # Insure a "zero" host part my ($addr, $mlen) = ($self->addr, $self->masklen); my @o = split('\.', $addr, 4); my $octet= '(?:[0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'; my @r = @o; my $d; # for my $i (0 .. $#o) # { # warn "# $self: $r[$i] == $o[$i]\n"; # } if ($mlen != 32) { if ($mlen > 24) { $d = 2 ** (32 - $mlen) - 1; $r[3] = '(?:' . join('|', ($o[3]..$o[3] + $d)) . ')'; } else { $r[3] = $octet; if ($mlen > 16) { $d = 2 ** (24 - $mlen) - 1; $r[2] = '(?:' . join('|', ($o[2]..$o[2] + $d)) . ')'; } else { $r[2] = $octet; if ($mlen > 8) { $d = 2 ** (16 - $mlen) - 1; $r[1] = '(?:' . join('|', ($o[1]..$o[1] + $d)) . ')'; } else { $r[1] = $octet; if ($mlen > 0) { $d = 2 ** (8 - $mlen) - 1; $r[0] = '(?:' . join('|', ($o[0] .. $o[0] + $d)) . ')'; } else { $r[0] = $octet; } } } } } ### no digit before nor after (look-behind, look-ahead) return "(?:(?<![0-9])$r[0]\\.$r[1]\\.$r[2]\\.$r[3](?![0-9]))"; } # end of NetAddr::IP::re 1; PK � �[�V��j j lib/auto/NetAddr/IP/canon.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 879 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/canon.al)" sub canon($) { my $addr = $_[0]->addr; return $_[0]->{isv6} ? lc _compV6($addr) : $addr; } # end of NetAddr::IP::canon 1; PK � �[W*��] ] lib/auto/NetAddr/IP/prefix.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 707 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/prefix.al)" # only applicable to ipV4 sub prefix($) { return undef if $_[0]->{isv6}; my $mask = (notcontiguous($_[0]->{mask}))[1]; return $_[0]->addr if $mask == 128; $mask -= 96; my @faddr = split (/\./, $_[0]->first->addr); my @laddr = split (/\./, $_[0]->broadcast->addr); return do_prefix $mask, \@faddr, \@laddr; } # end of NetAddr::IP::prefix 1; PK � �[ lib/auto/NetAddr/IP/Util/.existsnu �[��� PK � �[�\��d d % lib/auto/NetAddr/IP/Util/autosplit.ixnu �[��� # Index created by AutoSplit for ../../blib/lib/NetAddr/IP/Util.pm # (file acts as timestamp) 1; PK � �[�ҭ� � lib/auto/NetAddr/IP/short.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 860 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/short.al)" sub short($) { my $addr = $_[0]->addr; if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) { my @o = split(/\./, $addr, 4); splice(@o, 1, 2) if $o[1] == 0 and $o[2] == 0; return join '.', @o; } return _compV6($addr); } # end of NetAddr::IP::short 1; PK � �[G�� � lib/auto/NetAddr/IP/autosplit.ixnu �[��� # Index created by AutoSplit for blib/lib/NetAddr/IP.pm # (file acts as timestamp) package NetAddr::IP; sub do_prefix ($$$); sub prefix ($); sub nprefix ($); sub wildcard ($); sub _compact_v6 ($); sub _compV6 ($); sub short ($); sub canon ($); sub _splitplan ; sub _splitref ; sub hostenum ($); sub compactref ($); sub coalesce ; sub re ($); sub re6 ($); sub mod_version ; 1; PK � �[uN�]{ { lib/auto/NetAddr/IP/do_prefix.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 493 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/do_prefix.al)" sub do_prefix ($$$) { my $mask = shift; my $faddr = shift; my $laddr = shift; if ($mask > 24) { return "$faddr->[0].$faddr->[1].$faddr->[2].$faddr->[3]-$laddr->[3]"; } elsif ($mask == 24) { return "$faddr->[0].$faddr->[1].$faddr->[2]."; } elsif ($mask > 16) { return "$faddr->[0].$faddr->[1].$faddr->[2]-$laddr->[2]."; } elsif ($mask == 16) { return "$faddr->[0].$faddr->[1]."; } elsif ($mask > 8) { return "$faddr->[0].$faddr->[1]-$laddr->[1]."; } elsif ($mask == 8) { return "$faddr->[0]."; } else { return "$faddr->[0]-$laddr->[0]"; } } # end of NetAddr::IP::do_prefix 1; PK � �[���� lib/auto/NetAddr/IP/_compV6.alnu �[��� # NOTE: Derived from blib/lib/NetAddr/IP.pm. # Changes made here will be lost when autosplit is run again. # See AutoSplit.pm. package NetAddr::IP; #line 829 "blib/lib/NetAddr/IP.pm (autosplit into blib/lib/auto/NetAddr/IP/_compV6.al)" #sub _old_compV6 { # my @addr = split(':',shift); # my $found = 0; # my $v; # foreach(0..$#addr) { # ($v = $addr[$_]) =~ s/^0+//; # $addr[$_] = $v || 0; # } # @_ = reverse(1..$#addr); # foreach(@_) { # if ($addr[$_] || $addr[$_ -1]) { # last if $found; # next; # } # $addr[$_] = $addr[$_ -1] = ''; # $found = '1'; # } # (my $rv = join(':',@addr)) =~ s/:+:/::/; # return $rv; #} # thanks to Rob Riepel <riepel@networking.Stanford.EDU> # for this faster and more compact solution 11-17-08 sub _compV6 ($) { my $ip = shift; return $ip unless my @candidates = $ip =~ /((?:^|:)0(?::0)+(?::|$))/g; my $longest = (sort { length($b) <=> length($a) } @candidates)[0]; $ip =~ s/$longest/::/; return $ip; } # end of NetAddr::IP::_compV6 1; PK � �[�ؚ�� � man3/URI::data.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::data 3" .TH URI::data 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::data \- URI that contains immediate data .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI; \& \& $u = URI\->new("data:"); \& $u\->media_type("image/gif"); \& $u\->data(scalar(\`cat camel.gif\`)); \& print "$u\en"; \& open(XV, "|xv \-") and print XV $u\->data; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`URI::data\*(C'\fR class supports \f(CW\*(C`URI\*(C'\fR objects belonging to the \fIdata\fR \&\s-1URI\s0 scheme. The \fIdata\fR \s-1URI\s0 scheme is specified in \s-1RFC 2397.\s0 It allows inclusion of small data items as \*(L"immediate\*(R" data, as if it had been included externally. Examples: .PP .Vb 1 \& data:,Perl%20is%20good \& \& data:image/gif;base64,R0lGODdhIAAgAIAAAAAAAPj8+CwAAAAAI \& AAgAAAClYyPqcu9AJyCjtIKc5w5xP14xgeO2tlY3nWcajmZZdeJcG \& Kxrmimms1KMTa1Wg8UROx4MNUq1HrycMjHT9b6xKxaFLM6VRKzI+p \& KS9XtXpcbdun6uWVxJXA8pNPkdkkxhxc21LZHFOgD2KMoQXa2KMWI \& JtnE2KizVUkYJVZZ1nczBxXlFopZBtoJ2diXGdNUymmJdFMAADs= .Ve .PP \&\f(CW\*(C`URI\*(C'\fR objects belonging to the data scheme support the common methods (described in \s-1URI\s0) and the following two scheme-specific methods: .ie n .IP "$uri\->media_type( [$new_media_type] )" 4 .el .IP "\f(CW$uri\fR\->media_type( [$new_media_type] )" 4 .IX Item "$uri->media_type( [$new_media_type] )" Can be used to get or set the media type specified in the \&\s-1URI.\s0 If no media type is specified, then the default \&\f(CW"text/plain;charset=US\-ASCII"\fR is returned. .ie n .IP "$uri\->data( [$new_data] )" 4 .el .IP "\f(CW$uri\fR\->data( [$new_data] )" 4 .IX Item "$uri->data( [$new_data] )" Can be used to get or set the data contained in the \s-1URI.\s0 The data is passed unescaped (in binary form). The decision about whether to base64 encode the data in the \s-1URI\s0 is taken automatically, based on the encoding that produces the shorter \s-1URI\s0 string. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1URI\s0 .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1995\-1998 Gisle Aas. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[��G��" �" man3/URI::geo.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::geo 3" .TH URI::geo 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::geo \- URI scheme for geo Identifiers .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI; \& \& # Geo URI from textual uri \& my $guri = URI\->new( \*(Aqgeo:54.786989,\-2.344214\*(Aq ); \& \& # From coordinates \& my $guri = URI::geo\->new( 54.786989, \-2.344214 ); \& \& # Decode \& my ( $lat, $lon, $alt ) = $guri\->location; \& my $latitude = $guri\->latitude; \& \& # Update \& $guri\->location( 55, \-1 ); \& $guri\->longitude( \-43.23 ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" From <http://geouri.org/>: .PP .Vb 3 \& More and more protocols and data formats are being extended by methods \& to add geographic information. However, all of those options are tied \& to that specific protocol or data format. \& \& A dedicated Uniform Resource Identifier (URI) scheme for geographic \& locations would be independent from any protocol, usable by any \& software/data format that can handle generich URIs. Like a "mailto:" \& URI launches your favourite mail application today, a "geo:" URI could \& soon launch your favourite mapping service, or queue that location for \& a navigation device. .Ve .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .ie n .SS """new""" .el .SS "\f(CWnew\fP" .IX Subsection "new" Create a new URI::geo. The arguments should be either .IP "\(bu" 4 latitude, longitude and optionally altitude .IP "\(bu" 4 a reference to an array containing lat, lon, alt .IP "\(bu" 4 a reference to a hash with suitably named keys or .IP "\(bu" 4 a reference to an object with suitably named accessors .PP To maximize the likelihood that you can pass in some object that represents a geographical location and have URI::geo do the right thing we try a number of different accessor names. .PP If the object has a \f(CW\*(C`latlong\*(C'\fR method (e.g. Geo::Point) we'll use that. If there's a \f(CW\*(C`location\*(C'\fR method we call that. Otherwise we look for accessors called \f(CW\*(C`lat\*(C'\fR, \f(CW\*(C`latitude\*(C'\fR, \f(CW\*(C`lon\*(C'\fR, \f(CW\*(C`long\*(C'\fR, \f(CW\*(C`longitude\*(C'\fR, \&\f(CW\*(C`ele\*(C'\fR, \f(CW\*(C`alt\*(C'\fR, \f(CW\*(C`elevation\*(C'\fR or \f(CW\*(C`altitude\*(C'\fR and use them. .PP Often if you have an object or hash reference that represents a point you can pass it directly to \f(CW\*(C`new\*(C'\fR; so for example this will work: .PP .Vb 2 \& use URI::geo; \& use Geo::Point; \& \& my $pt = Geo::Point\->latlong( 48.208333, 16.372778 ); \& my $guri = URI::geo\->new( $pt ); .Ve .PP As will this: .PP .Vb 1 \& my $guri = URI::geo\->new( { lat => 55, lon => \-1 } ); .Ve .PP and this: .PP .Vb 1 \& my $guri = URI::geo\->new( 55, \-1 ); .Ve .PP Note that you can also create a new \f(CW\*(C`URI::geo\*(C'\fR by passing a Geo \s-1URI\s0 to \&\f(CW\*(C`URI::new\*(C'\fR: .PP .Vb 1 \& use URI; \& \& my $guri = URI\->new( \*(Aqgeo:55,\-1\*(Aq ); .Ve .ie n .SS """location""" .el .SS "\f(CWlocation\fP" .IX Subsection "location" Get or set the location of this geo \s-1URI.\s0 .PP .Vb 2 \& my ( $lat, $lon, $alt ) = $guri\->location; \& $guri\->location( 55.3, \-3.7, 120 ); .Ve .PP When setting the location it is possible to pass any of the argument types that can be passed to \f(CW\*(C`new\*(C'\fR. .ie n .SS """latitude""" .el .SS "\f(CWlatitude\fP" .IX Subsection "latitude" Get or set the latitude of this geo \s-1URI.\s0 .ie n .SS """longitude""" .el .SS "\f(CWlongitude\fP" .IX Subsection "longitude" Get or set the longitude of this geo \s-1URI.\s0 .ie n .SS """altitude""" .el .SS "\f(CWaltitude\fP" .IX Subsection "altitude" Get or set the altitude <https://en.wikipedia.org/wiki/Geo_URI_scheme#Altitude> of this geo \s-1URI.\s0 To delete the altitude set it to \f(CW\*(C`undef\*(C'\fR. .ie n .SS """crs""" .el .SS "\f(CWcrs\fP" .IX Subsection "crs" Get or set the Coordinate Reference System <https://en.wikipedia.org/wiki/Geo_URI_scheme#Coordinate_reference_systems> of this geo \s-1URI.\s0 To delete the \s-1CRS\s0 set it to \f(CW\*(C`undef\*(C'\fR. .ie n .SS """uncertainty""" .el .SS "\f(CWuncertainty\fP" .IX Subsection "uncertainty" Get or set the uncertainty <https://en.wikipedia.org/wiki/Geo_URI_scheme#Uncertainty> of this geo \s-1URI.\s0 To delete the uncertainty set it to \f(CW\*(C`undef\*(C'\fR. .ie n .SS """field""" .el .SS "\f(CWfield\fP" .IX Subsection "field" .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" URI::geo requires no configuration files or environment variables. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" \&\s-1URI\s0 .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .ie n .IP """Too many arguments""" 4 .el .IP "\f(CWToo many arguments\fR" 4 .IX Item "Too many arguments" The new method can only accept three parameters; latitude, longitude and altitude. .ie n .IP """Don\*(Aqt know how to convert point""" 4 .el .IP "\f(CWDon\*(Aqt know how to convert point\fR" 4 .IX Item "Dont know how to convert point" The new method doesn't know how to convert the supplied parameters into a URI::geo object. .ie n .IP """Need lat, lon or lat, lon, alt""" 4 .el .IP "\f(CWNeed lat, lon or lat, lon, alt\fR" 4 .IX Item "Need lat, lon or lat, lon, alt" The new method needs two (latitude and longitude) or three (latitude, longitude and altitude) parameters in a list. Any less or more than this is an error. .ie n .IP """No such field: %s""" 4 .el .IP "\f(CWNo such field: %s\fR" 4 .IX Item "No such field: %s" This field is not a known field for the URI::geo object. .ie n .IP """Badly formed geo uri""" 4 .el .IP "\f(CWBadly formed geo uri\fR" 4 .IX Item "Badly formed geo uri" The \s-1URI\s0 cannot be parsed as a \s-1URI\s0 .ie n .IP """Badly formed geo uri""" 4 .el .IP "\f(CWBadly formed geo uri\fR" 4 .IX Item "Badly formed geo uri" The \s-1URI\s0 cannot be parsed as a \s-1URI\s0 .ie n .IP """Latitude out of range""" 4 .el .IP "\f(CWLatitude out of range\fR" 4 .IX Item "Latitude out of range" Latitude may only be from \-90 to +90 .ie n .IP """Longitude out of range""" 4 .el .IP "\f(CWLongitude out of range\fR" 4 .IX Item "Longitude out of range" Longitude may only be from \-180 to +180 .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" To report a bug, or view the current list of bugs, please visit <https://github.com/libwww\-perl/URI/issues> .SH "AUTHOR" .IX Header "AUTHOR" Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2009, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. PK � �[G�4 4 man3/URI::otpauth.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::otpauth 3" .TH URI::otpauth 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::otpauth \- URI scheme for secret keys for OTP secrets. Usually found in QR codes .SH "VERSION" .IX Header "VERSION" Version 5.29 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI; \& \& # optauth URI from textual uri \& my $uri = URI\->new( \*(Aqotpauth://totp/Example:alice@google.com?secret=NFZS25DINFZV643VOAZXELLTGNRXEM3UH4&issuer=Example\*(Aq ); \& \& # same URI but created from arguments \& my $uri = URI::otpauth\->new( type => \*(Aqtotp\*(Aq, issuer => \*(AqExample\*(Aq, account_name => \*(Aqalice@google.com\*(Aq, secret => \*(Aqis\-this_sup3r\-s3cr3t?\*(Aq ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This \s-1URI\s0 scheme is defined in <https://github.com/google/google\-authenticator/wiki/Key\-Uri\-Format/>: .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .ie n .SS """new""" .el .SS "\f(CWnew\fP" .IX Subsection "new" Create a new URI::otpauth. The available arguments are listed below; .IP "\(bu" 4 account_name \- this can be the account name (probably an email address) used when authenticating with this secret. It is an optional field. .IP "\(bu" 4 algorithm \- this is the cryptographic hash function <https://en.wikipedia.org/wiki/Cryptographic_hash_function> that should be used. Current values are \s-1SHA1\s0 <https://en.wikipedia.org/wiki/SHA-1>, \s-1SHA256\s0 <https://en.wikipedia.org/wiki/SHA-2> or \s-1SHA512\s0 <https://en.wikipedia.org/wiki/SHA-2>. It is an optional field and will default to \s-1SHA1.\s0 .IP "\(bu" 4 counter \- this is only required when the type is \s-1HOTP.\s0 .IP "\(bu" 4 digits \- this determines the length <https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#digits> of the code presented to the user. It is an optional field and will default to 6 digits. .IP "\(bu" 4 issuer \- this can be the application / system <https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#issuer> that this secret can be used to authenticate to. It is an optional field. .IP "\(bu" 4 label \- this is the issuer and the account name <https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#label> joined with a \*(L":\*(R" character. It is an optional field. .IP "\(bu" 4 period \- this is the period that the \s-1TOTP\s0 code is valid for <https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#counter>. It is an optional field and will default to 30 seconds. .IP "\(bu" 4 secret \- this is the key <https://en.wikipedia.org/wiki/Key_(cryptography)> that the \s-1TOTP\s0 <https://en.wikipedia.org/wiki/Time-based_one-time_password>/\s-1HOTP\s0 <https://en.wikipedia.org/wiki/HMAC-based_one-time_password> algorithm uses to derive the value. It is an arbitrary byte string and must remain private. This field is mandatory. .IP "\(bu" 4 type \- this can be 'hotp <https://en.wikipedia.org/wiki/HMAC-based_one-time_password>' or 'totp <https://en.wikipedia.org/wiki/Time-based_one-time_password>'. This field will default to 'totp'. .ie n .SS """algorithm""" .el .SS "\f(CWalgorithm\fP" .IX Subsection "algorithm" Get or set the algorithm of this otpauth \s-1URI.\s0 .ie n .SS """account_name""" .el .SS "\f(CWaccount_name\fP" .IX Subsection "account_name" Get or set the account_name of this otpauth \s-1URI.\s0 .ie n .SS """counter""" .el .SS "\f(CWcounter\fP" .IX Subsection "counter" Get or set the counter of this otpauth \s-1URI.\s0 .ie n .SS """digits""" .el .SS "\f(CWdigits\fP" .IX Subsection "digits" Get or set the digits of this otpauth \s-1URI.\s0 .ie n .SS """issuer""" .el .SS "\f(CWissuer\fP" .IX Subsection "issuer" Get or set the issuer of this otpauth \s-1URI.\s0 .ie n .SS """label""" .el .SS "\f(CWlabel\fP" .IX Subsection "label" Get or set the label of this otpauth \s-1URI.\s0 .ie n .SS """period""" .el .SS "\f(CWperiod\fP" .IX Subsection "period" Get or set the period of this otpauth \s-1URI.\s0 .ie n .SS """secret""" .el .SS "\f(CWsecret\fP" .IX Subsection "secret" Get or set the secret of this otpauth \s-1URI.\s0 .ie n .SS """type""" .el .SS "\f(CWtype\fP" .IX Subsection "type" Get or set the type of this otpauth \s-1URI.\s0 .PP .Vb 1 \& my $type = $uri\->type(\*(Aqhotp\*(Aq); .Ve .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" URI::otpauth requires no configuration files or environment variables. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" \&\s-1URI\s0 .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .ie n .IP """secret is a mandatory parameter for URI::otpauth""" 4 .el .IP "\f(CWsecret is a mandatory parameter for URI::otpauth\fR" 4 .IX Item "secret is a mandatory parameter for URI::otpauth" The secret parameter was not detected for the URI::otpauth\->\fBnew()\fR method. .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" To report a bug, or view the current list of bugs, please visit <https://github.com/libwww\-perl/URI/issues> .SH "AUTHOR" .IX Header "AUTHOR" David Dick \f(CW\*(C`<ddick@cpan.org>\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2024, David Dick \f(CW\*(C`<ddick@cpan.org>\*(C'\fR. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. PK � �[�ݿ�e e man3/URI::ldap.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::ldap 3" .TH URI::ldap 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::ldap \- LDAP Uniform Resource Locators .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI; \& \& $uri = URI\->new("ldap:$uri_string"); \& $dn = $uri\->dn; \& $filter = $uri\->filter; \& @attr = $uri\->attributes; \& $scope = $uri\->scope; \& %extn = $uri\->extensions; \& \& $uri = URI\->new("ldap:"); # start empty \& $uri\->host("ldap.itd.umich.edu"); \& $uri\->dn("o=University of Michigan,c=US"); \& $uri\->attributes(qw(postalAddress)); \& $uri\->scope(\*(Aqsub\*(Aq); \& $uri\->filter(\*(Aq(cn=Babs Jensen)\*(Aq); \& print $uri\->as_string,"\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`URI::ldap\*(C'\fR provides an interface to parse an \s-1LDAP URI\s0 into its constituent parts and also to build a \s-1URI\s0 as described in \&\s-1RFC 2255.\s0 .SH "METHODS" .IX Header "METHODS" \&\f(CW\*(C`URI::ldap\*(C'\fR supports all the generic and server methods defined by \&\s-1URI\s0, plus the following. .PP Each of the following methods can be used to set or get the value in the \s-1URI.\s0 The values are passed in unescaped form. None of these return undefined values, but elements without a default can be empty. If arguments are given, then a new value is set for the given part of the \s-1URI.\s0 .ie n .IP "$uri\->dn( [$new_dn] )" 4 .el .IP "\f(CW$uri\fR\->dn( [$new_dn] )" 4 .IX Item "$uri->dn( [$new_dn] )" Sets or gets the \fIDistinguished Name\fR part of the \s-1URI.\s0 The \s-1DN\s0 identifies the base object of the \s-1LDAP\s0 search. .ie n .IP "$uri\->attributes( [@new_attrs] )" 4 .el .IP "\f(CW$uri\fR\->attributes( [@new_attrs] )" 4 .IX Item "$uri->attributes( [@new_attrs] )" Sets or gets the list of attribute names which are returned by the search. .ie n .IP "$uri\->scope( [$new_scope] )" 4 .el .IP "\f(CW$uri\fR\->scope( [$new_scope] )" 4 .IX Item "$uri->scope( [$new_scope] )" Sets or gets the scope to be used by the search. The value can be one of \&\f(CW"base"\fR, \f(CW"one"\fR or \f(CW"sub"\fR. If none is given in the \s-1URI\s0 then the return value defaults to \f(CW"base"\fR. .ie n .IP "$uri\->_scope( [$new_scope] )" 4 .el .IP "\f(CW$uri\fR\->_scope( [$new_scope] )" 4 .IX Item "$uri->_scope( [$new_scope] )" Same as \fBscope()\fR, but does not default to anything. .ie n .IP "$uri\->filter( [$new_filter] )" 4 .el .IP "\f(CW$uri\fR\->filter( [$new_filter] )" 4 .IX Item "$uri->filter( [$new_filter] )" Sets or gets the filter to be used by the search. If none is given in the \s-1URI\s0 then the return value defaults to \f(CW"(objectClass=*)"\fR. .ie n .IP "$uri\->_filter( [$new_filter] )" 4 .el .IP "\f(CW$uri\fR\->_filter( [$new_filter] )" 4 .IX Item "$uri->_filter( [$new_filter] )" Same as \fBfilter()\fR, but does not default to anything. .ie n .IP "$uri\->extensions( [$etype => $evalue,...] )" 4 .el .IP "\f(CW$uri\fR\->extensions( [$etype => \f(CW$evalue\fR,...] )" 4 .IX Item "$uri->extensions( [$etype => $evalue,...] )" Sets or gets the extensions used for the search. The list passed should be in the form etype1 => evalue1, etype2 => evalue2,... This is also the form of list that is returned. .SH "SEE ALSO" .IX Header "SEE ALSO" <http://tools.ietf.org/html/rfc2255> .SH "AUTHOR" .IX Header "AUTHOR" Graham Barr <\fIgbarr@pobox.com\fR> .PP Slightly modified by Gisle Aas to fit into the \s-1URI\s0 distribution. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[ u�a� � man3/URI::WithBase.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::WithBase 3" .TH URI::WithBase 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::WithBase \- URIs which remember their base .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& $u1 = URI::WithBase\->new($str, $base); \& $u2 = $u1\->abs; \& \& $base = $u1\->base; \& $u1\->base( $new_base ) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides the \f(CW\*(C`URI::WithBase\*(C'\fR class. Objects of this class are like \f(CW\*(C`URI\*(C'\fR objects, but can keep their base too. The base represents the context where this \s-1URI\s0 was found and can be used to absolutize or relativize the \s-1URI.\s0 All the methods described in \s-1URI\s0 are supported for \f(CW\*(C`URI::WithBase\*(C'\fR objects. .PP The methods provided in addition to or modified from those of \f(CW\*(C`URI\*(C'\fR are: .ie n .IP "$uri = URI::WithBase\->new($str, [$base])" 4 .el .IP "\f(CW$uri\fR = URI::WithBase\->new($str, [$base])" 4 .IX Item "$uri = URI::WithBase->new($str, [$base])" The constructor takes an optional base \s-1URI\s0 as the second argument. If provided, this argument initializes the base attribute. .ie n .IP "$uri\->base( [$new_base] )" 4 .el .IP "\f(CW$uri\fR\->base( [$new_base] )" 4 .IX Item "$uri->base( [$new_base] )" Can be used to get or set the value of the base attribute. The return value, which is the old value, is a \s-1URI\s0 object or \f(CW\*(C`undef\*(C'\fR. .ie n .IP "$uri\->abs( [$base_uri] )" 4 .el .IP "\f(CW$uri\fR\->abs( [$base_uri] )" 4 .IX Item "$uri->abs( [$base_uri] )" The \f(CW$base_uri\fR argument is now made optional as the object carries its base with it. A new object is returned even if \f(CW$uri\fR is already absolute (while plain \s-1URI\s0 objects simply return themselves in that case). .ie n .IP "$uri\->rel( [$base_uri] )" 4 .el .IP "\f(CW$uri\fR\->rel( [$base_uri] )" 4 .IX Item "$uri->rel( [$base_uri] )" The \f(CW$base_uri\fR argument is now made optional as the object carries its base with it. A new object is always returned. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1URI\s0 .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1998\-2002 Gisle Aas. PK � �[��Yv� � man3/URI::Split.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::Split 3" .TH URI::Split 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::Split \- Parse and compose URI strings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use URI::Split qw(uri_split uri_join); \& ($scheme, $auth, $path, $query, $frag) = uri_split($uri); \& $uri = uri_join($scheme, $auth, $path, $query, $frag); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Provides functions to parse and compose \s-1URI\s0 strings. The following functions are provided: .ie n .IP "($scheme, $auth, $path, $query, $frag) = uri_split($uri)" 4 .el .IP "($scheme, \f(CW$auth\fR, \f(CW$path\fR, \f(CW$query\fR, \f(CW$frag\fR) = uri_split($uri)" 4 .IX Item "($scheme, $auth, $path, $query, $frag) = uri_split($uri)" Breaks up a \s-1URI\s0 string into its component parts. An \f(CW\*(C`undef\*(C'\fR value is returned for those parts that are not present. The \f(CW$path\fR part is always present (but can be the empty string) and is thus never returned as \f(CW\*(C`undef\*(C'\fR. .Sp No sensible value is returned if this function is called in a scalar context. .ie n .IP "$uri = uri_join($scheme, $auth, $path, $query, $frag)" 4 .el .IP "\f(CW$uri\fR = uri_join($scheme, \f(CW$auth\fR, \f(CW$path\fR, \f(CW$query\fR, \f(CW$frag\fR)" 4 .IX Item "$uri = uri_join($scheme, $auth, $path, $query, $frag)" Puts together a \s-1URI\s0 string from its parts. Missing parts are signaled by passing \f(CW\*(C`undef\*(C'\fR for the corresponding argument. .Sp Minimal escaping is applied to parts that contain reserved chars that would confuse a parser. For instance, any occurrence of '?' or '#' in \f(CW$path\fR is always escaped, as it would otherwise be parsed back as a query or fragment. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1URI\s0, URI::Escape .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2003, Gisle Aas .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[�RFM M man3/URI::Heuristic.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::Heuristic 3" .TH URI::Heuristic 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::Heuristic \- Expand URI using heuristics .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 6 \& use URI::Heuristic qw(uf_uristr); \& $u = uf_uristr("example"); # http://www.example.com \& $u = uf_uristr("www.sol.no/sol"); # http://www.sol.no/sol \& $u = uf_uristr("aas"); # http://www.aas.no \& $u = uf_uristr("ftp.funet.fi"); # ftp://ftp.funet.fi \& $u = uf_uristr("/etc/passwd"); # file:/etc/passwd .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides functions that expand strings into real absolute URIs using some built-in heuristics. Strings that already represent absolute URIs (i.e. that start with a \f(CW\*(C`scheme:\*(C'\fR part) are never modified and are returned unchanged. The main use of these functions is to allow abbreviated URIs similar to what many web browsers allow for URIs typed in by the user. .PP The following functions are provided: .IP "uf_uristr($str)" 4 .IX Item "uf_uristr($str)" Tries to make the argument string into a proper absolute \s-1URI\s0 string. The \*(L"uf_\*(R" prefix stands for \*(L"User Friendly\*(R". Under MacOS, it assumes that any string with a common \s-1URL\s0 scheme (http, ftp, etc.) is a \s-1URL\s0 rather than a local path. So don't name your volumes after common \s-1URL\s0 schemes and expect \fBuf_uristr()\fR to construct valid file: \s-1URL\s0's on those volumes for you, because it won't. .IP "uf_uri($str)" 4 .IX Item "uf_uri($str)" Works the same way as \fBuf_uristr()\fR but returns a \f(CW\*(C`URI\*(C'\fR object. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" If the hostname portion of a \s-1URI\s0 does not contain any dots, then certain qualified guesses are made. These guesses are governed by the following environment variables: .IP "\s-1COUNTRY\s0" 10 .IX Item "COUNTRY" The two-letter country code (\s-1ISO 3166\s0) for your location. If the domain name of your host ends with two letters, then it is taken to be the default country. See also Locale::Country. .IP "\s-1HTTP_ACCEPT_LANGUAGE, LC_ALL, LANG\s0" 10 .IX Item "HTTP_ACCEPT_LANGUAGE, LC_ALL, LANG" If \s-1COUNTRY\s0 is not set, these standard environment variables are examined and country (not language) information possibly found in them is used as the default country. .IP "\s-1URL_GUESS_PATTERN\s0" 10 .IX Item "URL_GUESS_PATTERN" Contains a space-separated list of \s-1URL\s0 patterns to try. The string \&\*(L"\s-1ACME\*(R"\s0 is for some reason used as a placeholder for the host name in the \s-1URL\s0 provided. Example: .Sp .Vb 2 \& URL_GUESS_PATTERN="www.ACME.no www.ACME.se www.ACME.com" \& export URL_GUESS_PATTERN .Ve .Sp Specifying \s-1URL_GUESS_PATTERN\s0 disables any guessing rules based on country. An empty \s-1URL_GUESS_PATTERN\s0 disables any guessing that involves host name lookups. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1997\-1998, Gisle Aas .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[�@l ~ ~ man3/URI::QueryParam.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::QueryParam 3" .TH URI::QueryParam 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::QueryParam \- Additional query methods for URIs .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`URI::QueryParam\*(C'\fR used to provide the query_form_hash, query_param query_param_append, and query_param_delete methods on \s-1URI\s0 objects. These methods have been merged into \s-1URI\s0 itself, so this module is now a no-op. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2002 Gisle Aas. PK � �[ ���8) 8) man3/URI::file.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::file 3" .TH URI::file 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::file \- URI that maps to local file names .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI::file; \& \& $u1 = URI\->new("file:/foo/bar"); \& $u2 = URI\->new("foo/bar", "file"); \& \& $u3 = URI::file\->new($path); \& $u4 = URI::file\->new("c:\e\ewindows\e\e", "win32"); \& \& $u1\->file; \& $u1\->file("mac"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`URI::file\*(C'\fR class supports \f(CW\*(C`URI\*(C'\fR objects belonging to the \fIfile\fR \&\s-1URI\s0 scheme. This scheme allows us to map the conventional file names found on various computer systems to the \s-1URI\s0 name space, see \s-1RFC 8089\s0 <https://www.rfc-editor.org/rfc/rfc8089.html>. .PP If you simply want to construct \fIfile\fR \s-1URI\s0 objects from \s-1URI\s0 strings, use the normal \f(CW\*(C`URI\*(C'\fR constructor. If you want to construct \fIfile\fR \&\s-1URI\s0 objects from the actual file names used by various systems, then use one of the following \f(CW\*(C`URI::file\*(C'\fR constructors: .ie n .IP "$u = URI::file\->new( $filename, [$os] )" 4 .el .IP "\f(CW$u\fR = URI::file\->new( \f(CW$filename\fR, [$os] )" 4 .IX Item "$u = URI::file->new( $filename, [$os] )" Maps a file name to the \fIfile:\fR \s-1URI\s0 name space, creates a \s-1URI\s0 object and returns it. The \f(CW$filename\fR is interpreted as belonging to the indicated operating system ($os), which defaults to the value of the $^O variable. The \f(CW$filename\fR can be either absolute or relative, and the corresponding type of \s-1URI\s0 object for \f(CW$os\fR is returned. .ie n .IP "$u = URI::file\->new_abs( $filename, [$os] )" 4 .el .IP "\f(CW$u\fR = URI::file\->new_abs( \f(CW$filename\fR, [$os] )" 4 .IX Item "$u = URI::file->new_abs( $filename, [$os] )" Same as URI::file\->new, but makes sure that the \s-1URI\s0 returned represents an absolute file name. If the \f(CW$filename\fR argument is relative, then the name is resolved relative to the current directory, i.e. this constructor is really the same as: .Sp .Vb 1 \& URI::file\->new($filename)\->abs(URI::file\->cwd); .Ve .ie n .IP "$u = URI::file\->cwd" 4 .el .IP "\f(CW$u\fR = URI::file\->cwd" 4 .IX Item "$u = URI::file->cwd" Returns a \fIfile\fR \s-1URI\s0 that represents the current working directory. See Cwd. .PP The following methods are supported for \fIfile\fR \s-1URI\s0 (in addition to the common and generic methods described in \s-1URI\s0): .ie n .IP "$u\->file( [$os] )" 4 .el .IP "\f(CW$u\fR\->file( [$os] )" 4 .IX Item "$u->file( [$os] )" Returns a file name. It maps from the \s-1URI\s0 name space to the file name space of the indicated operating system. .Sp It might return \f(CW\*(C`undef\*(C'\fR if the name can not be represented in the indicated file system. .ie n .IP "$u\->dir( [$os] )" 4 .el .IP "\f(CW$u\fR\->dir( [$os] )" 4 .IX Item "$u->dir( [$os] )" Some systems use a different form for names of directories than for plain files. Use this method if you know you want to use the name for a directory. .PP The \f(CW\*(C`URI::file\*(C'\fR module can be used to map generic file names to names suitable for the current system. As such, it can work as a nice replacement for the \f(CW\*(C`File::Spec\*(C'\fR module. For instance, the following code translates the UNIX-style file name \fIFoo/Bar.pm\fR to a name suitable for the local system: .PP .Vb 4 \& $file = URI::file\->new("Foo/Bar.pm", "unix")\->file; \& die "Can\*(Aqt map filename Foo/Bar.pm for $^O" unless defined $file; \& open(FILE, $file) || die "Can\*(Aqt open \*(Aq$file\*(Aq: $!"; \& # do something with FILE .Ve .SH "MAPPING NOTES" .IX Header "MAPPING NOTES" Most computer systems today have hierarchically organized file systems. Mapping the names used in these systems to the generic \s-1URI\s0 syntax allows us to work with relative file URIs that behave as they should when resolved using the generic algorithm for URIs (specified in \s-1RFC 3986\s0 <https://www.rfc-editor.org/rfc/rfc3986.html>). Mapping a file name to the generic \s-1URI\s0 syntax involves mapping the path separator character to \*(L"/\*(R" and encoding any reserved characters that appear in the path segments of the file name. If path segments consisting of the strings \*(L".\*(R" or \*(L"..\*(R" have a different meaning than what is specified for generic URIs, then these must be encoded as well. .PP If the file system has device, volume or drive specifications as the root of the name space, then it makes sense to map them to the authority field of the generic \s-1URI\s0 syntax. This makes sure that relative URIs can not be resolved \*(L"above\*(R" them, i.e. generally how relative file names work in those systems. .PP Another common use of the authority field is to encode the host on which this file name is valid. The host name \*(L"localhost\*(R" is special and generally has the same meaning as a missing or empty authority field. This use is in conflict with using it as a device specification, but can often be resolved for device specifications having characters not legal in plain host names. .PP File name to \s-1URI\s0 mapping in normally not one-to-one. There are usually many URIs that map to any given file name. For instance, an authority of \*(L"localhost\*(R" maps the same as a \s-1URI\s0 with a missing or empty authority. .PP Example 1: The Mac classic (Mac \s-1OS 9\s0 and earlier) used \*(L":\*(R" as path separator, but not in the same way as a generic \s-1URI.\s0 \*(L":foo\*(R" was a relative name. \*(L"foo:bar\*(R" was an absolute name. Also, path segments could contain the \*(L"/\*(R" character as well as the literal \*(L".\*(R" or \*(L"..\*(R". So the mapping looks like this: .PP .Vb 12 \& Mac classic URI \& \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& :foo:bar <==> foo/bar \& : <==> ./ \& ::foo:bar <==> ../foo/bar \& ::: <==> ../../ \& foo:bar <==> file:/foo/bar \& foo:bar: <==> file:/foo/bar/ \& .. <==> %2E%2E \& <undef> <== / \& foo/ <== file:/foo%2F \& ./foo.txt <== file:/.%2Ffoo.txt .Ve .PP Note that if you want a relative \s-1URL,\s0 you *must* begin the path with a :. Any path that begins with [^:] is treated as absolute. .PP Example 2: The \s-1UNIX\s0 file system is easy to map, as it uses the same path separator as URIs, has a single root, and segments of \*(L".\*(R" and \*(L"..\*(R" have the same meaning. URIs that have the character \*(L"\e0\*(R" or \*(L"/\*(R" as part of any path segment can not be turned into valid \s-1UNIX\s0 file names. .PP .Vb 8 \& UNIX URI \& \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& foo/bar <==> foo/bar \& /foo/bar <==> file:/foo/bar \& /foo/bar <== file://localhost/foo/bar \& file: ==> ./file: \& <undef> <== file:/fo%00/bar \& / <==> file:/ .Ve .SH "CONFIGURATION VARIABLES" .IX Header "CONFIGURATION VARIABLES" The following configuration variables influence how the class and its methods behave: .ie n .IP "%URI::file::OS_CLASS" 4 .el .IP "\f(CW%URI::file::OS_CLASS\fR" 4 .IX Item "%URI::file::OS_CLASS" This hash maps \s-1OS\s0 identifiers to implementation classes. You might want to add or modify this if you want to plug in your own file handler class. Normally the keys should match the $^O values in use. .Sp If there is no mapping then the \*(L"Unix\*(R" implementation is used. .ie n .IP "$URI::file::DEFAULT_AUTHORITY" 4 .el .IP "\f(CW$URI::file::DEFAULT_AUTHORITY\fR" 4 .IX Item "$URI::file::DEFAULT_AUTHORITY" This determines what \*(L"authority\*(R" string to include in absolute file URIs. It defaults to "\*(L". If you prefer verbose URIs you might set it to be \*(R"localhost". .Sp Setting this value to \f(CW\*(C`undef\*(C'\fR forces behaviour compatible to \s-1URI\s0 v1.31 and earlier. In this mode host names in \s-1UNC\s0 paths and drive letters are mapped to the authority component on Windows, while we produce authority-less URIs on Unix. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1URI\s0, File::Spec, perlport .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1995\-1998,2004 Gisle Aas. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[!�+�� � man3/URI::_punycode.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::_punycode 3" .TH URI::_punycode 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::_punycode \- encodes Unicode string in Punycode .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use strict; \& use warnings; \& use utf8; \& \& use URI::_punycode qw(encode_punycode decode_punycode); \& \& # encode a unicode string \& my $punycode = encode_punycode(\*(Aqhttp://☃.net\*(Aq); # http://.net\-xc8g \& $punycode = encode_punycode(\*(Aqbücher\*(Aq); # bcher\-kva \& $punycode = encode_punycode(\*(Aq他们为什么不说中文\*(Aq); # ihqwcrb4cv8a8dqg056pqjye \& \& # decode a punycode string back into a unicode string \& my $unicode = decode_punycode(\*(Aqhttp://.net\-xc8g\*(Aq); # http://☃.net \& $unicode = decode_punycode(\*(Aqbcher\-kva\*(Aq); # bücher \& $unicode = decode_punycode(\*(Aqihqwcrb4cv8a8dqg056pqjye\*(Aq); # 他们为什么不说中文 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" URI::_punycode is a module to encode / decode Unicode strings into Punycode <https://tools.ietf.org/html/rfc3492>, an efficient encoding of Unicode for use with \s-1IDNA\s0 <https://tools.ietf.org/html/rfc5890>. .SH "FUNCTIONS" .IX Header "FUNCTIONS" All functions throw exceptions on failure. You can \f(CW\*(C`catch\*(C'\fR them with Syntax::Keyword::Try or Try::Tiny. The following functions are exported by default. .SS "encode_punycode" .IX Subsection "encode_punycode" .Vb 3 \& my $punycode = encode_punycode(\*(Aqhttp://☃.net\*(Aq); # http://.net\-xc8g \& $punycode = encode_punycode(\*(Aqbücher\*(Aq); # bcher\-kva \& $punycode = encode_punycode(\*(Aq他们为什么不说中文\*(Aq) # ihqwcrb4cv8a8dqg056pqjye .Ve .PP Takes a Unicode string (UTF8\-flagged variable) and returns a Punycode encoding for it. .SS "decode_punycode" .IX Subsection "decode_punycode" .Vb 3 \& my $unicode = decode_punycode(\*(Aqhttp://.net\-xc8g\*(Aq); # http://☃.net \& $unicode = decode_punycode(\*(Aqbcher\-kva\*(Aq); # bücher \& $unicode = decode_punycode(\*(Aqihqwcrb4cv8a8dqg056pqjye\*(Aq); # 他们为什么不说中文 .Ve .PP Takes a Punycode encoding and returns original Unicode string. .SH "AUTHOR" .IX Header "AUTHOR" Tatsuhiko Miyagawa <\fImiyagawa@bulknews.net\fR> is the author of IDNA::Punycode which was the basis for this module. .SH "SEE ALSO" .IX Header "SEE ALSO" IDNA::Punycode, \s-1RFC 3492\s0 <https://tools.ietf.org/html/rfc3492>, \&\s-1RFC 5891\s0 <https://tools.ietf.org/html/rfc5891> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[we7�.� .� man3/URI.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI 3" .TH URI 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI \- Uniform Resource Identifiers (absolute and relative) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI (); \& \& $u1 = URI\->new("http://www.example.com"); \& $u2 = URI\->new("foo", "http"); \& $u3 = $u2\->abs($u1); \& $u4 = $u3\->clone; \& $u5 = URI\->new("HTTP://WWW.example.com:80")\->canonical; \& \& $str = $u\->as_string; \& $str = "$u"; \& \& $scheme = $u\->scheme; \& $opaque = $u\->opaque; \& $path = $u\->path; \& $frag = $u\->fragment; \& \& $u\->scheme("ftp"); \& $u\->host("ftp.example.com"); \& $u\->path("cpan/"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements the \f(CW\*(C`URI\*(C'\fR class. Objects of this class represent \*(L"Uniform Resource Identifier references\*(R" as specified in \s-1RFC 2396\s0 (and updated by \s-1RFC 2732\s0). .PP A Uniform Resource Identifier is a compact string of characters that identifies an abstract or physical resource. A Uniform Resource Identifier can be further classified as either a Uniform Resource Locator (\s-1URL\s0) or a Uniform Resource Name (\s-1URN\s0). The distinction between \s-1URL\s0 and \s-1URN\s0 does not matter to the \f(CW\*(C`URI\*(C'\fR class interface. A \&\*(L"URI-reference\*(R" is a \s-1URI\s0 that may have additional information attached in the form of a fragment identifier. .PP An absolute \s-1URI\s0 reference consists of three parts: a \fIscheme\fR, a \&\fIscheme-specific part\fR and a \fIfragment\fR identifier. A subset of \s-1URI\s0 references share a common syntax for hierarchical namespaces. For these, the scheme-specific part is further broken down into \&\fIauthority\fR, \fIpath\fR and \fIquery\fR components. These URIs can also take the form of relative \s-1URI\s0 references, where the scheme (and usually also the authority) component is missing, but implied by the context of the \s-1URI\s0 reference. The three forms of \s-1URI\s0 reference syntax are summarized as follows: .PP .Vb 3 \& <scheme>:<scheme\-specific\-part>#<fragment> \& <scheme>://<authority><path>?<query>#<fragment> \& <path>?<query>#<fragment> .Ve .PP The components into which a \s-1URI\s0 reference can be divided depend on the \&\fIscheme\fR. The \f(CW\*(C`URI\*(C'\fR class provides methods to get and set the individual components. The methods available for a specific \&\f(CW\*(C`URI\*(C'\fR object depend on the scheme. .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" The following methods construct new \f(CW\*(C`URI\*(C'\fR objects: .ie n .IP "$uri = \s-1URI\-\s0>new( $str )" 4 .el .IP "\f(CW$uri\fR = \s-1URI\-\s0>new( \f(CW$str\fR )" 4 .IX Item "$uri = URI->new( $str )" .PD 0 .ie n .IP "$uri = \s-1URI\-\s0>new( $str, $scheme )" 4 .el .IP "\f(CW$uri\fR = \s-1URI\-\s0>new( \f(CW$str\fR, \f(CW$scheme\fR )" 4 .IX Item "$uri = URI->new( $str, $scheme )" .PD Constructs a new \s-1URI\s0 object. The string representation of a \s-1URI\s0 is given as argument, together with an optional scheme specification. Common \s-1URI\s0 wrappers like "" and <>, as well as leading and trailing white space, are automatically removed from the \f(CW$str\fR argument before it is processed further. .Sp The constructor determines the scheme, maps this to an appropriate \&\s-1URI\s0 subclass, constructs a new object of that class and returns it. .Sp If the scheme isn't one of those that \s-1URI\s0 recognizes, you still get an \s-1URI\s0 object back that you can access the generic methods on. The \&\f(CW\*(C`$uri\->has_recognized_scheme\*(C'\fR method can be used to test for this. .Sp The \f(CW$scheme\fR argument is only used when \f(CW$str\fR is a relative \s-1URI.\s0 It can be either a simple string that denotes the scheme, a string containing an absolute \s-1URI\s0 reference, or an absolute \f(CW\*(C`URI\*(C'\fR object. If no \f(CW$scheme\fR is specified for a relative \&\s-1URI\s0 \f(CW$str\fR, then \f(CW$str\fR is simply treated as a generic \s-1URI\s0 (no scheme-specific methods available). .Sp The set of characters available for building \s-1URI\s0 references is restricted (see URI::Escape). Characters outside this set are automatically escaped by the \s-1URI\s0 constructor. .ie n .IP "$uri = \s-1URI\-\s0>new_abs( $str, $base_uri )" 4 .el .IP "\f(CW$uri\fR = \s-1URI\-\s0>new_abs( \f(CW$str\fR, \f(CW$base_uri\fR )" 4 .IX Item "$uri = URI->new_abs( $str, $base_uri )" Constructs a new absolute \s-1URI\s0 object. The \f(CW$str\fR argument can denote a relative or absolute \s-1URI.\s0 If relative, then it is absolutized using \f(CW$base_uri\fR as base. The \f(CW$base_uri\fR must be an absolute \&\s-1URI.\s0 .ie n .IP "$uri = URI::file\->new( $filename )" 4 .el .IP "\f(CW$uri\fR = URI::file\->new( \f(CW$filename\fR )" 4 .IX Item "$uri = URI::file->new( $filename )" .PD 0 .ie n .IP "$uri = URI::file\->new( $filename, $os )" 4 .el .IP "\f(CW$uri\fR = URI::file\->new( \f(CW$filename\fR, \f(CW$os\fR )" 4 .IX Item "$uri = URI::file->new( $filename, $os )" .PD Constructs a new \fIfile\fR \s-1URI\s0 from a file name. See URI::file. .ie n .IP "$uri = URI::file\->new_abs( $filename )" 4 .el .IP "\f(CW$uri\fR = URI::file\->new_abs( \f(CW$filename\fR )" 4 .IX Item "$uri = URI::file->new_abs( $filename )" .PD 0 .ie n .IP "$uri = URI::file\->new_abs( $filename, $os )" 4 .el .IP "\f(CW$uri\fR = URI::file\->new_abs( \f(CW$filename\fR, \f(CW$os\fR )" 4 .IX Item "$uri = URI::file->new_abs( $filename, $os )" .PD Constructs a new absolute \fIfile\fR \s-1URI\s0 from a file name. See URI::file. .ie n .IP "$uri = URI::file\->cwd" 4 .el .IP "\f(CW$uri\fR = URI::file\->cwd" 4 .IX Item "$uri = URI::file->cwd" Returns the current working directory as a \fIfile\fR \s-1URI.\s0 See URI::file. .ie n .IP "$uri\->clone" 4 .el .IP "\f(CW$uri\fR\->clone" 4 .IX Item "$uri->clone" Returns a copy of the \f(CW$uri\fR. .SH "COMMON METHODS" .IX Header "COMMON METHODS" The methods described in this section are available for all \f(CW\*(C`URI\*(C'\fR objects. .PP Methods that give access to components of a \s-1URI\s0 always return the old value of the component. The value returned is \f(CW\*(C`undef\*(C'\fR if the component was not present. There is generally a difference between a component that is empty (represented as \f(CW""\fR) and a component that is missing (represented as \f(CW\*(C`undef\*(C'\fR). If an accessor method is given an argument, it updates the corresponding component in addition to returning the old value of the component. Passing an undefined argument removes the component (if possible). The description of each accessor method indicates whether the component is passed as an escaped (percent-encoded) or an unescaped string. A component that can be further divided into sub-parts are usually passed escaped, as unescaping might change its semantics. .PP The common methods available for all \s-1URI\s0 are: .ie n .IP "$uri\->scheme" 4 .el .IP "\f(CW$uri\fR\->scheme" 4 .IX Item "$uri->scheme" .PD 0 .ie n .IP "$uri\->scheme( $new_scheme )" 4 .el .IP "\f(CW$uri\fR\->scheme( \f(CW$new_scheme\fR )" 4 .IX Item "$uri->scheme( $new_scheme )" .PD Sets and returns the scheme part of the \f(CW$uri\fR. If the \f(CW$uri\fR is relative, then \f(CW$uri\fR\->scheme returns \f(CW\*(C`undef\*(C'\fR. If called with an argument, it updates the scheme of \f(CW$uri\fR, possibly changing the class of \f(CW$uri\fR, and returns the old scheme value. The method croaks if the new scheme name is illegal; a scheme name must begin with a letter and must consist of only US-ASCII letters, numbers, and a few special marks: \*(L".\*(R", \*(L"+\*(R", \*(L"\-\*(R". This restriction effectively means that the scheme must be passed unescaped. Passing an undefined argument to the scheme method makes the \s-1URI\s0 relative (if possible). .Sp Letter case does not matter for scheme names. The string returned by \f(CW$uri\fR\->scheme is always lowercase. If you want the scheme just as it was written in the \s-1URI\s0 in its original case, you can use the \f(CW$uri\fR\->_scheme method instead. .ie n .IP "$uri\->has_recognized_scheme" 4 .el .IP "\f(CW$uri\fR\->has_recognized_scheme" 4 .IX Item "$uri->has_recognized_scheme" Returns \s-1TRUE\s0 if the \s-1URI\s0 scheme is one that \s-1URI\s0 recognizes. .Sp It will also be \s-1TRUE\s0 for relative URLs where a recognized scheme was provided to the constructor, even if \f(CW\*(C`$uri\->scheme\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR for these. .ie n .IP "$uri\->opaque" 4 .el .IP "\f(CW$uri\fR\->opaque" 4 .IX Item "$uri->opaque" .PD 0 .ie n .IP "$uri\->opaque( $new_opaque )" 4 .el .IP "\f(CW$uri\fR\->opaque( \f(CW$new_opaque\fR )" 4 .IX Item "$uri->opaque( $new_opaque )" .PD Sets and returns the scheme-specific part of the \f(CW$uri\fR (everything between the scheme and the fragment) as an escaped string. .ie n .IP "$uri\->path" 4 .el .IP "\f(CW$uri\fR\->path" 4 .IX Item "$uri->path" .PD 0 .ie n .IP "$uri\->path( $new_path )" 4 .el .IP "\f(CW$uri\fR\->path( \f(CW$new_path\fR )" 4 .IX Item "$uri->path( $new_path )" .PD Sets and returns the same value as \f(CW$uri\fR\->opaque unless the \s-1URI\s0 supports the generic syntax for hierarchical namespaces. In that case the generic method is overridden to set and return the part of the \s-1URI\s0 between the \fIhost name\fR and the \fIfragment\fR. .ie n .IP "$uri\->fragment" 4 .el .IP "\f(CW$uri\fR\->fragment" 4 .IX Item "$uri->fragment" .PD 0 .ie n .IP "$uri\->fragment( $new_frag )" 4 .el .IP "\f(CW$uri\fR\->fragment( \f(CW$new_frag\fR )" 4 .IX Item "$uri->fragment( $new_frag )" .PD Returns the fragment identifier of a \s-1URI\s0 reference as an escaped string. .ie n .IP "$uri\->as_string" 4 .el .IP "\f(CW$uri\fR\->as_string" 4 .IX Item "$uri->as_string" Returns a \s-1URI\s0 object to a plain \s-1ASCII\s0 string. \s-1URI\s0 objects are also converted to plain strings automatically by overloading. This means that \f(CW$uri\fR objects can be used as plain strings in most Perl constructs. .ie n .IP "$uri\->as_iri" 4 .el .IP "\f(CW$uri\fR\->as_iri" 4 .IX Item "$uri->as_iri" Returns a Unicode string representing the \s-1URI.\s0 Escaped \s-1UTF\-8\s0 sequences representing non-ASCII characters are turned into their corresponding Unicode code point. .ie n .IP "$uri\->canonical" 4 .el .IP "\f(CW$uri\fR\->canonical" 4 .IX Item "$uri->canonical" Returns a normalized version of the \s-1URI.\s0 The rules for normalization are scheme-dependent. They usually involve lowercasing the scheme and Internet host name components, removing the explicit port specification if it matches the default port, uppercasing all escape sequences, and unescaping octets that can be better represented as plain characters. .Sp For efficiency reasons, if the \f(CW$uri\fR is already in normalized form, then a reference to it is returned instead of a copy. .ie n .IP "$uri\->eq( $other_uri )" 4 .el .IP "\f(CW$uri\fR\->eq( \f(CW$other_uri\fR )" 4 .IX Item "$uri->eq( $other_uri )" .PD 0 .ie n .IP "URI::eq( $first_uri, $other_uri )" 4 .el .IP "URI::eq( \f(CW$first_uri\fR, \f(CW$other_uri\fR )" 4 .IX Item "URI::eq( $first_uri, $other_uri )" .PD Tests whether two \s-1URI\s0 references are equal. \s-1URI\s0 references that normalize to the same string are considered equal. The method can also be used as a plain function which can also test two string arguments. .Sp If you need to test whether two \f(CW\*(C`URI\*(C'\fR object references denote the same object, use the '==' operator. .ie n .IP "$uri\->abs( $base_uri )" 4 .el .IP "\f(CW$uri\fR\->abs( \f(CW$base_uri\fR )" 4 .IX Item "$uri->abs( $base_uri )" Returns an absolute \s-1URI\s0 reference. If \f(CW$uri\fR is already absolute, then a reference to it is simply returned. If the \f(CW$uri\fR is relative, then a new absolute \s-1URI\s0 is constructed by combining the \&\f(CW$uri\fR and the \f(CW$base_uri\fR, and returned. .ie n .IP "$uri\->rel( $base_uri )" 4 .el .IP "\f(CW$uri\fR\->rel( \f(CW$base_uri\fR )" 4 .IX Item "$uri->rel( $base_uri )" Returns a relative \s-1URI\s0 reference if it is possible to make one that denotes the same resource relative to \f(CW$base_uri\fR. If not, then \f(CW$uri\fR is simply returned. .ie n .IP "$uri\->secure" 4 .el .IP "\f(CW$uri\fR\->secure" 4 .IX Item "$uri->secure" Returns a \s-1TRUE\s0 value if the \s-1URI\s0 is considered to point to a resource on a secure channel, such as an \s-1SSL\s0 or \s-1TLS\s0 encrypted one. .SH "GENERIC METHODS" .IX Header "GENERIC METHODS" The following methods are available to schemes that use the common/generic syntax for hierarchical namespaces. The descriptions of schemes below indicate which these are. Unrecognized schemes are assumed to support the generic syntax, and therefore the following methods: .ie n .IP "$uri\->authority" 4 .el .IP "\f(CW$uri\fR\->authority" 4 .IX Item "$uri->authority" .PD 0 .ie n .IP "$uri\->authority( $new_authority )" 4 .el .IP "\f(CW$uri\fR\->authority( \f(CW$new_authority\fR )" 4 .IX Item "$uri->authority( $new_authority )" .PD Sets and returns the escaped authority component of the \f(CW$uri\fR. .ie n .IP "$uri\->path" 4 .el .IP "\f(CW$uri\fR\->path" 4 .IX Item "$uri->path" .PD 0 .ie n .IP "$uri\->path( $new_path )" 4 .el .IP "\f(CW$uri\fR\->path( \f(CW$new_path\fR )" 4 .IX Item "$uri->path( $new_path )" .PD Sets and returns the escaped path component of the \f(CW$uri\fR (the part between the host name and the query or fragment). The path can never be undefined, but it can be the empty string. .ie n .IP "$uri\->path_query" 4 .el .IP "\f(CW$uri\fR\->path_query" 4 .IX Item "$uri->path_query" .PD 0 .ie n .IP "$uri\->path_query( $new_path_query )" 4 .el .IP "\f(CW$uri\fR\->path_query( \f(CW$new_path_query\fR )" 4 .IX Item "$uri->path_query( $new_path_query )" .PD Sets and returns the escaped path and query components as a single entity. The path and the query are separated by a \*(L"?\*(R" character, but the query can itself contain \*(L"?\*(R". .ie n .IP "$uri\->path_segments" 4 .el .IP "\f(CW$uri\fR\->path_segments" 4 .IX Item "$uri->path_segments" .PD 0 .ie n .IP "$uri\->path_segments( $segment, ... )" 4 .el .IP "\f(CW$uri\fR\->path_segments( \f(CW$segment\fR, ... )" 4 .IX Item "$uri->path_segments( $segment, ... )" .PD Sets and returns the path. In a scalar context, it returns the same value as \f(CW$uri\fR\->path. In a list context, it returns the unescaped path segments that make up the path. Path segments that have parameters are returned as an anonymous array. The first element is the unescaped path segment proper; subsequent elements are escaped parameter strings. Such an anonymous array uses overloading so it can be treated as a string too, but this string does not include the parameters. .Sp Note that absolute paths have the empty string as their first \&\fIpath_segment\fR, i.e. the \fIpath\fR \f(CW\*(C`/foo/bar\*(C'\fR have 3 \&\fIpath_segments\fR; "\*(L", \*(R"foo\*(L" and \*(R"bar". .ie n .IP "$uri\->query" 4 .el .IP "\f(CW$uri\fR\->query" 4 .IX Item "$uri->query" .PD 0 .ie n .IP "$uri\->query( $new_query )" 4 .el .IP "\f(CW$uri\fR\->query( \f(CW$new_query\fR )" 4 .IX Item "$uri->query( $new_query )" .PD Sets and returns the escaped query component of the \f(CW$uri\fR. .ie n .IP "$uri\->query_form" 4 .el .IP "\f(CW$uri\fR\->query_form" 4 .IX Item "$uri->query_form" .PD 0 .ie n .IP "$uri\->query_form( $key1 => $val1, $key2 => $val2, ... )" 4 .el .IP "\f(CW$uri\fR\->query_form( \f(CW$key1\fR => \f(CW$val1\fR, \f(CW$key2\fR => \f(CW$val2\fR, ... )" 4 .IX Item "$uri->query_form( $key1 => $val1, $key2 => $val2, ... )" .ie n .IP "$uri\->query_form( $key1 => $val1, $key2 => $val2, ..., $delim )" 4 .el .IP "\f(CW$uri\fR\->query_form( \f(CW$key1\fR => \f(CW$val1\fR, \f(CW$key2\fR => \f(CW$val2\fR, ..., \f(CW$delim\fR )" 4 .IX Item "$uri->query_form( $key1 => $val1, $key2 => $val2, ..., $delim )" .ie n .IP "$uri\->query_form( \e@key_value_pairs )" 4 .el .IP "\f(CW$uri\fR\->query_form( \e@key_value_pairs )" 4 .IX Item "$uri->query_form( @key_value_pairs )" .ie n .IP "$uri\->query_form( \e@key_value_pairs, $delim )" 4 .el .IP "\f(CW$uri\fR\->query_form( \e@key_value_pairs, \f(CW$delim\fR )" 4 .IX Item "$uri->query_form( @key_value_pairs, $delim )" .ie n .IP "$uri\->query_form( \e%hash )" 4 .el .IP "\f(CW$uri\fR\->query_form( \e%hash )" 4 .IX Item "$uri->query_form( %hash )" .ie n .IP "$uri\->query_form( \e%hash, $delim )" 4 .el .IP "\f(CW$uri\fR\->query_form( \e%hash, \f(CW$delim\fR )" 4 .IX Item "$uri->query_form( %hash, $delim )" .PD Sets and returns query components that use the \&\fIapplication/x\-www\-form\-urlencoded\fR format. Key/value pairs are separated by \*(L"&\*(R", and the key is separated from the value by a \*(L"=\*(R" character. .Sp The form can be set either by passing separate key/value pairs, or via an array or hash reference. Passing an empty array or an empty hash removes the query component, whereas passing no arguments at all leaves the component unchanged. The order of keys is undefined if a hash reference is passed. The old value is always returned as a list of separate key/value pairs. Assigning this list to a hash is unwise as the keys returned might repeat. .Sp The values passed when setting the form can be plain strings or references to arrays of strings. Passing an array of values has the same effect as passing the key repeatedly with one value at a time. All the following statements have the same effect: .Sp .Vb 5 \& $uri\->query_form(foo => 1, foo => 2); \& $uri\->query_form(foo => [1, 2]); \& $uri\->query_form([ foo => 1, foo => 2 ]); \& $uri\->query_form([ foo => [1, 2] ]); \& $uri\->query_form({ foo => [1, 2] }); .Ve .Sp The \f(CW$delim\fR parameter can be passed as \*(L";\*(R" to force the key/value pairs to be delimited by \*(L";\*(R" instead of \*(L"&\*(R" in the query string. This practice is often recommended for URLs embedded in \s-1HTML\s0 or \s-1XML\s0 documents as this avoids the trouble of escaping the \*(L"&\*(R" character. You might also set the \f(CW$URI::DEFAULT_QUERY_FORM_DELIMITER\fR variable to \&\*(L";\*(R" for the same global effect. .ie n .IP "@keys = $u\->query_param" 4 .el .IP "\f(CW@keys\fR = \f(CW$u\fR\->query_param" 4 .IX Item "@keys = $u->query_param" .PD 0 .ie n .IP "@values = $u\->query_param( $key )" 4 .el .IP "\f(CW@values\fR = \f(CW$u\fR\->query_param( \f(CW$key\fR )" 4 .IX Item "@values = $u->query_param( $key )" .ie n .IP "$first_value = $u\->query_param( $key )" 4 .el .IP "\f(CW$first_value\fR = \f(CW$u\fR\->query_param( \f(CW$key\fR )" 4 .IX Item "$first_value = $u->query_param( $key )" .ie n .IP "$u\->query_param( $key, $value,... )" 4 .el .IP "\f(CW$u\fR\->query_param( \f(CW$key\fR, \f(CW$value\fR,... )" 4 .IX Item "$u->query_param( $key, $value,... )" .PD If \f(CW$u\fR\->query_param is called with no arguments, it returns all the distinct parameter keys of the \s-1URI.\s0 In a scalar context it returns the number of distinct keys. .Sp When a \f(CW$key\fR argument is given, the method returns the parameter values with the given key. In a scalar context, only the first parameter value is returned. .Sp If additional arguments are given, they are used to update successive parameters with the given key. If any of the values provided are array references, then the array is dereferenced to get the actual values. .Sp Please note that you can supply multiple values to this method, but you cannot supply multiple keys. .Sp Do this: .Sp .Vb 1 \& $uri\->query_param( widget_id => 1, 5, 9 ); .Ve .Sp Do \s-1NOT\s0 do this: .Sp .Vb 1 \& $uri\->query_param( widget_id => 1, frobnicator_id => 99 ); .Ve .ie n .IP "$u\->query_param_append($key, $value,...)" 4 .el .IP "\f(CW$u\fR\->query_param_append($key, \f(CW$value\fR,...)" 4 .IX Item "$u->query_param_append($key, $value,...)" Adds new parameters with the given key without touching any old parameters with the same key. It can be explained as a more efficient version of: .Sp .Vb 3 \& $u\->query_param($key, \& $u\->query_param($key), \& $value,...); .Ve .Sp One difference is that this expression would return the old values of \f(CW$key\fR, whereas the \fBquery_param_append()\fR method does not. .ie n .IP "@values = $u\->query_param_delete($key)" 4 .el .IP "\f(CW@values\fR = \f(CW$u\fR\->query_param_delete($key)" 4 .IX Item "@values = $u->query_param_delete($key)" .PD 0 .ie n .IP "$first_value = $u\->query_param_delete($key)" 4 .el .IP "\f(CW$first_value\fR = \f(CW$u\fR\->query_param_delete($key)" 4 .IX Item "$first_value = $u->query_param_delete($key)" .PD Deletes all key/value pairs with the given key. The old values are returned. In a scalar context, only the first value is returned. .Sp Using the \fBquery_param_delete()\fR method is slightly more efficient than the equivalent: .Sp .Vb 1 \& $u\->query_param($key, []); .Ve .ie n .IP "$hashref = $u\->query_form_hash" 4 .el .IP "\f(CW$hashref\fR = \f(CW$u\fR\->query_form_hash" 4 .IX Item "$hashref = $u->query_form_hash" .PD 0 .ie n .IP "$u\->query_form_hash( \e%new_form )" 4 .el .IP "\f(CW$u\fR\->query_form_hash( \e%new_form )" 4 .IX Item "$u->query_form_hash( %new_form )" .PD Returns a reference to a hash that represents the query form's key/value pairs. If a key occurs multiple times, then the hash value becomes an array reference. .Sp Note that sequence information is lost. This means that: .Sp .Vb 1 \& $u\->query_form_hash($u\->query_form_hash); .Ve .Sp is not necessarily a no-op, as it may reorder the key/value pairs. The values returned by the \fBquery_param()\fR method should stay the same though. .ie n .IP "$uri\->query_keywords" 4 .el .IP "\f(CW$uri\fR\->query_keywords" 4 .IX Item "$uri->query_keywords" .PD 0 .ie n .IP "$uri\->query_keywords( $keywords, ... )" 4 .el .IP "\f(CW$uri\fR\->query_keywords( \f(CW$keywords\fR, ... )" 4 .IX Item "$uri->query_keywords( $keywords, ... )" .ie n .IP "$uri\->query_keywords( \e@keywords )" 4 .el .IP "\f(CW$uri\fR\->query_keywords( \e@keywords )" 4 .IX Item "$uri->query_keywords( @keywords )" .PD Sets and returns query components that use the keywords separated by \*(L"+\*(R" format. .Sp The keywords can be set either by passing separate keywords directly or by passing a reference to an array of keywords. Passing an empty array removes the query component, whereas passing no arguments at all leaves the component unchanged. The old value is always returned as a list of separate words. .SH "SERVER METHODS" .IX Header "SERVER METHODS" For schemes where the \fIauthority\fR component denotes an Internet host, the following methods are available in addition to the generic methods. .ie n .IP "$uri\->userinfo" 4 .el .IP "\f(CW$uri\fR\->userinfo" 4 .IX Item "$uri->userinfo" .PD 0 .ie n .IP "$uri\->userinfo( $new_userinfo )" 4 .el .IP "\f(CW$uri\fR\->userinfo( \f(CW$new_userinfo\fR )" 4 .IX Item "$uri->userinfo( $new_userinfo )" .PD Sets and returns the escaped userinfo part of the authority component. .Sp For some schemes this is a user name and a password separated by a colon. This practice is not recommended. Embedding passwords in clear text (such as \s-1URI\s0) has proven to be a security risk in almost every case where it has been used. .ie n .IP "$uri\->host" 4 .el .IP "\f(CW$uri\fR\->host" 4 .IX Item "$uri->host" .PD 0 .ie n .IP "$uri\->host( $new_host )" 4 .el .IP "\f(CW$uri\fR\->host( \f(CW$new_host\fR )" 4 .IX Item "$uri->host( $new_host )" .PD Sets and returns the unescaped hostname. .Sp If the \f(CW$new_host\fR string ends with a colon and a number, then this number also sets the port. .Sp For IPv6 addresses the brackets around the raw address is removed in the return value from \f(CW$uri\fR\->host. When setting the host attribute to an IPv6 address you can use a raw address or one enclosed in brackets. The address needs to be enclosed in brackets if you want to pass in a new port value as well. .Sp .Vb 2 \& my $uri = URI\->new("http://www.\exC3\exBCri\-sample/foo/bar.html"); \& print $u\->host; # www.xn\-\-ri\-sample\-fra0f .Ve .ie n .IP "$uri\->ihost" 4 .el .IP "\f(CW$uri\fR\->ihost" 4 .IX Item "$uri->ihost" Returns the host in Unicode form. Any \s-1IDNA\s0 A\-labels (encoded unicode chars with \&\fIxn\*(--\fR prefix) are turned into U\-labels (unicode chars). .Sp .Vb 2 \& my $uri = URI\->new("http://www.\exC3\exBCri\-sample/foo/bar.html"); \& print $u\->ihost; # www.\exC3\exBCri\-sample .Ve .ie n .IP "$uri\->port" 4 .el .IP "\f(CW$uri\fR\->port" 4 .IX Item "$uri->port" .PD 0 .ie n .IP "$uri\->port( $new_port )" 4 .el .IP "\f(CW$uri\fR\->port( \f(CW$new_port\fR )" 4 .IX Item "$uri->port( $new_port )" .PD Sets and returns the port. The port is a simple integer that should be greater than 0. .Sp If a port is not specified explicitly in the \s-1URI,\s0 then the \s-1URI\s0 scheme's default port is returned. If you don't want the default port substituted, then you can use the \f(CW$uri\fR\->_port method instead. .ie n .IP "$uri\->host_port" 4 .el .IP "\f(CW$uri\fR\->host_port" 4 .IX Item "$uri->host_port" .PD 0 .ie n .IP "$uri\->host_port( $new_host_port )" 4 .el .IP "\f(CW$uri\fR\->host_port( \f(CW$new_host_port\fR )" 4 .IX Item "$uri->host_port( $new_host_port )" .PD Sets and returns the host and port as a single unit. The returned value includes a port, even if it matches the default port. The host part and the port part are separated by a colon: \*(L":\*(R". .Sp For IPv6 addresses the bracketing is preserved; thus \&\s-1URI\-\s0>new(\*(L"http://[::1]/\*(R")\->host_port returns \*(L"[::1]:80\*(R". Contrast this with \&\f(CW$uri\fR\->host which will remove the brackets. .ie n .IP "$uri\->default_port" 4 .el .IP "\f(CW$uri\fR\->default_port" 4 .IX Item "$uri->default_port" Returns the default port of the \s-1URI\s0 scheme to which \f(CW$uri\fR belongs. For \fIhttp\fR this is the number 80, for \fIftp\fR this is the number 21, etc. The default port for a scheme can not be changed. .SH "SCHEME-SPECIFIC SUPPORT" .IX Header "SCHEME-SPECIFIC SUPPORT" Scheme-specific support is provided for the following \s-1URI\s0 schemes. For \f(CW\*(C`URI\*(C'\fR objects that do not belong to one of these, you can only use the common and generic methods. .IP "\fBdata\fR:" 4 .IX Item "data:" The \fIdata\fR \s-1URI\s0 scheme is specified in \s-1RFC 2397.\s0 It allows inclusion of small data items as \*(L"immediate\*(R" data, as if it had been included externally. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the data scheme support the common methods and two new methods to access their scheme-specific components: \&\f(CW$uri\fR\->media_type and \f(CW$uri\fR\->data. See URI::data for details. .IP "\fBfile\fR:" 4 .IX Item "file:" An old specification of the \fIfile\fR \s-1URI\s0 scheme is found in \s-1RFC 1738. A\s0 new \s-1RFC 2396\s0 based specification in not available yet, but file \s-1URI\s0 references are in common use. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the file scheme support the common and generic methods. In addition, they provide two methods for mapping file URIs back to local file names; \f(CW$uri\fR\->file and \f(CW$uri\fR\->dir. See URI::file for details. .IP "\fBftp\fR:" 4 .IX Item "ftp:" An old specification of the \fIftp\fR \s-1URI\s0 scheme is found in \s-1RFC 1738.\s0 A new \s-1RFC 2396\s0 based specification in not available yet, but ftp \s-1URI\s0 references are in common use. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the ftp scheme support the common, generic and server methods. In addition, they provide two methods for accessing the userinfo sub-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password. .IP "\fBgopher\fR:" 4 .IX Item "gopher:" The \fIgopher\fR \s-1URI\s0 scheme is specified in <draft\-murali\-url\-gopher\-1996\-12\-04> and will hopefully be available as a \s-1RFC 2396\s0 based specification. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the gopher scheme support the common, generic and server methods. In addition, they support some methods for accessing gopher-specific path components: \f(CW$uri\fR\->gopher_type, \&\f(CW$uri\fR\->selector, \f(CW$uri\fR\->search, \f(CW$uri\fR\->string. .IP "\fBhttp\fR:" 4 .IX Item "http:" The \fIhttp\fR \s-1URI\s0 scheme is specified in \s-1RFC 2616.\s0 The scheme is used to reference resources hosted by \s-1HTTP\s0 servers. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the http scheme support the common, generic and server methods. .IP "\fBhttps\fR:" 4 .IX Item "https:" The \fIhttps\fR \s-1URI\s0 scheme is a Netscape invention which is commonly implemented. The scheme is used to reference \s-1HTTP\s0 servers through \s-1SSL\s0 connections. Its syntax is the same as http, but the default port is different. .IP "\fBgeo\fR:" 4 .IX Item "geo:" The \fIgeo\fR \s-1URI\s0 scheme is specified in \s-1RFC 5870\s0 <http://tools.ietf.org/html/rfc5870>. The scheme is used to reference physical location in a two\- or three-dimensional coordinate reference system in a compact, simple, human-readable, and protocol-independent way. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the geo scheme support the common methods. .IP "\fBicap\fR:" 4 .IX Item "icap:" The \fIicap\fR \s-1URI\s0 scheme is specified in \s-1RFC 3507\s0 <http://tools.ietf.org/html/rfc3507>. The scheme is used to reference resources hosted by \s-1ICAP\s0 servers. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the icap scheme support the common, generic and server methods. .IP "\fBicaps\fR:" 4 .IX Item "icaps:" The \fIicaps\fR \s-1URI\s0 scheme is specified in \s-1RFC 3507\s0 <http://tools.ietf.org/html/rfc3507> as well. The scheme is used to reference \s-1ICAP\s0 servers through \s-1SSL\s0 connections. Its syntax is the same as icap, including the same default port. .IP "\fBldap\fR:" 4 .IX Item "ldap:" The \fIldap\fR \s-1URI\s0 scheme is specified in \s-1RFC 2255.\s0 \s-1LDAP\s0 is the Lightweight Directory Access Protocol. An ldap \s-1URI\s0 describes an \s-1LDAP\s0 search operation to perform to retrieve information from an \s-1LDAP\s0 directory. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the ldap scheme support the common, generic and server methods as well as ldap-specific methods: \f(CW$uri\fR\->dn, \&\f(CW$uri\fR\->attributes, \f(CW$uri\fR\->scope, \f(CW$uri\fR\->filter, \f(CW$uri\fR\->extensions. See URI::ldap for details. .IP "\fBldapi\fR:" 4 .IX Item "ldapi:" Like the \fIldap\fR \s-1URI\s0 scheme, but uses a \s-1UNIX\s0 domain socket. The server methods are not supported, and the local socket path is available as \f(CW$uri\fR\->un_path. The \fIldapi\fR scheme is used by the OpenLDAP package. There is no real specification for it, but it is mentioned in various OpenLDAP manual pages. .IP "\fBldaps\fR:" 4 .IX Item "ldaps:" Like the \fIldap\fR \s-1URI\s0 scheme, but uses an \s-1SSL\s0 connection. This scheme is deprecated, as the preferred way is to use the \fIstart_tls\fR mechanism. .IP "\fBmailto\fR:" 4 .IX Item "mailto:" The \fImailto\fR \s-1URI\s0 scheme is specified in \s-1RFC 2368.\s0 The scheme was originally used to designate the Internet mailing address of an individual or service. It has (in \s-1RFC 2368\s0) been extended to allow setting of other mail header fields and the message body. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the mailto scheme support the common methods and the generic query methods. In addition, they support the following mailto-specific methods: \f(CW$uri\fR\->to, \f(CW$uri\fR\->headers. .Sp Note that the \*(L"foo@example.com\*(R" part of a mailto is \fInot\fR the \&\f(CW\*(C`userinfo\*(C'\fR and \f(CW\*(C`host\*(C'\fR but instead the \f(CW\*(C`path\*(C'\fR. This allows a mailto \s-1URI\s0 to contain multiple comma separated email addresses. .IP "\fBmms\fR:" 4 .IX Item "mms:" The \fImms\fR \s-1URL\s0 specification can be found at <http://sdp.ppona.com/>. \&\f(CW\*(C`URI\*(C'\fR objects belonging to the mms scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components. .IP "\fBnews\fR:" 4 .IX Item "news:" The \fInews\fR, \fInntp\fR and \fIsnews\fR \s-1URI\s0 schemes are specified in <draft\-gilman\-news\-url\-01> and will hopefully be available as an \s-1RFC 2396\s0 based specification soon. (Update: as of April 2010, they are in \&\s-1RFC 5538\s0 <https://tools.ietf.org/html/rfc5538>. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the news scheme support the common, generic and server methods. In addition, they provide some methods to access the path: \f(CW$uri\fR\->group and \f(CW$uri\fR\->message. .IP "\fBnntp\fR:" 4 .IX Item "nntp:" See \fInews\fR scheme. .IP "\fBnntps\fR:" 4 .IX Item "nntps:" See \fInews\fR scheme and \s-1RFC 5538\s0 <https://tools.ietf.org/html/rfc5538>. .IP "\fBotpauth\fR:" 4 .IX Item "otpauth:" The \fIotpauth\fR \s-1URI\s0 scheme is specified in <https://github.com/google/google\-authenticator/wiki/Key\-Uri\-Format>. The scheme is used to encode secret keys for use in \s-1TOTP\s0 or \s-1HOTP\s0 schemes. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the otpauth scheme support the common methods. .IP "\fBpop\fR:" 4 .IX Item "pop:" The \fIpop\fR \s-1URI\s0 scheme is specified in \s-1RFC 2384.\s0 The scheme is used to reference a \s-1POP3\s0 mailbox. .Sp \&\f(CW\*(C`URI\*(C'\fR objects belonging to the pop scheme support the common, generic and server methods. In addition, they provide two methods to access the userinfo components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->auth .IP "\fBrlogin\fR:" 4 .IX Item "rlogin:" An old specification of the \fIrlogin\fR \s-1URI\s0 scheme is found in \s-1RFC 1738.\s0 \f(CW\*(C`URI\*(C'\fR objects belonging to the rlogin scheme support the common, generic and server methods. .IP "\fBrtsp\fR:" 4 .IX Item "rtsp:" The \fIrtsp\fR \s-1URL\s0 specification can be found in section 3.2 of \s-1RFC 2326.\s0 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the rtsp scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components. .IP "\fBrtspu\fR:" 4 .IX Item "rtspu:" The \fIrtspu\fR \s-1URI\s0 scheme is used to talk to \s-1RTSP\s0 servers over \s-1UDP\s0 instead of \s-1TCP.\s0 The syntax is the same as rtsp. .IP "\fBrsync\fR:" 4 .IX Item "rsync:" Information about rsync is available from <http://rsync.samba.org/>. \&\f(CW\*(C`URI\*(C'\fR objects belonging to the rsync scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password. .IP "\fBsip\fR:" 4 .IX Item "sip:" The \fIsip\fR \s-1URI\s0 specification is described in sections 19.1 and 25 of \s-1RFC 3261.\s0 \f(CW\*(C`URI\*(C'\fR objects belonging to the sip scheme support the common, generic, and server methods with the exception of path related sub-components. In addition, they provide two methods to get and set \&\fIsip\fR parameters: \f(CW$uri\fR\->params_form and \f(CW$uri\fR\->params. .IP "\fBsips\fR:" 4 .IX Item "sips:" See \fIsip\fR scheme. Its syntax is the same as sip, but the default port is different. .IP "\fBsnews\fR:" 4 .IX Item "snews:" See \fInews\fR scheme. Its syntax is the same as news, but the default port is different. .IP "\fBtelnet\fR:" 4 .IX Item "telnet:" An old specification of the \fItelnet\fR \s-1URI\s0 scheme is found in \s-1RFC 1738.\s0 \f(CW\*(C`URI\*(C'\fR objects belonging to the telnet scheme support the common, generic and server methods. .IP "\fBtn3270\fR:" 4 .IX Item "tn3270:" These URIs are used like \fItelnet\fR URIs but for connections to \s-1IBM\s0 mainframes. \f(CW\*(C`URI\*(C'\fR objects belonging to the tn3270 scheme support the common, generic and server methods. .IP "\fBssh\fR:" 4 .IX Item "ssh:" Information about ssh is available at <http://www.openssh.com/>. \&\f(CW\*(C`URI\*(C'\fR objects belonging to the ssh scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password. .IP "\fBsftp\fR:" 4 .IX Item "sftp:" \&\f(CW\*(C`URI\*(C'\fR objects belonging to the sftp scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password. .IP "\fBurn\fR:" 4 .IX Item "urn:" The syntax of Uniform Resource Names is specified in \s-1RFC 2141.\s0 \f(CW\*(C`URI\*(C'\fR objects belonging to the urn scheme provide the common methods, and also the methods \f(CW$uri\fR\->nid and \f(CW$uri\fR\->nss, which return the Namespace Identifier and the Namespace-Specific String respectively. .Sp The Namespace Identifier basically works like the Scheme identifier of URIs, and further divides the \s-1URN\s0 namespace. Namespace Identifier assignments are maintained at <http://www.iana.org/assignments/urn\-namespaces>. .Sp Letter case is not significant for the Namespace Identifier. It is always returned in lower case by the \f(CW$uri\fR\->nid method. The \f(CW$uri\fR\->_nid method can be used if you want it in its original case. .IP "\fBurn\fR:\fBisbn\fR:" 4 .IX Item "urn:isbn:" The \f(CW\*(C`urn:isbn:\*(C'\fR namespace contains International Standard Book Numbers (ISBNs) and is described in \s-1RFC 3187.\s0 A \f(CW\*(C`URI\*(C'\fR object belonging to this namespace has the following extra methods (if the Business::ISBN module is available): \f(CW$uri\fR\->isbn, \&\f(CW$uri\fR\->isbn_publisher_code, \f(CW$uri\fR\->isbn_group_code (formerly isbn_country_code, which is still supported by issues a deprecation warning), \f(CW$uri\fR\->isbn_as_ean. .IP "\fBurn\fR:\fBoid\fR:" 4 .IX Item "urn:oid:" The \f(CW\*(C`urn:oid:\*(C'\fR namespace contains Object Identifiers (OIDs) and is described in \s-1RFC 3061.\s0 An object identifier consists of sequences of digits separated by dots. A \f(CW\*(C`URI\*(C'\fR object belonging to this namespace has an additional method called \f(CW$uri\fR\->oid that can be used to get/set the oid value. In a list context, oid numbers are returned as separate elements. .SH "CONFIGURATION VARIABLES" .IX Header "CONFIGURATION VARIABLES" The following configuration variables influence how the class and its methods behave: .ie n .IP "$URI::ABS_ALLOW_RELATIVE_SCHEME" 4 .el .IP "\f(CW$URI::ABS_ALLOW_RELATIVE_SCHEME\fR" 4 .IX Item "$URI::ABS_ALLOW_RELATIVE_SCHEME" Some older parsers used to allow the scheme name to be present in the relative \s-1URL\s0 if it was the same as the base \s-1URL\s0 scheme. \s-1RFC 2396\s0 says that this should be avoided, but you can enable this old behaviour by setting the \f(CW$URI::ABS_ALLOW_RELATIVE_SCHEME\fR variable to a \s-1TRUE\s0 value. The difference is demonstrated by the following examples: .Sp .Vb 2 \& URI\->new("http:foo")\->abs("http://host/a/b") \& ==> "http:foo" \& \& local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1; \& URI\->new("http:foo")\->abs("http://host/a/b") \& ==> "http:/host/a/foo" .Ve .ie n .IP "$URI::ABS_REMOTE_LEADING_DOTS" 4 .el .IP "\f(CW$URI::ABS_REMOTE_LEADING_DOTS\fR" 4 .IX Item "$URI::ABS_REMOTE_LEADING_DOTS" You can also have the \fBabs()\fR method ignore excess \*(L"..\*(R" segments in the relative \s-1URI\s0 by setting \f(CW$URI::ABS_REMOTE_LEADING_DOTS\fR to a \s-1TRUE\s0 value. The difference is demonstrated by the following examples: .Sp .Vb 2 \& URI\->new("../../../foo")\->abs("http://host/a/b") \& ==> "http://host/../../foo" \& \& local $URI::ABS_REMOTE_LEADING_DOTS = 1; \& URI\->new("../../../foo")\->abs("http://host/a/b") \& ==> "http://host/foo" .Ve .ie n .IP "$URI::DEFAULT_QUERY_FORM_DELIMITER" 4 .el .IP "\f(CW$URI::DEFAULT_QUERY_FORM_DELIMITER\fR" 4 .IX Item "$URI::DEFAULT_QUERY_FORM_DELIMITER" This value can be set to \*(L";\*(R" to have the query form \f(CW\*(C`key=value\*(C'\fR pairs delimited by \*(L";\*(R" instead of \*(L"&\*(R" which is the default. .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" .IP "\s-1URI_HAS_RESERVED_SQUARE_BRACKETS\s0" 4 .IX Item "URI_HAS_RESERVED_SQUARE_BRACKETS" Before version 5.11, \s-1URI\s0 treated square brackets as reserved characters throughout the whole \s-1URI\s0 string. However, these brackets are reserved only within the authority/host part of the \s-1URI\s0 and nowhere else (\s-1RFC 3986\s0). .Sp Starting with version 5.11, \s-1URI\s0 takes this distinction into account. Setting the environment variable \f(CW\*(C`URI_HAS_RESERVED_SQUARE_BRACKETS\*(C'\fR (programmatically or via the shell), restores the old behavior. .Sp .Vb 5 \& #\-\- restore 5.10 behavior programmatically \& BEGIN { \& $ENV{URI_HAS_RESERVED_SQUARE_BRACKETS} = 1; \& } \& use URI (); .Ve .Sp \&\fINote\fR: This environment variable is just used during initialization and has to be set \fIbefore\fR module \s-1URI\s0 is used/required. Changing it at run time has no effect. .Sp Its value can be checked programmatically by accessing the constant \&\f(CW\*(C`URI::HAS_RESERVED_SQUARE_BRACKETS\*(C'\fR. .SH "BUGS" .IX Header "BUGS" There are some things that are not quite right: .IP "\(bu" 4 Using regexp variables like \f(CW$1\fR directly as arguments to the \s-1URI\s0 accessor methods does not work too well with current perl implementations. I would argue that this is actually a bug in perl. The workaround is to quote them. Example: .Sp .Vb 2 \& /(...)/ || die; \& $u\->query("$1"); .Ve .IP "\(bu" 4 The escaping (percent encoding) of chars in the 128 .. 255 range passed to the \&\s-1URI\s0 constructor or when setting \s-1URI\s0 parts using the accessor methods depend on the state of the internal \s-1UTF8\s0 flag (see utf8::is_utf8) of the string passed. If the \s-1UTF8\s0 flag is set the \s-1UTF\-8\s0 encoded version of the character is percent encoded. If the \s-1UTF8\s0 flag isn't set the Latin\-1 version (byte) of the character is percent encoded. This basically exposes the internal encoding of Perl strings. .SH "PARSING URIs WITH REGEXP" .IX Header "PARSING URIs WITH REGEXP" As an alternative to this module, the following (official) regular expression can be used to decode a \s-1URI:\s0 .PP .Vb 2 \& my($scheme, $authority, $path, $query, $fragment) = \& $uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\e?([^#]*))?(?:#(.*))?|; .Ve .PP The \f(CW\*(C`URI::Split\*(C'\fR module provides the function \fBuri_split()\fR as a readable alternative. .SH "SEE ALSO" .IX Header "SEE ALSO" URI::file, URI::WithBase, URI::Escape, URI::Split, URI::Heuristic .PP \&\s-1RFC 2396:\s0 \*(L"Uniform Resource Identifiers (\s-1URI\s0): Generic Syntax\*(R", Berners-Lee, Fielding, Masinter, August 1998. .PP <http://www.iana.org/assignments/uri\-schemes> .PP <http://www.iana.org/assignments/urn\-namespaces> .PP <http://www.w3.org/Addressing/> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1995\-2009 Gisle Aas. .PP Copyright 1995 Martijn Koster. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "AUTHORS / ACKNOWLEDGMENTS" .IX Header "AUTHORS / ACKNOWLEDGMENTS" This module is based on the \f(CW\*(C`URI::URL\*(C'\fR module, which in turn was (distantly) based on the \f(CW\*(C`wwwurl.pl\*(C'\fR code in the libwww-perl for perl4 developed by Roy Fielding, as part of the Arcadia project at the University of California, Irvine, with contributions from Brooks Cutter. .PP \&\f(CW\*(C`URI::URL\*(C'\fR was developed by Gisle Aas, Tim Bunce, Roy Fielding and Martijn Koster with input from other people on the libwww-perl mailing list. .PP \&\f(CW\*(C`URI\*(C'\fR and related subclasses was developed by Gisle Aas. PK � �[�0[- - man3/URI::icap.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::icap 3" .TH URI::icap 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::icap \- URI scheme for ICAP Identifiers .SH "VERSION" .IX Header "VERSION" Version 5.20 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI::icap; \& \& my $uri = URI\->new(\*(Aqicap://icap\-proxy.example.com/\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements the \f(CW\*(C`icap:\*(C'\fR \s-1URI\s0 scheme defined in \s-1RFC 3507\s0 <http://tools.ietf.org/html/rfc3507>, for the Internet Content Adaptation Protocol <https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol>. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" This module inherits the behaviour of URI::http and overrides the default_portdefault_port> method. .SS "default_port" .IX Subsection "default_port" The default port for icap servers is 1344 .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" See \s-1URI\s0 .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" See \s-1URI\s0 and \s-1URI\s0 .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" None .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" See \s-1URI\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1RFC 3507\s0 <http://tools.ietf.org/html/rfc3507> .SH "AUTHOR" .IX Header "AUTHOR" David Dick, \f(CW\*(C`<ddick at cpan.org>\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2016 David Dick. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See <http://dev.perl.org/licenses/> for more information. PK � �[��c� man3/URI::Escape.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::Escape 3" .TH URI::Escape 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::Escape \- Percent\-encode and percent\-decode unsafe characters .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use URI::Escape; \& $safe = uri_escape("10% is enough\en"); \& $verysafe = uri_escape("foo", "\e0\-\e377"); \& $str = uri_unescape($safe); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides functions to percent-encode and percent-decode \s-1URI\s0 strings as defined by \s-1RFC 3986.\s0 Percent-encoding \s-1URI\s0's is informally called \*(L"\s-1URI\s0 escaping\*(R". This is the terminology used by this module, which predates the formalization of the terms by the \s-1RFC\s0 by several years. .PP A \s-1URI\s0 consists of a restricted set of characters. The restricted set of characters consists of digits, letters, and a few graphic symbols chosen from those common to most of the character encodings and input facilities available to Internet users. They are made up of the \&\*(L"unreserved\*(R" and \*(L"reserved\*(R" character sets as defined in \s-1RFC 3986.\s0 .PP .Vb 4 \& unreserved = ALPHA / DIGIT / "\-" / "." / "_" / "~" \& reserved = ":" / "/" / "?" / "#" / "[" / "]" / "@" \& "!" / "$" / "&" / "\*(Aq" / "(" / ")" \& / "*" / "+" / "," / ";" / "=" .Ve .PP In addition, any byte (octet) can be represented in a \s-1URI\s0 by an escape sequence: a triplet consisting of the character \*(L"%\*(R" followed by two hexadecimal digits. A byte can also be represented directly by a character, using the US-ASCII character for that octet. .PP Some of the characters are \fIreserved\fR for use as delimiters or as part of certain \s-1URI\s0 components. These must be escaped if they are to be treated as ordinary data. Read \s-1RFC 3986\s0 for further details. .PP The functions provided (and exported by default) from this module are: .ie n .IP "uri_escape( $string )" 4 .el .IP "uri_escape( \f(CW$string\fR )" 4 .IX Item "uri_escape( $string )" .PD 0 .ie n .IP "uri_escape( $string, $unsafe )" 4 .el .IP "uri_escape( \f(CW$string\fR, \f(CW$unsafe\fR )" 4 .IX Item "uri_escape( $string, $unsafe )" .PD Replaces each unsafe character in the \f(CW$string\fR with the corresponding escape sequence and returns the result. The \f(CW$string\fR argument should be a string of bytes. The \fBuri_escape()\fR function will croak if given a characters with code above 255. Use \fBuri_escape_utf8()\fR if you know you have such chars or/and want chars in the 128 .. 255 range treated as \&\s-1UTF\-8.\s0 .Sp The \fBuri_escape()\fR function takes an optional second argument that overrides the set of characters that are to be escaped. The set is specified as a string that can be used in a regular expression character class (between [ ]). E.g.: .Sp .Vb 3 \& "\ex00\-\ex1f\ex7f\-\exff" # all control and hi\-bit characters \& "a\-z" # all lower case characters \& "^A\-Za\-z" # everything not a letter .Ve .Sp The default set of characters to be escaped is all those which are \&\fInot\fR part of the \f(CW\*(C`unreserved\*(C'\fR character class shown above as well as the reserved characters. I.e. the default is: .Sp .Vb 1 \& "^A\-Za\-z0\-9\e\-\e._~" .Ve .Sp The second argument can also be specified as a regular expression object: .Sp .Vb 1 \& qr/[^A\-Za\-z]/ .Ve .Sp Any strings matched by this regular expression will have all of their characters escaped. .ie n .IP "uri_escape_utf8( $string )" 4 .el .IP "uri_escape_utf8( \f(CW$string\fR )" 4 .IX Item "uri_escape_utf8( $string )" .PD 0 .ie n .IP "uri_escape_utf8( $string, $unsafe )" 4 .el .IP "uri_escape_utf8( \f(CW$string\fR, \f(CW$unsafe\fR )" 4 .IX Item "uri_escape_utf8( $string, $unsafe )" .PD Works like \fBuri_escape()\fR, but will encode chars as \s-1UTF\-8\s0 before escaping them. This makes this function able to deal with characters with code above 255 in \f(CW$string\fR. Note that chars in the 128 .. 255 range will be escaped differently by this function compared to what \&\fBuri_escape()\fR would. For chars in the 0 .. 127 range there is no difference. .Sp Equivalent to: .Sp .Vb 2 \& utf8::encode($string); \& my $uri = uri_escape($string); .Ve .Sp Note: JavaScript has a function called \fBescape()\fR that produces the sequence \*(L"%uXXXX\*(R" for chars in the 256 .. 65535 range. This function has really nothing to do with \s-1URI\s0 escaping but some folks got confused since it \*(L"does the right thing\*(R" in the 0 .. 255 range. Because of this you sometimes see \*(L"URIs\*(R" with these kind of escapes. The JavaScript \fBencodeURIComponent()\fR function is similar to \fBuri_escape_utf8()\fR. .IP "uri_unescape($string,...)" 4 .IX Item "uri_unescape($string,...)" Returns a string with each \f(CW%XX\fR sequence replaced with the actual byte (octet). .Sp This does the same as: .Sp .Vb 1 \& $string =~ s/%([0\-9A\-Fa\-f]{2})/chr(hex($1))/eg; .Ve .Sp but does not modify the string in-place as this \s-1RE\s0 would. Using the \&\fBuri_unescape()\fR function instead of the \s-1RE\s0 might make the code look cleaner and is a few characters less to type. .Sp In a simple benchmark test I did, calling the function (instead of the inline \s-1RE\s0 above) if a few chars were unescaped was something like 40% slower, and something like 700% slower if none were. If you are going to unescape a lot of times it might be a good idea to inline the \s-1RE.\s0 .Sp If the \fBuri_unescape()\fR function is passed multiple strings, then each one is returned unescaped. .PP The module can also export the \f(CW%escapes\fR hash, which contains the mapping from all 256 bytes to the corresponding escape codes. Lookup in this hash is faster than evaluating \f(CW\*(C`sprintf("%%%02X", ord($byte))\*(C'\fR each time. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1URI\s0 .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1995\-2004 Gisle Aas. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[��)U� � man3/URI::URL.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::URL 3" .TH URI::URL 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::URL \- Uniform Resource Locators .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& $u1 = URI::URL\->new($str, $base); \& $u2 = $u1\->abs; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is provided for backwards compatibility with modules that depend on the interface provided by the \f(CW\*(C`URI::URL\*(C'\fR class that used to be distributed with the libwww-perl library. .PP The following differences exist compared to the \f(CW\*(C`URI\*(C'\fR class interface: .IP "\(bu" 3 The \s-1URI::URL\s0 module exports the \fBurl()\fR function as an alternate constructor interface. .IP "\(bu" 3 The constructor takes an optional \f(CW$base\fR argument. The \f(CW\*(C`URI::URL\*(C'\fR class is a subclass of \f(CW\*(C`URI::WithBase\*(C'\fR. .IP "\(bu" 3 The \s-1URI::URL\-\s0>newlocal class method is the same as URI::file\->new_abs. .IP "\(bu" 3 \&\fBURI::URL::strict\fR\|(1) .IP "\(bu" 3 \&\f(CW$url\fR\->print_on method .IP "\(bu" 3 \&\f(CW$url\fR\->crack method .IP "\(bu" 3 \&\f(CW$url\fR\->full_path: same as ($uri\->abs_path || \*(L"/\*(R") .IP "\(bu" 3 \&\f(CW$url\fR\->netloc: same as \f(CW$uri\fR\->authority .IP "\(bu" 3 \&\f(CW$url\fR\->epath, \f(CW$url\fR\->equery: same as \f(CW$uri\fR\->path, \f(CW$uri\fR\->query .IP "\(bu" 3 \&\f(CW$url\fR\->path and \f(CW$url\fR\->query pass unescaped strings. .IP "\(bu" 3 \&\f(CW$url\fR\->path_components: same as \f(CW$uri\fR\->path_segments (if you don't consider path segment parameters) .IP "\(bu" 3 \&\f(CW$url\fR\->params and \f(CW$url\fR\->eparams methods .IP "\(bu" 3 \&\f(CW$url\fR\->base method. See URI::WithBase. .IP "\(bu" 3 \&\f(CW$url\fR\->abs and \f(CW$url\fR\->rel have an optional \f(CW$base\fR argument. See URI::WithBase. .IP "\(bu" 3 \&\f(CW$url\fR\->frag: same as \f(CW$uri\fR\->fragment .IP "\(bu" 3 \&\f(CW$url\fR\->keywords: same as \f(CW$uri\fR\->query_keywords .IP "\(bu" 3 \&\f(CW$url\fR\->localpath and friends map to \f(CW$uri\fR\->file. .IP "\(bu" 3 \&\f(CW$url\fR\->address and \f(CW$url\fR\->encoded822addr: same as \f(CW$uri\fR\->to for mailto \s-1URI\s0 .IP "\(bu" 3 \&\f(CW$url\fR\->groupart method for news \s-1URI\s0 .IP "\(bu" 3 \&\f(CW$url\fR\->article: same as \f(CW$uri\fR\->message .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1URI\s0, URI::WithBase .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1998\-2000 Gisle Aas. PK � �[��2q man3/URI::icaps.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::icaps 3" .TH URI::icaps 3 "2024-09-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" URI::icaps \- URI scheme for ICAPS Identifiers .SH "VERSION" .IX Header "VERSION" Version 5.20 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use URI::icaps; \& \& my $uri = URI\->new(\*(Aqicaps://icap\-proxy.example.com/\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements the \f(CW\*(C`icaps:\*(C'\fR \s-1URI\s0 scheme defined in \s-1RFC 3507\s0 <http://tools.ietf.org/html/rfc3507>, for the Internet Content Adaptation Protocol <https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol>. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" This module inherits the behaviour of URI::icap and overrides the securesecure> method. .SS "secure" .IX Subsection "secure" returns 1 as icaps is a secure protocol .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" See URI::icap .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" See URI::icap .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" None .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" See URI::icap .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1RFC 3507\s0 <http://tools.ietf.org/html/rfc3507> .SH "AUTHOR" .IX Header "AUTHOR" David Dick, \f(CW\*(C`<ddick at cpan.org>\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2016 David Dick. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See <http://dev.perl.org/licenses/> for more information. PK � �[ arch/auto/URI/.existsnu �[��� PK � �[�(�ܻ� �� lib/URI.pmnu ��6�$ package URI; use strict; use warnings; our $VERSION = '5.29'; # 1=version 5.10 and earlier; 0=version 5.11 and later use constant HAS_RESERVED_SQUARE_BRACKETS => $ENV{URI_HAS_RESERVED_SQUARE_BRACKETS} ? 1 : 0; our ($ABS_REMOTE_LEADING_DOTS, $ABS_ALLOW_RELATIVE_SCHEME, $DEFAULT_QUERY_FORM_DELIMITER); my %implements; # mapping from scheme to implementor class # Some "official" character classes our $reserved = HAS_RESERVED_SQUARE_BRACKETS ? q(;/?:@&=+$,[]) : q(;/?:@&=+$,); our $mark = q(-_.!~*'()); #'; emacs our $unreserved = "A-Za-z0-9\Q$mark\E"; our $uric = quotemeta($reserved) . $unreserved . "%"; our $uric4host = $uric . ( HAS_RESERVED_SQUARE_BRACKETS ? '' : quotemeta( q([]) ) ); our $uric4user = quotemeta( q{!$'()*,;:._~%-+=%&} ) . "A-Za-z0-9" . ( HAS_RESERVED_SQUARE_BRACKETS ? quotemeta( q([]) ) : '' ); # RFC-3987: iuserinfo w/o UTF our $scheme_re = '[a-zA-Z][a-zA-Z0-9.+\-]*'; # These schemes don't have an IPv6+ address part. our $schemes_without_host_part_re = 'data|ldapi|urn|sqlite|sqlite3'; # These schemes can have an IPv6+ authority part: # file, ftp, gopher, http, https, ldap, ldaps, mms, news, nntp, nntps, pop, rlogin, rtsp, rtspu, rsync, sip, sips, snews, # telnet, tn3270, ssh, sftp # (all DB URIs, i.e. cassandra, couch, couchdb, etc.), except 'sqlite:', 'sqlite3:'. Others? #MAINT: URI has no test coverage for DB schemes #MAINT: decoupling - perhaps let each class decide itself by defining a member function 'scheme_has_authority_part()'? #MAINT: 'mailto:' needs special treatment for IPv* addresses / RFC 5321 (4.1.3). Until then: restore all '[', ']' # These schemes need fallback to previous (<= 5.10) encoding until a specific handler is available. our $fallback_schemes_re = 'mailto'; use Carp (); use URI::Escape (); use overload ('""' => sub { ${$_[0]} }, '==' => sub { _obj_eq(@_) }, '!=' => sub { !_obj_eq(@_) }, fallback => 1, ); # Check if two objects are the same object sub _obj_eq { return overload::StrVal($_[0]) eq overload::StrVal($_[1]); } sub new { my($class, $uri, $scheme) = @_; $uri = defined ($uri) ? "$uri" : ""; # stringify # Get rid of potential wrapping $uri =~ s/^<(?:URL:)?(.*)>$/$1/; # $uri =~ s/^"(.*)"$/$1/; $uri =~ s/^\s+//; $uri =~ s/\s+$//; my $impclass; if ($uri =~ m/^($scheme_re):/so) { $scheme = $1; } else { if (($impclass = ref($scheme))) { $scheme = $scheme->scheme; } elsif ($scheme && $scheme =~ m/^($scheme_re)(?::|$)/o) { $scheme = $1; } } $impclass ||= implementor($scheme) || do { require URI::_foreign; $impclass = 'URI::_foreign'; }; return $impclass->_init($uri, $scheme); } sub new_abs { my($class, $uri, $base) = @_; $uri = $class->new($uri, $base); $uri->abs($base); } sub _init { my $class = shift; my($str, $scheme) = @_; # find all funny characters and encode the bytes. $str = $class->_uric_escape($str); $str = "$scheme:$str" unless $str =~ /^$scheme_re:/o || $class->_no_scheme_ok; my $self = bless \$str, $class; $self; } #-- Version: 5.11+ # Since the complete URI will be percent-encoded including '[' and ']', # we selectively unescape square brackets from the authority/host part of the URI. # Derived modules that implement _uric_escape() should take this into account # if they do not rely on URI::_uric_escape(). # No unescaping is performed for the userinfo@ part of the authority part. sub _fix_uric_escape_for_host_part { return if HAS_RESERVED_SQUARE_BRACKETS; return if $_[0] !~ /%/; return if $_[0] =~ m{^(?:$URI::schemes_without_host_part_re):}os; # until a scheme specific handler is available, fall back to previous behavior of v5.10 (i.e. 'mailto:') if ($_[0] =~ m{^(?:$URI::fallback_schemes_re):}os) { $_[0] =~ s/\%5B/[/gi; $_[0] =~ s/\%5D/]/gi; return; } if ($_[0] =~ m{^((?:$URI::scheme_re:)?)//([^/?\#]+)(.*)$}os) { my $orig = $2; my ($user, $host) = $orig =~ /^(.*@)?([^@]*)$/; $user ||= ''; my $port = $host =~ s/(:\d+)$// ? $1 : ''; #MAINT: die() here if scheme indicates TCP/UDP and port is out of range [0..65535] ? $host =~ s/\%5B/[/gi; $host =~ s/\%5D/]/gi; $_[0] =~ s/\Q$orig\E/$user$host$port/; } } sub _uric_escape { my($class, $str) = @_; $str =~ s*([^$uric\#])* URI::Escape::escape_char($1) *ego; _fix_uric_escape_for_host_part( $str ); utf8::downgrade($str); return $str; } my %require_attempted; sub implementor { my($scheme, $impclass) = @_; if (!$scheme || $scheme !~ /\A$scheme_re\z/o) { require URI::_generic; return "URI::_generic"; } $scheme = lc($scheme); if ($impclass) { # Set the implementor class for a given scheme my $old = $implements{$scheme}; $impclass->_init_implementor($scheme); $implements{$scheme} = $impclass; return $old; } my $ic = $implements{$scheme}; return $ic if $ic; # scheme not yet known, look for internal or # preloaded (with 'use') implementation $ic = "URI::$scheme"; # default location # turn scheme into a valid perl identifier by a simple transformation... $ic =~ s/\+/_P/g; $ic =~ s/\./_O/g; $ic =~ s/\-/_/g; no strict 'refs'; # check we actually have one for the scheme: unless (@{"${ic}::ISA"}) { if (not exists $require_attempted{$ic}) { $require_attempted{$ic} = 1; # Try to load it my $_old_error = $@; eval "require $ic"; die $@ if $@ && $@ !~ /Can\'t locate.*in \@INC/; $@ = $_old_error; } return undef unless @{"${ic}::ISA"}; } $ic->_init_implementor($scheme); $implements{$scheme} = $ic; $ic; } sub _init_implementor { my($class, $scheme) = @_; # Remember that one implementor class may actually # serve to implement several URI schemes. } sub clone { my $self = shift; my $other = $$self; bless \$other, ref $self; } sub TO_JSON { ${$_[0]} } sub _no_scheme_ok { 0 } sub _scheme { my $self = shift; unless (@_) { return undef unless $$self =~ /^($scheme_re):/o; return $1; } my $old; my $new = shift; if (defined($new) && length($new)) { Carp::croak("Bad scheme '$new'") unless $new =~ /^$scheme_re$/o; $old = $1 if $$self =~ s/^($scheme_re)://o; my $newself = URI->new("$new:$$self"); $$self = $$newself; bless $self, ref($newself); } else { if ($self->_no_scheme_ok) { $old = $1 if $$self =~ s/^($scheme_re)://o; Carp::carp("Oops, opaque part now look like scheme") if $^W && $$self =~ m/^$scheme_re:/o } else { $old = $1 if $$self =~ m/^($scheme_re):/o; } } return $old; } sub scheme { my $scheme = shift->_scheme(@_); return undef unless defined $scheme; lc($scheme); } sub has_recognized_scheme { my $self = shift; return ref($self) !~ /^URI::_(?:foreign|generic)\z/; } sub opaque { my $self = shift; unless (@_) { $$self =~ /^(?:$scheme_re:)?([^\#]*)/o or die; return $1; } $$self =~ /^($scheme_re:)? # optional scheme ([^\#]*) # opaque (\#.*)? # optional fragment $/sx or die; my $old_scheme = $1; my $old_opaque = $2; my $old_frag = $3; my $new_opaque = shift; $new_opaque = "" unless defined $new_opaque; $new_opaque =~ s/([^$uric])/ URI::Escape::escape_char($1)/ego; utf8::downgrade($new_opaque); $$self = defined($old_scheme) ? $old_scheme : ""; $$self .= $new_opaque; $$self .= $old_frag if defined $old_frag; $old_opaque; } sub path { goto &opaque } # alias sub fragment { my $self = shift; unless (@_) { return undef unless $$self =~ /\#(.*)/s; return $1; } my $old; $old = $1 if $$self =~ s/\#(.*)//s; my $new_frag = shift; if (defined $new_frag) { $new_frag =~ s/([^$uric])/ URI::Escape::escape_char($1) /ego; utf8::downgrade($new_frag); $$self .= "#$new_frag"; } $old; } sub as_string { my $self = shift; $$self; } sub as_iri { my $self = shift; my $str = $$self; if ($str =~ s/%([89a-fA-F][0-9a-fA-F])/chr(hex($1))/eg) { # All this crap because the more obvious: # # Encode::decode("UTF-8", $str, sub { sprintf "%%%02X", shift }) # # doesn't work before Encode 2.39. Wait for a standard release # to bundle that version. require Encode; my $enc = Encode::find_encoding("UTF-8"); my $u = ""; while (length $str) { $u .= $enc->decode($str, Encode::FB_QUIET()); if (length $str) { # escape next char $u .= URI::Escape::escape_char(substr($str, 0, 1, "")); } } $str = $u; } return $str; } sub canonical { # Make sure scheme is lowercased, that we don't escape unreserved chars, # and that we use upcase escape sequences. my $self = shift; my $scheme = $self->_scheme || ""; my $uc_scheme = $scheme =~ /[A-Z]/; my $esc = $$self =~ /%[a-fA-F0-9]{2}/; return $self unless $uc_scheme || $esc; my $other = $self->clone; if ($uc_scheme) { $other->_scheme(lc $scheme); } if ($esc) { $$other =~ s{%([0-9a-fA-F]{2})} { my $a = chr(hex($1)); $a =~ /^[$unreserved]\z/o ? $a : "%\U$1" }ge; } return $other; } # Compare two URIs, subclasses will provide a more correct implementation sub eq { my($self, $other) = @_; $self = URI->new($self, $other) unless ref $self; $other = URI->new($other, $self) unless ref $other; ref($self) eq ref($other) && # same class $self->canonical->as_string eq $other->canonical->as_string; } # generic-URI transformation methods sub abs { $_[0]; } sub rel { $_[0]; } sub secure { 0 } # help out Storable sub STORABLE_freeze { my($self, $cloning) = @_; return $$self; } sub STORABLE_thaw { my($self, $cloning, $str) = @_; $$self = $str; } 1; __END__ =head1 NAME URI - Uniform Resource Identifiers (absolute and relative) =head1 SYNOPSIS use URI (); $u1 = URI->new("http://www.example.com"); $u2 = URI->new("foo", "http"); $u3 = $u2->abs($u1); $u4 = $u3->clone; $u5 = URI->new("HTTP://WWW.example.com:80")->canonical; $str = $u->as_string; $str = "$u"; $scheme = $u->scheme; $opaque = $u->opaque; $path = $u->path; $frag = $u->fragment; $u->scheme("ftp"); $u->host("ftp.example.com"); $u->path("cpan/"); =head1 DESCRIPTION This module implements the C<URI> class. Objects of this class represent "Uniform Resource Identifier references" as specified in RFC 2396 (and updated by RFC 2732). A Uniform Resource Identifier is a compact string of characters that identifies an abstract or physical resource. A Uniform Resource Identifier can be further classified as either a Uniform Resource Locator (URL) or a Uniform Resource Name (URN). The distinction between URL and URN does not matter to the C<URI> class interface. A "URI-reference" is a URI that may have additional information attached in the form of a fragment identifier. An absolute URI reference consists of three parts: a I<scheme>, a I<scheme-specific part> and a I<fragment> identifier. A subset of URI references share a common syntax for hierarchical namespaces. For these, the scheme-specific part is further broken down into I<authority>, I<path> and I<query> components. These URIs can also take the form of relative URI references, where the scheme (and usually also the authority) component is missing, but implied by the context of the URI reference. The three forms of URI reference syntax are summarized as follows: <scheme>:<scheme-specific-part>#<fragment> <scheme>://<authority><path>?<query>#<fragment> <path>?<query>#<fragment> The components into which a URI reference can be divided depend on the I<scheme>. The C<URI> class provides methods to get and set the individual components. The methods available for a specific C<URI> object depend on the scheme. =head1 CONSTRUCTORS The following methods construct new C<URI> objects: =over 4 =item $uri = URI->new( $str ) =item $uri = URI->new( $str, $scheme ) Constructs a new URI object. The string representation of a URI is given as argument, together with an optional scheme specification. Common URI wrappers like "" and <>, as well as leading and trailing white space, are automatically removed from the $str argument before it is processed further. The constructor determines the scheme, maps this to an appropriate URI subclass, constructs a new object of that class and returns it. If the scheme isn't one of those that URI recognizes, you still get an URI object back that you can access the generic methods on. The C<< $uri->has_recognized_scheme >> method can be used to test for this. The $scheme argument is only used when $str is a relative URI. It can be either a simple string that denotes the scheme, a string containing an absolute URI reference, or an absolute C<URI> object. If no $scheme is specified for a relative URI $str, then $str is simply treated as a generic URI (no scheme-specific methods available). The set of characters available for building URI references is restricted (see L<URI::Escape>). Characters outside this set are automatically escaped by the URI constructor. =item $uri = URI->new_abs( $str, $base_uri ) Constructs a new absolute URI object. The $str argument can denote a relative or absolute URI. If relative, then it is absolutized using $base_uri as base. The $base_uri must be an absolute URI. =item $uri = URI::file->new( $filename ) =item $uri = URI::file->new( $filename, $os ) Constructs a new I<file> URI from a file name. See L<URI::file>. =item $uri = URI::file->new_abs( $filename ) =item $uri = URI::file->new_abs( $filename, $os ) Constructs a new absolute I<file> URI from a file name. See L<URI::file>. =item $uri = URI::file->cwd Returns the current working directory as a I<file> URI. See L<URI::file>. =item $uri->clone Returns a copy of the $uri. =back =head1 COMMON METHODS The methods described in this section are available for all C<URI> objects. Methods that give access to components of a URI always return the old value of the component. The value returned is C<undef> if the component was not present. There is generally a difference between a component that is empty (represented as C<"">) and a component that is missing (represented as C<undef>). If an accessor method is given an argument, it updates the corresponding component in addition to returning the old value of the component. Passing an undefined argument removes the component (if possible). The description of each accessor method indicates whether the component is passed as an escaped (percent-encoded) or an unescaped string. A component that can be further divided into sub-parts are usually passed escaped, as unescaping might change its semantics. The common methods available for all URI are: =over 4 =item $uri->scheme =item $uri->scheme( $new_scheme ) Sets and returns the scheme part of the $uri. If the $uri is relative, then $uri->scheme returns C<undef>. If called with an argument, it updates the scheme of $uri, possibly changing the class of $uri, and returns the old scheme value. The method croaks if the new scheme name is illegal; a scheme name must begin with a letter and must consist of only US-ASCII letters, numbers, and a few special marks: ".", "+", "-". This restriction effectively means that the scheme must be passed unescaped. Passing an undefined argument to the scheme method makes the URI relative (if possible). Letter case does not matter for scheme names. The string returned by $uri->scheme is always lowercase. If you want the scheme just as it was written in the URI in its original case, you can use the $uri->_scheme method instead. =item $uri->has_recognized_scheme Returns TRUE if the URI scheme is one that URI recognizes. It will also be TRUE for relative URLs where a recognized scheme was provided to the constructor, even if C<< $uri->scheme >> returns C<undef> for these. =item $uri->opaque =item $uri->opaque( $new_opaque ) Sets and returns the scheme-specific part of the $uri (everything between the scheme and the fragment) as an escaped string. =item $uri->path =item $uri->path( $new_path ) Sets and returns the same value as $uri->opaque unless the URI supports the generic syntax for hierarchical namespaces. In that case the generic method is overridden to set and return the part of the URI between the I<host name> and the I<fragment>. =item $uri->fragment =item $uri->fragment( $new_frag ) Returns the fragment identifier of a URI reference as an escaped string. =item $uri->as_string Returns a URI object to a plain ASCII string. URI objects are also converted to plain strings automatically by overloading. This means that $uri objects can be used as plain strings in most Perl constructs. =item $uri->as_iri Returns a Unicode string representing the URI. Escaped UTF-8 sequences representing non-ASCII characters are turned into their corresponding Unicode code point. =item $uri->canonical Returns a normalized version of the URI. The rules for normalization are scheme-dependent. They usually involve lowercasing the scheme and Internet host name components, removing the explicit port specification if it matches the default port, uppercasing all escape sequences, and unescaping octets that can be better represented as plain characters. For efficiency reasons, if the $uri is already in normalized form, then a reference to it is returned instead of a copy. =item $uri->eq( $other_uri ) =item URI::eq( $first_uri, $other_uri ) Tests whether two URI references are equal. URI references that normalize to the same string are considered equal. The method can also be used as a plain function which can also test two string arguments. If you need to test whether two C<URI> object references denote the same object, use the '==' operator. =item $uri->abs( $base_uri ) Returns an absolute URI reference. If $uri is already absolute, then a reference to it is simply returned. If the $uri is relative, then a new absolute URI is constructed by combining the $uri and the $base_uri, and returned. =item $uri->rel( $base_uri ) Returns a relative URI reference if it is possible to make one that denotes the same resource relative to $base_uri. If not, then $uri is simply returned. =item $uri->secure Returns a TRUE value if the URI is considered to point to a resource on a secure channel, such as an SSL or TLS encrypted one. =back =head1 GENERIC METHODS The following methods are available to schemes that use the common/generic syntax for hierarchical namespaces. The descriptions of schemes below indicate which these are. Unrecognized schemes are assumed to support the generic syntax, and therefore the following methods: =over 4 =item $uri->authority =item $uri->authority( $new_authority ) Sets and returns the escaped authority component of the $uri. =item $uri->path =item $uri->path( $new_path ) Sets and returns the escaped path component of the $uri (the part between the host name and the query or fragment). The path can never be undefined, but it can be the empty string. =item $uri->path_query =item $uri->path_query( $new_path_query ) Sets and returns the escaped path and query components as a single entity. The path and the query are separated by a "?" character, but the query can itself contain "?". =item $uri->path_segments =item $uri->path_segments( $segment, ... ) Sets and returns the path. In a scalar context, it returns the same value as $uri->path. In a list context, it returns the unescaped path segments that make up the path. Path segments that have parameters are returned as an anonymous array. The first element is the unescaped path segment proper; subsequent elements are escaped parameter strings. Such an anonymous array uses overloading so it can be treated as a string too, but this string does not include the parameters. Note that absolute paths have the empty string as their first I<path_segment>, i.e. the I<path> C</foo/bar> have 3 I<path_segments>; "", "foo" and "bar". =item $uri->query =item $uri->query( $new_query ) Sets and returns the escaped query component of the $uri. =item $uri->query_form =item $uri->query_form( $key1 => $val1, $key2 => $val2, ... ) =item $uri->query_form( $key1 => $val1, $key2 => $val2, ..., $delim ) =item $uri->query_form( \@key_value_pairs ) =item $uri->query_form( \@key_value_pairs, $delim ) =item $uri->query_form( \%hash ) =item $uri->query_form( \%hash, $delim ) Sets and returns query components that use the I<application/x-www-form-urlencoded> format. Key/value pairs are separated by "&", and the key is separated from the value by a "=" character. The form can be set either by passing separate key/value pairs, or via an array or hash reference. Passing an empty array or an empty hash removes the query component, whereas passing no arguments at all leaves the component unchanged. The order of keys is undefined if a hash reference is passed. The old value is always returned as a list of separate key/value pairs. Assigning this list to a hash is unwise as the keys returned might repeat. The values passed when setting the form can be plain strings or references to arrays of strings. Passing an array of values has the same effect as passing the key repeatedly with one value at a time. All the following statements have the same effect: $uri->query_form(foo => 1, foo => 2); $uri->query_form(foo => [1, 2]); $uri->query_form([ foo => 1, foo => 2 ]); $uri->query_form([ foo => [1, 2] ]); $uri->query_form({ foo => [1, 2] }); The $delim parameter can be passed as ";" to force the key/value pairs to be delimited by ";" instead of "&" in the query string. This practice is often recommended for URLs embedded in HTML or XML documents as this avoids the trouble of escaping the "&" character. You might also set the $URI::DEFAULT_QUERY_FORM_DELIMITER variable to ";" for the same global effect. =item @keys = $u->query_param =item @values = $u->query_param( $key ) =item $first_value = $u->query_param( $key ) =item $u->query_param( $key, $value,... ) If $u->query_param is called with no arguments, it returns all the distinct parameter keys of the URI. In a scalar context it returns the number of distinct keys. When a $key argument is given, the method returns the parameter values with the given key. In a scalar context, only the first parameter value is returned. If additional arguments are given, they are used to update successive parameters with the given key. If any of the values provided are array references, then the array is dereferenced to get the actual values. Please note that you can supply multiple values to this method, but you cannot supply multiple keys. Do this: $uri->query_param( widget_id => 1, 5, 9 ); Do NOT do this: $uri->query_param( widget_id => 1, frobnicator_id => 99 ); =item $u->query_param_append($key, $value,...) Adds new parameters with the given key without touching any old parameters with the same key. It can be explained as a more efficient version of: $u->query_param($key, $u->query_param($key), $value,...); One difference is that this expression would return the old values of $key, whereas the query_param_append() method does not. =item @values = $u->query_param_delete($key) =item $first_value = $u->query_param_delete($key) Deletes all key/value pairs with the given key. The old values are returned. In a scalar context, only the first value is returned. Using the query_param_delete() method is slightly more efficient than the equivalent: $u->query_param($key, []); =item $hashref = $u->query_form_hash =item $u->query_form_hash( \%new_form ) Returns a reference to a hash that represents the query form's key/value pairs. If a key occurs multiple times, then the hash value becomes an array reference. Note that sequence information is lost. This means that: $u->query_form_hash($u->query_form_hash); is not necessarily a no-op, as it may reorder the key/value pairs. The values returned by the query_param() method should stay the same though. =item $uri->query_keywords =item $uri->query_keywords( $keywords, ... ) =item $uri->query_keywords( \@keywords ) Sets and returns query components that use the keywords separated by "+" format. The keywords can be set either by passing separate keywords directly or by passing a reference to an array of keywords. Passing an empty array removes the query component, whereas passing no arguments at all leaves the component unchanged. The old value is always returned as a list of separate words. =back =head1 SERVER METHODS For schemes where the I<authority> component denotes an Internet host, the following methods are available in addition to the generic methods. =over 4 =item $uri->userinfo =item $uri->userinfo( $new_userinfo ) Sets and returns the escaped userinfo part of the authority component. For some schemes this is a user name and a password separated by a colon. This practice is not recommended. Embedding passwords in clear text (such as URI) has proven to be a security risk in almost every case where it has been used. =item $uri->host =item $uri->host( $new_host ) Sets and returns the unescaped hostname. If the C<$new_host> string ends with a colon and a number, then this number also sets the port. For IPv6 addresses the brackets around the raw address is removed in the return value from $uri->host. When setting the host attribute to an IPv6 address you can use a raw address or one enclosed in brackets. The address needs to be enclosed in brackets if you want to pass in a new port value as well. my $uri = URI->new("http://www.\xC3\xBCri-sample/foo/bar.html"); print $u->host; # www.xn--ri-sample-fra0f =item $uri->ihost Returns the host in Unicode form. Any IDNA A-labels (encoded unicode chars with I<xn--> prefix) are turned into U-labels (unicode chars). my $uri = URI->new("http://www.\xC3\xBCri-sample/foo/bar.html"); print $u->ihost; # www.\xC3\xBCri-sample =item $uri->port =item $uri->port( $new_port ) Sets and returns the port. The port is a simple integer that should be greater than 0. If a port is not specified explicitly in the URI, then the URI scheme's default port is returned. If you don't want the default port substituted, then you can use the $uri->_port method instead. =item $uri->host_port =item $uri->host_port( $new_host_port ) Sets and returns the host and port as a single unit. The returned value includes a port, even if it matches the default port. The host part and the port part are separated by a colon: ":". For IPv6 addresses the bracketing is preserved; thus URI->new("http://[::1]/")->host_port returns "[::1]:80". Contrast this with $uri->host which will remove the brackets. =item $uri->default_port Returns the default port of the URI scheme to which $uri belongs. For I<http> this is the number 80, for I<ftp> this is the number 21, etc. The default port for a scheme can not be changed. =back =head1 SCHEME-SPECIFIC SUPPORT Scheme-specific support is provided for the following URI schemes. For C<URI> objects that do not belong to one of these, you can only use the common and generic methods. =over 4 =item B<data>: The I<data> URI scheme is specified in RFC 2397. It allows inclusion of small data items as "immediate" data, as if it had been included externally. C<URI> objects belonging to the data scheme support the common methods and two new methods to access their scheme-specific components: $uri->media_type and $uri->data. See L<URI::data> for details. =item B<file>: An old specification of the I<file> URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but file URI references are in common use. C<URI> objects belonging to the file scheme support the common and generic methods. In addition, they provide two methods for mapping file URIs back to local file names; $uri->file and $uri->dir. See L<URI::file> for details. =item B<ftp>: An old specification of the I<ftp> URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but ftp URI references are in common use. C<URI> objects belonging to the ftp scheme support the common, generic and server methods. In addition, they provide two methods for accessing the userinfo sub-components: $uri->user and $uri->password. =item B<gopher>: The I<gopher> URI scheme is specified in <draft-murali-url-gopher-1996-12-04> and will hopefully be available as a RFC 2396 based specification. C<URI> objects belonging to the gopher scheme support the common, generic and server methods. In addition, they support some methods for accessing gopher-specific path components: $uri->gopher_type, $uri->selector, $uri->search, $uri->string. =item B<http>: The I<http> URI scheme is specified in RFC 2616. The scheme is used to reference resources hosted by HTTP servers. C<URI> objects belonging to the http scheme support the common, generic and server methods. =item B<https>: The I<https> URI scheme is a Netscape invention which is commonly implemented. The scheme is used to reference HTTP servers through SSL connections. Its syntax is the same as http, but the default port is different. =item B<geo>: The I<geo> URI scheme is specified in L<RFC 5870|http://tools.ietf.org/html/rfc5870>. The scheme is used to reference physical location in a two- or three-dimensional coordinate reference system in a compact, simple, human-readable, and protocol-independent way. C<URI> objects belonging to the geo scheme support the common methods. =item B<icap>: The I<icap> URI scheme is specified in L<RFC 3507|http://tools.ietf.org/html/rfc3507>. The scheme is used to reference resources hosted by ICAP servers. C<URI> objects belonging to the icap scheme support the common, generic and server methods. =item B<icaps>: The I<icaps> URI scheme is specified in L<RFC 3507|http://tools.ietf.org/html/rfc3507> as well. The scheme is used to reference ICAP servers through SSL connections. Its syntax is the same as icap, including the same default port. =item B<ldap>: The I<ldap> URI scheme is specified in RFC 2255. LDAP is the Lightweight Directory Access Protocol. An ldap URI describes an LDAP search operation to perform to retrieve information from an LDAP directory. C<URI> objects belonging to the ldap scheme support the common, generic and server methods as well as ldap-specific methods: $uri->dn, $uri->attributes, $uri->scope, $uri->filter, $uri->extensions. See L<URI::ldap> for details. =item B<ldapi>: Like the I<ldap> URI scheme, but uses a UNIX domain socket. The server methods are not supported, and the local socket path is available as $uri->un_path. The I<ldapi> scheme is used by the OpenLDAP package. There is no real specification for it, but it is mentioned in various OpenLDAP manual pages. =item B<ldaps>: Like the I<ldap> URI scheme, but uses an SSL connection. This scheme is deprecated, as the preferred way is to use the I<start_tls> mechanism. =item B<mailto>: The I<mailto> URI scheme is specified in RFC 2368. The scheme was originally used to designate the Internet mailing address of an individual or service. It has (in RFC 2368) been extended to allow setting of other mail header fields and the message body. C<URI> objects belonging to the mailto scheme support the common methods and the generic query methods. In addition, they support the following mailto-specific methods: $uri->to, $uri->headers. Note that the "foo@example.com" part of a mailto is I<not> the C<userinfo> and C<host> but instead the C<path>. This allows a mailto URI to contain multiple comma separated email addresses. =item B<mms>: The I<mms> URL specification can be found at L<http://sdp.ppona.com/>. C<URI> objects belonging to the mms scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components. =item B<news>: The I<news>, I<nntp> and I<snews> URI schemes are specified in <draft-gilman-news-url-01> and will hopefully be available as an RFC 2396 based specification soon. (Update: as of April 2010, they are in L<RFC 5538|https://tools.ietf.org/html/rfc5538>. C<URI> objects belonging to the news scheme support the common, generic and server methods. In addition, they provide some methods to access the path: $uri->group and $uri->message. =item B<nntp>: See I<news> scheme. =item B<nntps>: See I<news> scheme and L<RFC 5538|https://tools.ietf.org/html/rfc5538>. =item B<otpauth>: The I<otpauth> URI scheme is specified in L<https://github.com/google/google-authenticator/wiki/Key-Uri-Format>. The scheme is used to encode secret keys for use in TOTP or HOTP schemes. C<URI> objects belonging to the otpauth scheme support the common methods. =item B<pop>: The I<pop> URI scheme is specified in RFC 2384. The scheme is used to reference a POP3 mailbox. C<URI> objects belonging to the pop scheme support the common, generic and server methods. In addition, they provide two methods to access the userinfo components: $uri->user and $uri->auth =item B<rlogin>: An old specification of the I<rlogin> URI scheme is found in RFC 1738. C<URI> objects belonging to the rlogin scheme support the common, generic and server methods. =item B<rtsp>: The I<rtsp> URL specification can be found in section 3.2 of RFC 2326. C<URI> objects belonging to the rtsp scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components. =item B<rtspu>: The I<rtspu> URI scheme is used to talk to RTSP servers over UDP instead of TCP. The syntax is the same as rtsp. =item B<rsync>: Information about rsync is available from L<http://rsync.samba.org/>. C<URI> objects belonging to the rsync scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password. =item B<sip>: The I<sip> URI specification is described in sections 19.1 and 25 of RFC 3261. C<URI> objects belonging to the sip scheme support the common, generic, and server methods with the exception of path related sub-components. In addition, they provide two methods to get and set I<sip> parameters: $uri->params_form and $uri->params. =item B<sips>: See I<sip> scheme. Its syntax is the same as sip, but the default port is different. =item B<snews>: See I<news> scheme. Its syntax is the same as news, but the default port is different. =item B<telnet>: An old specification of the I<telnet> URI scheme is found in RFC 1738. C<URI> objects belonging to the telnet scheme support the common, generic and server methods. =item B<tn3270>: These URIs are used like I<telnet> URIs but for connections to IBM mainframes. C<URI> objects belonging to the tn3270 scheme support the common, generic and server methods. =item B<ssh>: Information about ssh is available at L<http://www.openssh.com/>. C<URI> objects belonging to the ssh scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password. =item B<sftp>: C<URI> objects belonging to the sftp scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password. =item B<urn>: The syntax of Uniform Resource Names is specified in RFC 2141. C<URI> objects belonging to the urn scheme provide the common methods, and also the methods $uri->nid and $uri->nss, which return the Namespace Identifier and the Namespace-Specific String respectively. The Namespace Identifier basically works like the Scheme identifier of URIs, and further divides the URN namespace. Namespace Identifier assignments are maintained at L<http://www.iana.org/assignments/urn-namespaces>. Letter case is not significant for the Namespace Identifier. It is always returned in lower case by the $uri->nid method. The $uri->_nid method can be used if you want it in its original case. =item B<urn>:B<isbn>: The C<urn:isbn:> namespace contains International Standard Book Numbers (ISBNs) and is described in RFC 3187. A C<URI> object belonging to this namespace has the following extra methods (if the Business::ISBN module is available): $uri->isbn, $uri->isbn_publisher_code, $uri->isbn_group_code (formerly isbn_country_code, which is still supported by issues a deprecation warning), $uri->isbn_as_ean. =item B<urn>:B<oid>: The C<urn:oid:> namespace contains Object Identifiers (OIDs) and is described in RFC 3061. An object identifier consists of sequences of digits separated by dots. A C<URI> object belonging to this namespace has an additional method called $uri->oid that can be used to get/set the oid value. In a list context, oid numbers are returned as separate elements. =back =head1 CONFIGURATION VARIABLES The following configuration variables influence how the class and its methods behave: =over 4 =item $URI::ABS_ALLOW_RELATIVE_SCHEME Some older parsers used to allow the scheme name to be present in the relative URL if it was the same as the base URL scheme. RFC 2396 says that this should be avoided, but you can enable this old behaviour by setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value. The difference is demonstrated by the following examples: URI->new("http:foo")->abs("http://host/a/b") ==> "http:foo" local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1; URI->new("http:foo")->abs("http://host/a/b") ==> "http:/host/a/foo" =item $URI::ABS_REMOTE_LEADING_DOTS You can also have the abs() method ignore excess ".." segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS to a TRUE value. The difference is demonstrated by the following examples: URI->new("../../../foo")->abs("http://host/a/b") ==> "http://host/../../foo" local $URI::ABS_REMOTE_LEADING_DOTS = 1; URI->new("../../../foo")->abs("http://host/a/b") ==> "http://host/foo" =item $URI::DEFAULT_QUERY_FORM_DELIMITER This value can be set to ";" to have the query form C<key=value> pairs delimited by ";" instead of "&" which is the default. =back =head1 ENVIRONMENT VARIABLES =over 4 =item URI_HAS_RESERVED_SQUARE_BRACKETS Before version 5.11, URI treated square brackets as reserved characters throughout the whole URI string. However, these brackets are reserved only within the authority/host part of the URI and nowhere else (RFC 3986). Starting with version 5.11, URI takes this distinction into account. Setting the environment variable C<URI_HAS_RESERVED_SQUARE_BRACKETS> (programmatically or via the shell), restores the old behavior. #-- restore 5.10 behavior programmatically BEGIN { $ENV{URI_HAS_RESERVED_SQUARE_BRACKETS} = 1; } use URI (); I<Note>: This environment variable is just used during initialization and has to be set I<before> module URI is used/required. Changing it at run time has no effect. Its value can be checked programmatically by accessing the constant C<URI::HAS_RESERVED_SQUARE_BRACKETS>. =back =head1 BUGS There are some things that are not quite right: =over =item * Using regexp variables like $1 directly as arguments to the URI accessor methods does not work too well with current perl implementations. I would argue that this is actually a bug in perl. The workaround is to quote them. Example: /(...)/ || die; $u->query("$1"); =item * The escaping (percent encoding) of chars in the 128 .. 255 range passed to the URI constructor or when setting URI parts using the accessor methods depend on the state of the internal UTF8 flag (see utf8::is_utf8) of the string passed. If the UTF8 flag is set the UTF-8 encoded version of the character is percent encoded. If the UTF8 flag isn't set the Latin-1 version (byte) of the character is percent encoded. This basically exposes the internal encoding of Perl strings. =back =head1 PARSING URIs WITH REGEXP As an alternative to this module, the following (official) regular expression can be used to decode a URI: my($scheme, $authority, $path, $query, $fragment) = $uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?|; The C<URI::Split> module provides the function uri_split() as a readable alternative. =head1 SEE ALSO L<URI::file>, L<URI::WithBase>, L<URI::Escape>, L<URI::Split>, L<URI::Heuristic> RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax", Berners-Lee, Fielding, Masinter, August 1998. L<http://www.iana.org/assignments/uri-schemes> L<http://www.iana.org/assignments/urn-namespaces> L<http://www.w3.org/Addressing/> =head1 COPYRIGHT Copyright 1995-2009 Gisle Aas. Copyright 1995 Martijn Koster. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 AUTHORS / ACKNOWLEDGMENTS This module is based on the C<URI::URL> module, which in turn was (distantly) based on the C<wwwurl.pl> code in the libwww-perl for perl4 developed by Roy Fielding, as part of the Arcadia project at the University of California, Irvine, with contributions from Brooks Cutter. C<URI::URL> was developed by Gisle Aas, Tim Bunce, Roy Fielding and Martijn Koster with input from other people on the libwww-perl mailing list. C<URI> and related subclasses was developed by Gisle Aas. =cut PK � �[ lib/auto/URI/.existsnu �[��� PK � �[�L2[ lib/URI/urn.pmnu ��6�$ package URI::urn; # RFC 2141 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI'; use Carp qw(carp); my %implementor; sub _init { my $class = shift; my $self = $class->SUPER::_init(@_); my $nid = $self->nid; my $impclass = $implementor{$nid}; return $impclass->_urn_init($self, $nid) if $impclass; $impclass = "URI::urn"; if ($nid =~ /^[A-Za-z\d][A-Za-z\d\-]*\z/) { my $id = $nid; # make it a legal perl identifier $id =~ s/-/_/g; $id = "_$id" if $id =~ /^\d/; $impclass = "URI::urn::$id"; no strict 'refs'; unless (@{"${impclass}::ISA"}) { # Try to load it my $_old_error = $@; eval "require $impclass"; die $@ if $@ && $@ !~ /Can\'t locate.*in \@INC/; $@ = $_old_error; $impclass = "URI::urn" unless @{"${impclass}::ISA"}; } } else { carp("Illegal namespace identifier '$nid' for URN '$self'") if $^W; } $implementor{$nid} = $impclass; return $impclass->_urn_init($self, $nid); } sub _urn_init { my($class, $self, $nid) = @_; bless $self, $class; } sub _nid { my $self = shift; my $opaque = $self->opaque; if (@_) { my $v = $opaque; my $new = shift; $v =~ s/[^:]*/$new/; $self->opaque($v); # XXX possible rebless } $opaque =~ s/:.*//s; return $opaque; } sub nid { # namespace identifier my $self = shift; my $nid = $self->_nid(@_); $nid = lc($nid) if defined($nid); return $nid; } sub nss { # namespace specific string my $self = shift; my $opaque = $self->opaque; if (@_) { my $v = $opaque; my $new = shift; if (defined $new) { $v =~ s/(:|\z).*/:$new/; } else { $v =~ s/:.*//s; } $self->opaque($v); } return undef unless $opaque =~ s/^[^:]*://; return $opaque; } sub canonical { my $self = shift; my $nid = $self->_nid; my $new = $self->SUPER::canonical; return $new if $nid !~ /[A-Z]/ || $nid =~ /%/; $new = $new->clone if $new == $self; $new->nid(lc($nid)); return $new; } 1; PK � �[ϡc) lib/URI/_userpass.pmnu ��6�$ package URI::_userpass; use strict; use warnings; use URI::Escape qw(uri_unescape); our $VERSION = '5.29'; sub user { my $self = shift; my $info = $self->userinfo; if (@_) { my $new = shift; my $pass = defined($info) ? $info : ""; $pass =~ s/^[^:]*//; if (!defined($new) && !length($pass)) { $self->userinfo(undef); } else { $new = "" unless defined($new); $new =~ s/%/%25/g; $new =~ s/:/%3A/g; $self->userinfo("$new$pass"); } } return undef unless defined $info; $info =~ s/:.*//; uri_unescape($info); } sub password { my $self = shift; my $info = $self->userinfo; if (@_) { my $new = shift; my $user = defined($info) ? $info : ""; $user =~ s/:.*//; if (!defined($new)) { $self->userinfo(length $user ? $user : undef); } else { $new = "" unless defined($new); $new =~ s/%/%25/g; $self->userinfo("$user:$new"); } } return undef unless defined $info; return undef unless $info =~ s/^[^:]*://; uri_unescape($info); } 1; PK � �[m���� � lib/URI/icap.pmnu ��6�$ package URI::icap; use strict; use warnings; use base qw(URI::http); our $VERSION = '5.29'; sub default_port { return 1344 } 1; __END__ =head1 NAME URI::icap - URI scheme for ICAP Identifiers =head1 VERSION Version 5.20 =head1 SYNOPSIS use URI::icap; my $uri = URI->new('icap://icap-proxy.example.com/'); =head1 DESCRIPTION This module implements the C<icap:> URI scheme defined in L<RFC 3507|http://tools.ietf.org/html/rfc3507>, for the L<Internet Content Adaptation Protocol|https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol>. =head1 SUBROUTINES/METHODS This module inherits the behaviour of L<URI::http|URI::http> and overrides the L<default_port|URI#$uri->default_port> method. =head2 default_port The default port for icap servers is 1344 =head1 DIAGNOSTICS See L<URI|URI> =head1 CONFIGURATION AND ENVIRONMENT See L<URI|URI#CONFIGURATION-VARIABLES> and L<URI|URI#ENVIRONMENT-VARIABLES> =head1 DEPENDENCIES None =head1 INCOMPATIBILITIES None reported =head1 BUGS AND LIMITATIONS See L<URI|URI#BUGS> =head1 SEE ALSO L<RFC 3507|http://tools.ietf.org/html/rfc3507> =head1 AUTHOR David Dick, C<< <ddick at cpan.org> >> =head1 LICENSE AND COPYRIGHT Copyright 2016 David Dick. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See L<http://dev.perl.org/licenses/> for more information. PK � �[qPa6� � lib/URI/rsync.pmnu ��6�$ package URI::rsync; # http://rsync.samba.org/ # rsync://[USER@]HOST[:PORT]/SRC use strict; use warnings; our $VERSION = '5.29'; use parent qw(URI::_server URI::_userpass); sub default_port { 873 } 1; PK � �[I� . . lib/URI/_server.pmnu ��6�$ package URI::_server; use strict; use warnings; use parent 'URI::_generic'; use URI::Escape qw(uri_unescape); our $VERSION = '5.29'; sub _uric_escape { my($class, $str) = @_; if ($str =~ m,^((?:$URI::scheme_re:)?)//([^/?\#]*)(.*)$,os) { my($scheme, $host, $rest) = ($1, $2, $3); my $ui = $host =~ s/(.*@)// ? $1 : ""; my $port = $host =~ s/(:\d+)\z// ? $1 : ""; if (_host_escape($host)) { $str = "$scheme//$ui$host$port$rest"; } } return $class->SUPER::_uric_escape($str); } sub _host_escape { return if URI::HAS_RESERVED_SQUARE_BRACKETS and $_[0] !~ /[^$URI::uric]/; return if !URI::HAS_RESERVED_SQUARE_BRACKETS and $_[0] !~ /[^$URI::uric4host]/; eval { require URI::_idna; $_[0] = URI::_idna::encode($_[0]); }; return 0 if $@; return 1; } sub as_iri { my $self = shift; my $str = $self->SUPER::as_iri; if ($str =~ /\bxn--/) { if ($str =~ m,^((?:$URI::scheme_re:)?)//([^/?\#]*)(.*)$,os) { my($scheme, $host, $rest) = ($1, $2, $3); my $ui = $host =~ s/(.*@)// ? $1 : ""; my $port = $host =~ s/(:\d+)\z// ? $1 : ""; require URI::_idna; $host = URI::_idna::decode($host); $str = "$scheme//$ui$host$port$rest"; } } return $str; } sub userinfo { my $self = shift; my $old = $self->authority; if (@_) { my $new = $old; $new = "" unless defined $new; $new =~ s/.*@//; # remove old stuff my $ui = shift; if (defined $ui) { $ui =~ s/([^$URI::uric4user])/ URI::Escape::escape_char($1)/ego; $new = "$ui\@$new"; } $self->authority($new); } return undef if !defined($old) || $old !~ /(.*)@/; return $1; } sub host { my $self = shift; my $old = $self->authority; if (@_) { my $tmp = $old; $tmp = "" unless defined $tmp; my $ui = ($tmp =~ /(.*@)/) ? $1 : ""; my $port = ($tmp =~ /(:\d+)$/) ? $1 : ""; my $new = shift; $new = "" unless defined $new; if (length $new) { $new =~ s/[@]/%40/g; # protect @ if ($new =~ /^[^:]*:\d*\z/ || $new =~ /]:\d*\z/) { $new =~ s/(:\d*)\z// || die "Assert"; $port = $1; } $new = "[$new]" if $new =~ /:/ && $new !~ /^\[/; # IPv6 address _host_escape($new); } $self->authority("$ui$new$port"); } return undef unless defined $old; $old =~ s/.*@//; $old =~ s/:\d+$//; # remove the port $old =~ s{^\[(.*)\]$}{$1}; # remove brackets around IPv6 (RFC 3986 3.2.2) return uri_unescape($old); } sub ihost { my $self = shift; my $old = $self->host(@_); if ($old =~ /(^|\.)xn--/) { require URI::_idna; $old = URI::_idna::decode($old); } return $old; } sub _port { my $self = shift; my $old = $self->authority; if (@_) { my $new = $old; $new =~ s/:\d*$//; my $port = shift; $new .= ":$port" if defined $port; $self->authority($new); } return $1 if defined($old) && $old =~ /:(\d*)$/; return; } sub port { my $self = shift; my $port = $self->_port(@_); $port = $self->default_port if !defined($port) || $port eq ""; $port; } sub host_port { my $self = shift; my $old = $self->authority; $self->host(shift) if @_; return undef unless defined $old; $old =~ s/.*@//; # zap userinfo $old =~ s/:$//; # empty port should be treated the same a no port $old .= ":" . $self->port unless $old =~ /:\d+$/; $old; } sub default_port { undef } sub canonical { my $self = shift; my $other = $self->SUPER::canonical; my $host = $other->host || ""; my $port = $other->_port; my $uc_host = $host =~ /[A-Z]/; my $def_port = defined($port) && ($port eq "" || $port == $self->default_port); if ($uc_host || $def_port) { $other = $other->clone if $other == $self; $other->host(lc $host) if $uc_host; $other->port(undef) if $def_port; } $other; } 1; PK � �[��1�} } lib/URI/mms.pmnu ��6�$ package URI::mms; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::http'; sub default_port { 1755 } 1; PK � �[���l l lib/URI/ldap.pmnu ��6�$ # Copyright (c) 1998 Graham Barr <gbarr@pobox.com>. All rights reserved. # This program is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. package URI::ldap; use strict; use warnings; our $VERSION = '5.29'; use parent qw(URI::_ldap URI::_server); sub default_port { 389 } sub _nonldap_canonical { my $self = shift; $self->URI::_server::canonical(@_); } 1; __END__ =head1 NAME URI::ldap - LDAP Uniform Resource Locators =head1 SYNOPSIS use URI; $uri = URI->new("ldap:$uri_string"); $dn = $uri->dn; $filter = $uri->filter; @attr = $uri->attributes; $scope = $uri->scope; %extn = $uri->extensions; $uri = URI->new("ldap:"); # start empty $uri->host("ldap.itd.umich.edu"); $uri->dn("o=University of Michigan,c=US"); $uri->attributes(qw(postalAddress)); $uri->scope('sub'); $uri->filter('(cn=Babs Jensen)'); print $uri->as_string,"\n"; =head1 DESCRIPTION C<URI::ldap> provides an interface to parse an LDAP URI into its constituent parts and also to build a URI as described in RFC 2255. =head1 METHODS C<URI::ldap> supports all the generic and server methods defined by L<URI>, plus the following. Each of the following methods can be used to set or get the value in the URI. The values are passed in unescaped form. None of these return undefined values, but elements without a default can be empty. If arguments are given, then a new value is set for the given part of the URI. =over 4 =item $uri->dn( [$new_dn] ) Sets or gets the I<Distinguished Name> part of the URI. The DN identifies the base object of the LDAP search. =item $uri->attributes( [@new_attrs] ) Sets or gets the list of attribute names which are returned by the search. =item $uri->scope( [$new_scope] ) Sets or gets the scope to be used by the search. The value can be one of C<"base">, C<"one"> or C<"sub">. If none is given in the URI then the return value defaults to C<"base">. =item $uri->_scope( [$new_scope] ) Same as scope(), but does not default to anything. =item $uri->filter( [$new_filter] ) Sets or gets the filter to be used by the search. If none is given in the URI then the return value defaults to C<"(objectClass=*)">. =item $uri->_filter( [$new_filter] ) Same as filter(), but does not default to anything. =item $uri->extensions( [$etype => $evalue,...] ) Sets or gets the extensions used for the search. The list passed should be in the form etype1 => evalue1, etype2 => evalue2,... This is also the form of list that is returned. =back =head1 SEE ALSO L<http://tools.ietf.org/html/rfc2255> =head1 AUTHOR Graham Barr E<lt>F<gbarr@pobox.com>E<gt> Slightly modified by Gisle Aas to fit into the URI distribution. =head1 COPYRIGHT Copyright (c) 1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[xe� lib/URI/IRI.pmnu ��6�$ package URI::IRI; # Experimental use strict; use warnings; use URI (); use overload '""' => sub { shift->as_string }; our $VERSION = '5.29'; sub new { my($class, $uri, $scheme) = @_; utf8::upgrade($uri); return bless { uri => URI->new($uri, $scheme), }, $class; } sub clone { my $self = shift; return bless { uri => $self->{uri}->clone, }, ref($self); } sub as_string { my $self = shift; return $self->{uri}->as_iri; } our $AUTOLOAD; sub AUTOLOAD { my $method = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2); # We create the function here so that it will not need to be # autoloaded the next time. no strict 'refs'; *$method = sub { shift->{uri}->$method(@_) }; goto &$method; } sub DESTROY {} # avoid AUTOLOADing it 1; PK � �[ut��� � lib/URI/_query.pmnu ��6�$ package URI::_query; use strict; use warnings; use URI (); use URI::Escape qw(uri_unescape); use Scalar::Util (); our $VERSION = '5.29'; sub query { my $self = shift; $$self =~ m,^([^?\#]*)(?:\?([^\#]*))?(.*)$,s or die; if (@_) { my $q = shift; $$self = $1; if (defined $q) { $q =~ s/([^$URI::uric])/ URI::Escape::escape_char($1)/ego; utf8::downgrade($q); $$self .= "?$q"; } $$self .= $3; } $2; } # Handle ...?foo=bar&bar=foo type of query sub query_form { my $self = shift; my $old = $self->query; if (@_) { # Try to set query string my $delim; my $r = $_[0]; if (_is_array($r)) { $delim = $_[1]; @_ = @$r; } elsif (ref($r) eq "HASH") { $delim = $_[1]; @_ = map { $_ => $r->{$_} } sort keys %$r; } $delim = pop if @_ % 2; my @query; while (my($key,$vals) = splice(@_, 0, 2)) { $key = '' unless defined $key; $key =~ s/([;\/?:@&=+,\$\[\]%])/ URI::Escape::escape_char($1)/eg; $key =~ s/ /+/g; $vals = [_is_array($vals) ? @$vals : $vals]; for my $val (@$vals) { if (defined $val) { $val =~ s/([;\/?:@&=+,\$\[\]%])/ URI::Escape::escape_char($1)/eg; $val =~ s/ /+/g; push(@query, "$key=$val"); } else { push(@query, $key); } } } if (@query) { unless ($delim) { $delim = $1 if $old && $old =~ /([&;])/; $delim ||= $URI::DEFAULT_QUERY_FORM_DELIMITER || "&"; } $self->query(join($delim, @query)); } else { $self->query(undef); } } return if !defined($old) || !length($old) || !defined(wantarray); return unless $old =~ /=/; # not a form map { ( defined ) ? do { s/\+/ /g; uri_unescape($_) } : undef } map { /=/ ? split(/=/, $_, 2) : ($_ => undef)} split(/[&;]/, $old); } # Handle ...?dog+bones type of query sub query_keywords { my $self = shift; my $old = $self->query; if (@_) { # Try to set query string my @copy = @_; @copy = @{$copy[0]} if @copy == 1 && _is_array($copy[0]); for (@copy) { s/([;\/?:@&=+,\$\[\]%])/ URI::Escape::escape_char($1)/eg; } $self->query(@copy ? join('+', @copy) : undef); } return if !defined($old) || !defined(wantarray); return if $old =~ /=/; # not keywords, but a form map { uri_unescape($_) } split(/\+/, $old, -1); } # Some URI::URL compatibility stuff sub equery { goto &query } sub query_param { my $self = shift; my @old = $self->query_form; if (@_ == 0) { # get keys my (%seen, $i); return grep !($i++ % 2 || $seen{$_}++), @old; } my $key = shift; my @i = grep $_ % 2 == 0 && $old[$_] eq $key, 0 .. $#old; if (@_) { my @new = @old; my @new_i = @i; my @vals = map { _is_array($_) ? @$_ : $_ } @_; while (@new_i > @vals) { splice @new, pop @new_i, 2; } if (@vals > @new_i) { my $i = @new_i ? $new_i[-1] + 2 : @new; my @splice = splice @vals, @new_i, @vals - @new_i; splice @new, $i, 0, map { $key => $_ } @splice; } if (@vals) { #print "SET $new_i[0]\n"; @new[ map $_ + 1, @new_i ] = @vals; } $self->query_form(\@new); } return wantarray ? @old[map $_+1, @i] : @i ? $old[$i[0]+1] : undef; } sub query_param_append { my $self = shift; my $key = shift; my @vals = map { _is_array($_) ? @$_ : $_ } @_; $self->query_form($self->query_form, $key => \@vals); # XXX return; } sub query_param_delete { my $self = shift; my $key = shift; my @old = $self->query_form; my @vals; for (my $i = @old - 2; $i >= 0; $i -= 2) { next if $old[$i] ne $key; push(@vals, (splice(@old, $i, 2))[1]); } $self->query_form(\@old) if @vals; return wantarray ? reverse @vals : $vals[-1]; } sub query_form_hash { my $self = shift; my @old = $self->query_form; if (@_) { $self->query_form(@_ == 1 ? %{shift(@_)} : @_); } my %hash; while (my($k, $v) = splice(@old, 0, 2)) { if (exists $hash{$k}) { for ($hash{$k}) { $_ = [$_] unless _is_array($_); push(@$_, $v); } } else { $hash{$k} = $v; } } return \%hash; } sub _is_array { return( defined($_[0]) && ( Scalar::Util::reftype($_[0]) || '' ) eq "ARRAY" && !( Scalar::Util::blessed( $_[0] ) && overload::Method( $_[0], '""' ) ) ); } 1; PK � �[)��� � lib/URI/QueryParam.pmnu ��6�$ package URI::QueryParam; use strict; use warnings; our $VERSION = '5.29'; 1; __END__ =head1 NAME URI::QueryParam - Additional query methods for URIs =head1 SYNOPSIS use URI; =head1 DESCRIPTION C<URI::QueryParam> used to provide the L<< query_form_hash|URI/$hashref = $u->query_form_hash >>, L<< query_param|URI/@keys = $u->query_param >> L<< query_param_append|URI/$u->query_param_append($key, $value,...) >>, and L<< query_param_delete|URI/ @values = $u->query_param_delete($key) >> methods on L<URI> objects. These methods have been merged into L<URI> itself, so this module is now a no-op. =head1 COPYRIGHT Copyright 2002 Gisle Aas. =cut PK � �[;�C� � lib/URI/snews.pmnu ��6�$ package URI::snews; # draft-gilman-news-url-01 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::news'; sub default_port { 563 } sub secure { 1 } 1; PK � �[E�:n� � lib/URI/_ldap.pmnu ��6�$ # Copyright (c) 1998 Graham Barr <gbarr@pobox.com>. All rights reserved. # This program is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. package URI::_ldap; use strict; use warnings; our $VERSION = '5.29'; use URI::Escape qw(uri_unescape); sub _ldap_elem { my $self = shift; my $elem = shift; my $query = $self->query; my @bits = (split(/\?/,defined($query) ? $query : ""),("")x4); my $old = $bits[$elem]; if (@_) { my $new = shift; $new =~ s/\?/%3F/g; $bits[$elem] = $new; $query = join("?",@bits); $query =~ s/\?+$//; $query = undef unless length($query); $self->query($query); } $old; } sub dn { my $old = shift->path(@_); $old =~ s:^/::; uri_unescape($old); } sub attributes { my $self = shift; my $old = _ldap_elem($self,0, @_ ? join(",", map { my $tmp = $_; $tmp =~ s/,/%2C/g; $tmp } @_) : ()); return $old unless wantarray; map { uri_unescape($_) } split(/,/,$old); } sub _scope { my $self = shift; my $old = _ldap_elem($self,1, @_); return undef unless defined wantarray && defined $old; uri_unescape($old); } sub scope { my $old = &_scope; $old = "base" unless length $old; $old; } sub _filter { my $self = shift; my $old = _ldap_elem($self,2, @_); return undef unless defined wantarray && defined $old; uri_unescape($old); # || "(objectClass=*)"; } sub filter { my $old = &_filter; $old = "(objectClass=*)" unless length $old; $old; } sub extensions { my $self = shift; my @ext; while (@_) { my $key = shift; my $value = shift; push(@ext, join("=", map { $_="" unless defined; s/,/%2C/g; $_ } $key, $value)); } @ext = join(",", @ext) if @ext; my $old = _ldap_elem($self,3, @ext); return $old unless wantarray; map { uri_unescape($_) } map { /^([^=]+)=(.*)$/ } split(/,/,$old); } sub canonical { my $self = shift; my $other = $self->_nonldap_canonical; # The stuff below is not as efficient as one might hope... $other = $other->clone if $other == $self; $other->dn(_normalize_dn($other->dn)); # Should really know about mixed case "postalAddress", etc... $other->attributes(map lc, $other->attributes); # Lowercase scope, remove default my $old_scope = $other->scope; my $new_scope = lc($old_scope); $new_scope = "" if $new_scope eq "base"; $other->scope($new_scope) if $new_scope ne $old_scope; # Remove filter if default my $old_filter = $other->filter; $other->filter("") if lc($old_filter) eq "(objectclass=*)" || lc($old_filter) eq "objectclass=*"; # Lowercase extensions types and deal with known extension values my @ext = $other->extensions; for (my $i = 0; $i < @ext; $i += 2) { my $etype = $ext[$i] = lc($ext[$i]); if ($etype =~ /^!?bindname$/) { $ext[$i+1] = _normalize_dn($ext[$i+1]); } } $other->extensions(@ext) if @ext; $other; } sub _normalize_dn # RFC 2253 { my $dn = shift; return $dn; # The code below will fail if the "+" or "," is embedding in a quoted # string or simply escaped... my @dn = split(/([+,])/, $dn); for (@dn) { s/^([a-zA-Z]+=)/lc($1)/e; } join("", @dn); } 1; PK � �[��� lib/URI/nntp.pmnu ��6�$ package URI::nntp; # draft-gilman-news-url-01 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::news'; 1; PK � �[>^�#� � lib/URI/telnet.pmnu ��6�$ package URI::telnet; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_login'; sub default_port { 23 } 1; PK � �[�c9{� � lib/URI/news.pmnu ��6�$ package URI::news; # draft-gilman-news-url-01 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_server'; use URI::Escape qw(uri_unescape); use Carp (); sub default_port { 119 } # newsURL = scheme ":" [ news-server ] [ refbygroup | message ] # scheme = "news" | "snews" | "nntp" # news-server = "//" server "/" # refbygroup = group [ "/" messageno [ "-" messageno ] ] # message = local-part "@" domain sub _group { my $self = shift; my $old = $self->path; if (@_) { my($group,$from,$to) = @_; if ($group =~ /\@/) { $group =~ s/^<(.*)>$/$1/; # "<" and ">" should not be part of it } $group =~ s,%,%25,g; $group =~ s,/,%2F,g; my $path = $group; if (defined $from) { $path .= "/$from"; $path .= "-$to" if defined $to; } $self->path($path); } $old =~ s,^/,,; if ($old !~ /\@/ && $old =~ s,/(.*),, && wantarray) { my $extra = $1; return (uri_unescape($old), split(/-/, $extra)); } uri_unescape($old); } sub group { my $self = shift; if (@_) { Carp::croak("Group name can't contain '\@'") if $_[0] =~ /\@/; } my @old = $self->_group(@_); return if $old[0] =~ /\@/; wantarray ? @old : $old[0]; } sub message { my $self = shift; if (@_) { Carp::croak("Message must contain '\@'") unless $_[0] =~ /\@/; } my $old = $self->_group(@_); return undef unless $old =~ /\@/; return $old; } 1; PK � �[3F�/Q Q lib/URI/file/QNX.pmnu ��6�$ package URI::file::QNX; use strict; use warnings; use parent 'URI::file::Unix'; our $VERSION = '5.29'; sub _file_extract_path { my($class, $path) = @_; # tidy path $path =~ s,(.)//+,$1/,g; # ^// is correct $path =~ s,(/\.)+/,/,g; $path = "./$path" if $path =~ m,^[^:/]+:,,; # look like "scheme:" $path; } 1; PK � �[����� � lib/URI/file/Mac.pmnu ��6�$ package URI::file::Mac; use strict; use warnings; use parent 'URI::file::Base'; use URI::Escape qw(uri_unescape); our $VERSION = '5.29'; sub _file_extract_path { my $class = shift; my $path = shift; my @pre; if ($path =~ s/^(:+)//) { if (length($1) == 1) { @pre = (".") unless length($path); } else { @pre = ("..") x (length($1) - 1); } } else { #absolute $pre[0] = ""; } my $isdir = ($path =~ s/:$//); $path =~ s,([%/;]), URI::Escape::escape_char($1),eg; my @path = split(/:/, $path, -1); for (@path) { if ($_ eq "." || $_ eq "..") { $_ = "%2E" x length($_); } $_ = ".." unless length($_); } push (@path,"") if $isdir; (join("/", @pre, @path), 1); } sub file { my $class = shift; my $uri = shift; my @path; my $auth = $uri->authority; if (defined $auth) { if (lc($auth) ne "localhost" && $auth ne "") { my $u_auth = uri_unescape($auth); if (!$class->_file_is_localhost($u_auth)) { # some other host (use it as volume name) @path = ("", $auth); # XXX or just return to make it illegal; } } } my @ps = split("/", $uri->path, -1); shift @ps if @path; push(@path, @ps); my $pre = ""; if (!@path) { return; # empty path; XXX return ":" instead? } elsif ($path[0] eq "") { # absolute shift(@path); if (@path == 1) { return if $path[0] eq ""; # not root directory push(@path, ""); # volume only, effectively append ":" } @ps = @path; @path = (); my $part; for (@ps) { #fix up "." and "..", including interior, in relatives next if $_ eq "."; $part = $_ eq ".." ? "" : $_; push(@path,$part); } if ($ps[-1] eq "..") { #if this happens, we need another : push(@path,""); } } else { $pre = ":"; @ps = @path; @path = (); my $part; for (@ps) { #fix up "." and "..", including interior, in relatives next if $_ eq "."; $part = $_ eq ".." ? "" : $_; push(@path,$part); } if ($ps[-1] eq "..") { #if this happens, we need another : push(@path,""); } } return unless $pre || @path; for (@path) { s/;.*//; # get rid of parameters #return unless length; # XXX $_ = uri_unescape($_); return if /\0/; return if /:/; # Should we? } $pre . join(":", @path); } sub dir { my $class = shift; my $path = $class->file(@_); return unless defined $path; $path .= ":" unless $path =~ /:$/; $path; } 1; PK � �[d�I� � lib/URI/file/Unix.pmnu ��6�$ package URI::file::Unix; use strict; use warnings; use parent 'URI::file::Base'; use URI::Escape qw(uri_unescape); our $VERSION = '5.29'; sub _file_extract_path { my($class, $path) = @_; # tidy path $path =~ s,//+,/,g; $path =~ s,(/\.)+/,/,g; $path = "./$path" if $path =~ m,^[^:/]+:,,; # look like "scheme:" return $path; } sub _file_is_absolute { my($class, $path) = @_; return $path =~ m,^/,; } sub file { my $class = shift; my $uri = shift; my @path; my $auth = $uri->authority; if (defined($auth)) { if (lc($auth) ne "localhost" && $auth ne "") { $auth = uri_unescape($auth); unless ($class->_file_is_localhost($auth)) { push(@path, "", "", $auth); } } } my @ps = $uri->path_segments; shift @ps if @path; push(@path, @ps); for (@path) { # Unix file/directory names are not allowed to contain '\0' or '/' return undef if /\0/; return undef if /\//; # should we really? } return join("/", @path); } 1; PK � �[��,L� � lib/URI/file/Win32.pmnu ��6�$ package URI::file::Win32; use strict; use warnings; use parent 'URI::file::Base'; use URI::Escape qw(uri_unescape); our $VERSION = '5.29'; sub _file_extract_authority { my $class = shift; return $class->SUPER::_file_extract_authority($_[0]) if defined $URI::file::DEFAULT_AUTHORITY; return $1 if $_[0] =~ s,^\\\\([^\\]+),,; # UNC return $1 if $_[0] =~ s,^//([^/]+),,; # UNC too? if ($_[0] =~ s,^([a-zA-Z]:),,) { my $auth = $1; $auth .= "relative" if $_[0] !~ m,^[\\/],; return $auth; } return undef; } sub _file_extract_path { my($class, $path) = @_; $path =~ s,\\,/,g; #$path =~ s,//+,/,g; $path =~ s,(/\.)+/,/,g; if (defined $URI::file::DEFAULT_AUTHORITY) { $path =~ s,^([a-zA-Z]:),/$1,; } return $path; } sub _file_is_absolute { my($class, $path) = @_; return $path =~ m,^[a-zA-Z]:, || $path =~ m,^[/\\],; } sub file { my $class = shift; my $uri = shift; my $auth = $uri->authority; my $rel; # is filename relative to drive specified in authority if (defined $auth) { $auth = uri_unescape($auth); if ($auth =~ /^([a-zA-Z])[:|](relative)?/) { $auth = uc($1) . ":"; $rel++ if $2; } elsif (lc($auth) eq "localhost") { $auth = ""; } elsif (length $auth) { $auth = "\\\\" . $auth; # UNC } } else { $auth = ""; } my @path = $uri->path_segments; for (@path) { return undef if /\0/; return undef if /\//; #return undef if /\\/; # URLs with "\" is not uncommon } return undef unless $class->fix_path(@path); my $path = join("\\", @path); $path =~ s/^\\// if $rel; $path = $auth . $path; $path =~ s,^\\([a-zA-Z])[:|],\u$1:,; return $path; } sub fix_path { 1; } 1; PK � �[c��(1 1 lib/URI/file/OS2.pmnu ��6�$ package URI::file::OS2; use strict; use warnings; use parent 'URI::file::Win32'; our $VERSION = '5.29'; # The Win32 version translates k:/foo to file://k:/foo (?!) # We add an empty host sub _file_extract_authority { my $class = shift; return $1 if $_[0] =~ s,^\\\\([^\\]+),,; # UNC return $1 if $_[0] =~ s,^//([^/]+),,; # UNC too? if ($_[0] =~ m#^[a-zA-Z]{1,2}:#) { # allow for ab: drives return ""; } return; } sub file { my $p = &URI::file::Win32::file; return unless defined $p; $p =~ s,\\,/,g; $p; } 1; PK � �[c��� � lib/URI/file/FAT.pmnu ��6�$ package URI::file::FAT; use strict; use warnings; use parent 'URI::file::Win32'; our $VERSION = '5.29'; sub fix_path { shift; # class for (@_) { # turn it into 8.3 names my @p = map uc, split(/\./, $_, -1); return if @p > 2; # more than 1 dot is not allowed @p = ("") unless @p; # split bug? (returns nothing when splitting "") $_ = substr($p[0], 0, 8); if (@p > 1) { my $ext = substr($p[1], 0, 3); $_ .= ".$ext" if length $ext; } } 1; # ok } 1; PK � �[����� � lib/URI/file/Base.pmnu ��6�$ package URI::file::Base; use strict; use warnings; use URI::Escape (); our $VERSION = '5.29'; sub new { my $class = shift; my $path = shift; $path = "" unless defined $path; my($auth, $escaped_auth, $escaped_path); ($auth, $escaped_auth) = $class->_file_extract_authority($path); ($path, $escaped_path) = $class->_file_extract_path($path); if (defined $auth) { $auth =~ s,%,%25,g unless $escaped_auth; $auth =~ s,([/?\#]), URI::Escape::escape_char($1),eg; $auth = "//$auth"; if (defined $path) { $path = "/$path" unless substr($path, 0, 1) eq "/"; } else { $path = ""; } } else { return undef unless defined $path; $auth = ""; } $path =~ s,([%;?]), URI::Escape::escape_char($1),eg unless $escaped_path; $path =~ s/\#/%23/g; my $uri = $auth . $path; $uri = "file:$uri" if substr($uri, 0, 1) eq "/"; URI->new($uri, "file"); } sub _file_extract_authority { my($class, $path) = @_; return undef unless $class->_file_is_absolute($path); return $URI::file::DEFAULT_AUTHORITY; } sub _file_extract_path { return undef; } sub _file_is_absolute { return 0; } sub _file_is_localhost { shift; # class my $host = lc(shift); return 1 if $host eq "localhost"; eval { require Net::Domain; lc(Net::Domain::hostfqdn() || '') eq $host || lc(Net::Domain::hostname() || '') eq $host; }; } sub file { undef; } sub dir { my $self = shift; $self->file(@_); } 1; PK � �[�qG�� � lib/URI/ldaps.pmnu ��6�$ package URI::ldaps; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::ldap'; sub default_port { 636 } sub secure { 1 } 1; PK � �[�Ftb b lib/URI/sftp.pmnu ��6�$ package URI::sftp; use strict; use warnings; use parent 'URI::ssh'; our $VERSION = '5.29'; 1; PK � �[� � lib/URI/urn/oid.pmnu ��6�$ package URI::urn::oid; # RFC 2061 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::urn'; sub oid { my $self = shift; my $old = $self->nss; if (@_) { $self->nss(join(".", @_)); } return split(/\./, $old) if wantarray; return $old; } 1; PK � �[�B�� � lib/URI/urn/isbn.pmnu ��6�$ package URI::urn::isbn; # RFC 3187 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::urn'; use Carp qw(carp); BEGIN { require Business::ISBN; local $^W = 0; # don't warn about dev versions, perl5.004 style warn "Using Business::ISBN version " . Business::ISBN->VERSION . " which is deprecated.\nUpgrade to Business::ISBN version 3.005\n" if Business::ISBN->VERSION < 3.005; } sub _isbn { my $nss = shift; $nss = $nss->nss if ref($nss); my $isbn = Business::ISBN->new($nss); $isbn = undef if $isbn && !$isbn->is_valid; return $isbn; } sub _nss_isbn { my $self = shift; my $nss = $self->nss(@_); my $isbn = _isbn($nss); $isbn = $isbn->as_string if $isbn; return($nss, $isbn); } sub isbn { my $self = shift; my $isbn; (undef, $isbn) = $self->_nss_isbn(@_); return $isbn; } sub isbn_publisher_code { my $isbn = shift->_isbn || return undef; return $isbn->publisher_code; } BEGIN { my $group_method = do { local $^W = 0; # don't warn about dev versions, perl5.004 style Business::ISBN->VERSION >= 2 ? 'group_code' : 'country_code'; }; sub isbn_group_code { my $isbn = shift->_isbn || return undef; return $isbn->$group_method; } } sub isbn_country_code { my $name = (caller(0))[3]; $name =~ s/.*:://; carp "$name is DEPRECATED. Use isbn_group_code instead"; no strict 'refs'; &isbn_group_code; } BEGIN { my $isbn13_method = do { local $^W = 0; # don't warn about dev versions, perl5.004 style Business::ISBN->VERSION >= 2 ? 'as_isbn13' : 'as_ean'; }; sub isbn13 { my $isbn = shift->_isbn || return undef; # Business::ISBN 1.x didn't put hyphens in the EAN, and it was just a string # Business::ISBN 2.0 doesn't do EAN, but it does ISBN-13 objects # and it uses the hyphens, so call as_string with an empty anon array # or, adjust the test and features to say that it comes out with hyphens. my $thingy = $isbn->$isbn13_method; return eval { $thingy->can( 'as_string' ) } ? $thingy->as_string([]) : $thingy; } } sub isbn_as_ean { my $name = (caller(0))[3]; $name =~ s/.*:://; carp "$name is DEPRECATED. Use isbn13 instead"; no strict 'refs'; &isbn13; } sub canonical { my $self = shift; my($nss, $isbn) = $self->_nss_isbn; my $new = $self->SUPER::canonical; return $new unless $nss && $isbn && $nss ne $isbn; $new = $new->clone if $new == $self; $new->nss($isbn); return $new; } 1; PK � �[�1y y lib/URI/mailto.pmnu ��6�$ package URI::mailto; # RFC 2368 use strict; use warnings; our $VERSION = '5.29'; use parent qw(URI URI::_query); sub to { my $self = shift; my @old = $self->headers; if (@_) { my @new = @old; # get rid of any other to: fields for (my $i = 0; $i < @new; $i += 2) { if (lc($new[$i] || '') eq "to") { splice(@new, $i, 2); redo; } } my $to = shift; $to = "" unless defined $to; unshift(@new, "to" => $to); $self->headers(@new); } return unless defined wantarray; my @to; while (@old) { my $h = shift @old; my $v = shift @old; push(@to, $v) if lc($h) eq "to"; } join(",", @to); } sub headers { my $self = shift; # The trick is to just treat everything as the query string... my $opaque = "to=" . $self->opaque; $opaque =~ s/\?/&/; if (@_) { my @new = @_; # strip out any "to" fields my @to; for (my $i=0; $i < @new; $i += 2) { if (lc($new[$i] || '') eq "to") { push(@to, (splice(@new, $i, 2))[1]); # remove header redo; } } my $new = join(",",@to); $new =~ s/%/%25/g; $new =~ s/\?/%3F/g; $self->opaque($new); $self->query_form(@new) if @new; } return unless defined wantarray; # I am lazy today... URI->new("mailto:?$opaque")->query_form; } # https://datatracker.ietf.org/doc/html/rfc6068#section-5 requires # plus signs (+) not to be turned into spaces sub query_form { my $self = shift; my @fields = $self->SUPER::query_form(@_); for ( my $i = 0 ; $i < @fields ; $i += 2 ) { if ( $fields[0] eq 'to' ) { $fields[1] =~ s/ /+/g; last; } } return @fields; } 1; PK � �[~�� � lib/URI/sip.pmnu ��6�$ # # Written by Ryan Kereliuk <ryker@ryker.org>. This file may be # distributed under the same terms as Perl itself. # # The RFC 3261 sip URI is <scheme>:<authority>;<params>?<query>. # package URI::sip; use strict; use warnings; use parent qw(URI::_server URI::_userpass); use URI::Escape (); our $VERSION = '5.29'; sub default_port { 5060 } sub authority { my $self = shift; $$self =~ m,^($URI::scheme_re:)?([^;?]*)(.*)$,os or die; my $start = $1; my $authoritystr = $2; my $rest = $3; if (@_) { $authoritystr = shift; $authoritystr =~ s/([^$URI::uric])/ URI::Escape::escape_char($1)/ego; $$self = $start . $authoritystr . $rest; } return $authoritystr; } sub params_form { my $self = shift; $$self =~ m,^((?:$URI::scheme_re:)?)(?:([^;?]*))?(;[^?]*)?(.*)$,os or die; my $start = $1 . $2; my $paramstr = $3; my $rest = $4; if (@_) { my @paramarr; for (my $i = 0; $i < @_; $i += 2) { push(@paramarr, "$_[$i]=$_[$i+1]"); } $paramstr = join(";", @paramarr); $$self = $start . ";" . $paramstr . $rest; } $paramstr =~ s/^;//o; return split(/[;=]/, $paramstr); } sub params { my $self = shift; $$self =~ m,^((?:$URI::scheme_re:)?)(?:([^;?]*))?(;[^?]*)?(.*)$,os or die; my $start = $1 . $2; my $paramstr = $3; my $rest = $4; if (@_) { $paramstr = shift; $$self = $start . ";" . $paramstr . $rest; } $paramstr =~ s/^;//o; return $paramstr; } # Inherited methods that make no sense for a SIP URI. sub path {} sub path_query {} sub path_segments {} sub abs { shift } sub rel { shift } sub query_keywords {} 1; PK � �[|�U} } lib/URI/rtsp.pmnu ��6�$ package URI::rtsp; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::http'; sub default_port { 554 } 1; PK � �[" � � lib/URI/_generic.pmnu ��6�$ package URI::_generic; use strict; use warnings; use parent qw(URI URI::_query); use URI::Escape qw(uri_unescape); use Carp (); our $VERSION = '5.29'; my $ACHAR = URI::HAS_RESERVED_SQUARE_BRACKETS ? $URI::uric : $URI::uric4host; $ACHAR =~ s,\\[/?],,g; my $PCHAR = $URI::uric; $PCHAR =~ s,\\[?],,g; sub _no_scheme_ok { 1 } our $IPv6_re; sub _looks_like_raw_ip6_address { my $addr = shift; if ( !$IPv6_re ) { #-- lazy / runs once / use Regexp::IPv6 if installed eval { require Regexp::IPv6; Regexp::IPv6->import( qw($IPv6_re) ); 1; } || do { $IPv6_re = qr/[:0-9a-f]{3,}/; }; #-- fallback: unambitious guess } return 0 unless $addr; return 0 if $addr =~ tr/:/:/ < 2; #-- fallback must not create false positive for IPv4:Port = 0:0 return 1 if $addr =~ /^$IPv6_re$/i; return 0; } sub authority { my $self = shift; $$self =~ m,^((?:$URI::scheme_re:)?)(?://([^/?\#]*))?(.*)$,os or die; if (@_) { my $auth = shift; $$self = $1; my $rest = $3; if (defined $auth) { $auth =~ s/([^$ACHAR])/ URI::Escape::escape_char($1)/ego; if ( my ($user, $host) = $auth =~ /^(.*@)?([^@]+)$/ ) { #-- special escape userinfo part $user ||= ''; $user =~ s/([^$URI::uric4user])/ URI::Escape::escape_char($1)/ego; $user =~ s/%40$/\@/; # recover final '@' $host = "[$host]" if _looks_like_raw_ip6_address( $host ); $auth = $user . $host; } utf8::downgrade($auth); $$self .= "//$auth"; } _check_path($rest, $$self); $$self .= $rest; } $2; } sub path { my $self = shift; $$self =~ m,^((?:[^:/?\#]+:)?(?://[^/?\#]*)?)([^?\#]*)(.*)$,s or die; if (@_) { $$self = $1; my $rest = $3; my $new_path = shift; $new_path = "" unless defined $new_path; $new_path =~ s/([^$PCHAR])/ URI::Escape::escape_char($1)/ego; utf8::downgrade($new_path); _check_path($new_path, $$self); $$self .= $new_path . $rest; } $2; } sub path_query { my $self = shift; $$self =~ m,^((?:[^:/?\#]+:)?(?://[^/?\#]*)?)([^\#]*)(.*)$,s or die; if (@_) { $$self = $1; my $rest = $3; my $new_path = shift; $new_path = "" unless defined $new_path; $new_path =~ s/([^$URI::uric])/ URI::Escape::escape_char($1)/ego; utf8::downgrade($new_path); _check_path($new_path, $$self); $$self .= $new_path . $rest; } $2; } sub _check_path { my($path, $pre) = @_; my $prefix; if ($pre =~ m,/,) { # authority present $prefix = "/" if length($path) && $path !~ m,^[/?\#],; } else { if ($path =~ m,^//,) { Carp::carp("Path starting with double slash is confusing") if $^W; } elsif (!length($pre) && $path =~ m,^[^:/?\#]+:,) { Carp::carp("Path might look like scheme, './' prepended") if $^W; $prefix = "./"; } } substr($_[0], 0, 0) = $prefix if defined $prefix; } sub path_segments { my $self = shift; my $path = $self->path; if (@_) { my @arg = @_; # make a copy for (@arg) { if (ref($_)) { my @seg = @$_; $seg[0] =~ s/%/%25/g; for (@seg) { s/;/%3B/g; } $_ = join(";", @seg); } else { s/%/%25/g; s/;/%3B/g; } s,/,%2F,g; } $self->path(join("/", @arg)); } return $path unless wantarray; map {/;/ ? $self->_split_segment($_) : uri_unescape($_) } split('/', $path, -1); } sub _split_segment { my $self = shift; require URI::_segment; URI::_segment->new(@_); } sub abs { my $self = shift; my $base = shift || Carp::croak("Missing base argument"); if (my $scheme = $self->scheme) { return $self unless $URI::ABS_ALLOW_RELATIVE_SCHEME; $base = URI->new($base) unless ref $base; return $self unless $scheme eq $base->scheme; } $base = URI->new($base) unless ref $base; my $abs = $self->clone; $abs->scheme($base->scheme); return $abs if $$self =~ m,^(?:$URI::scheme_re:)?//,o; $abs->authority($base->authority); my $path = $self->path; return $abs if $path =~ m,^/,; if (!length($path)) { my $abs = $base->clone; my $query = $self->query; $abs->query($query) if defined $query; my $fragment = $self->fragment; $abs->fragment($fragment) if defined $fragment; return $abs; } my $p = $base->path; $p =~ s,[^/]+$,,; $p .= $path; my @p = split('/', $p, -1); shift(@p) if @p && !length($p[0]); my $i = 1; while ($i < @p) { #print "$i ", join("/", @p), " ($p[$i])\n"; if ($p[$i-1] eq ".") { splice(@p, $i-1, 1); $i-- if $i > 1; } elsif ($p[$i] eq ".." && $p[$i-1] ne "..") { splice(@p, $i-1, 2); if ($i > 1) { $i--; push(@p, "") if $i == @p; } } else { $i++; } } $p[-1] = "" if @p && $p[-1] eq "."; # trailing "/." if ($URI::ABS_REMOTE_LEADING_DOTS) { shift @p while @p && $p[0] =~ /^\.\.?$/; } $abs->path("/" . join("/", @p)); $abs; } # The opposite of $url->abs. Return a URI which is as relative as possible sub rel { my $self = shift; my $base = shift || Carp::croak("Missing base argument"); my $rel = $self->clone; $base = URI->new($base) unless ref $base; #my($scheme, $auth, $path) = @{$rel}{qw(scheme authority path)}; my $scheme = $rel->scheme; my $auth = $rel->canonical->authority; my $path = $rel->path; if (!defined($scheme) && !defined($auth)) { # it is already relative return $rel; } #my($bscheme, $bauth, $bpath) = @{$base}{qw(scheme authority path)}; my $bscheme = $base->scheme; my $bauth = $base->canonical->authority; my $bpath = $base->path; for ($bscheme, $bauth, $auth) { $_ = '' unless defined } unless ($scheme eq $bscheme && $auth eq $bauth) { # different location, can't make it relative return $rel; } for ($path, $bpath) { $_ = "/$_" unless m,^/,; } # Make it relative by eliminating scheme and authority $rel->scheme(undef); $rel->authority(undef); # This loop is based on code from Nicolai Langfeldt <janl@ifi.uio.no>. # First we calculate common initial path components length ($li). my $li = 1; while (1) { my $i = index($path, '/', $li); last if $i < 0 || $i != index($bpath, '/', $li) || substr($path,$li,$i-$li) ne substr($bpath,$li,$i-$li); $li=$i+1; } # then we nuke it from both paths substr($path, 0,$li) = ''; substr($bpath,0,$li) = ''; if ($path eq $bpath && defined($rel->fragment) && !defined($rel->query)) { $rel->path(""); } else { # Add one "../" for each path component left in the base path $path = ('../' x $bpath =~ tr|/|/|) . $path; $path = "./" if $path eq ""; $rel->path($path); } $rel; } 1; PK � �[ ���� � lib/URI/pop.pmnu ��6�$ package URI::pop; # RFC 2384 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_server'; use URI::Escape qw(uri_unescape); sub default_port { 110 } #pop://<user>;auth=<auth>@<host>:<port> sub user { my $self = shift; my $old = $self->userinfo; if (@_) { my $new_info = $old; $new_info = "" unless defined $new_info; $new_info =~ s/^[^;]*//; my $new = shift; if (!defined($new) && !length($new_info)) { $self->userinfo(undef); } else { $new = "" unless defined $new; $new =~ s/%/%25/g; $new =~ s/;/%3B/g; $self->userinfo("$new$new_info"); } } return undef unless defined $old; $old =~ s/;.*//; return uri_unescape($old); } sub auth { my $self = shift; my $old = $self->userinfo; if (@_) { my $new = $old; $new = "" unless defined $new; $new =~ s/(^[^;]*)//; my $user = $1; $new =~ s/;auth=[^;]*//i; my $auth = shift; if (defined $auth) { $auth =~ s/%/%25/g; $auth =~ s/;/%3B/g; $new = ";AUTH=$auth$new"; } $self->userinfo("$user$new"); } return undef unless defined $old; $old =~ s/^[^;]*//; return uri_unescape($1) if $old =~ /;auth=(.*)/i; return; } 1; PK � �[� �t� � lib/URI/ldapi.pmnu ��6�$ package URI::ldapi; use strict; use warnings; our $VERSION = '5.29'; use parent qw(URI::_ldap URI::_generic); use URI::Escape (); sub un_path { my $self = shift; my $old = URI::Escape::uri_unescape($self->authority); if (@_) { my $p = shift; $p =~ s/:/%3A/g; $p =~ s/\@/%40/g; $self->authority($p); } return $old; } sub _nonldap_canonical { my $self = shift; $self->URI::_generic::canonical(@_); } 1; PK � �[> > lib/URI/data.pmnu ��6�$ package URI::data; # RFC 2397 use strict; use warnings; use parent 'URI'; our $VERSION = '5.29'; use MIME::Base64 qw(decode_base64 encode_base64); use URI::Escape qw(uri_unescape); sub media_type { my $self = shift; my $opaque = $self->opaque; $opaque =~ /^([^,]*),?/ or die; my $old = $1; my $base64; $base64 = $1 if $old =~ s/(;base64)$//i; if (@_) { my $new = shift; $new = "" unless defined $new; $new =~ s/%/%25/g; $new =~ s/,/%2C/g; $base64 = "" unless defined $base64; $opaque =~ s/^[^,]*,?/$new$base64,/; $self->opaque($opaque); } return uri_unescape($old) if $old; # media_type can't really be "0" "text/plain;charset=US-ASCII"; # default type } sub data { my $self = shift; my($enc, $data) = split(",", $self->opaque, 2); unless (defined $data) { $data = ""; $enc = "" unless defined $enc; } my $base64 = ($enc =~ /;base64$/i); if (@_) { $enc =~ s/;base64$//i if $base64; my $new = shift; $new = "" unless defined $new; my $uric_count = _uric_count($new); my $urienc_len = $uric_count + (length($new) - $uric_count) * 3; my $base64_len = int((length($new)+2) / 3) * 4; $base64_len += 7; # because of ";base64" marker if ($base64_len < $urienc_len || $_[0]) { $enc .= ";base64"; $new = encode_base64($new, ""); } else { $new =~ s/%/%25/g; } $self->opaque("$enc,$new"); } return unless defined wantarray; $data = uri_unescape($data); return $base64 ? decode_base64($data) : $data; } # I could not find a better way to interpolate the tr/// chars from # a variable. my $ENC = $URI::uric; $ENC =~ s/%//; eval <<EOT; die $@ if $@; sub _uric_count { \$_[0] =~ tr/$ENC//; } EOT 1; __END__ =head1 NAME URI::data - URI that contains immediate data =head1 SYNOPSIS use URI; $u = URI->new("data:"); $u->media_type("image/gif"); $u->data(scalar(`cat camel.gif`)); print "$u\n"; open(XV, "|xv -") and print XV $u->data; =head1 DESCRIPTION The C<URI::data> class supports C<URI> objects belonging to the I<data> URI scheme. The I<data> URI scheme is specified in RFC 2397. It allows inclusion of small data items as "immediate" data, as if it had been included externally. Examples: data:,Perl%20is%20good data:image/gif;base64,R0lGODdhIAAgAIAAAAAAAPj8+CwAAAAAI AAgAAAClYyPqcu9AJyCjtIKc5w5xP14xgeO2tlY3nWcajmZZdeJcG Kxrmimms1KMTa1Wg8UROx4MNUq1HrycMjHT9b6xKxaFLM6VRKzI+p KS9XtXpcbdun6uWVxJXA8pNPkdkkxhxc21LZHFOgD2KMoQXa2KMWI JtnE2KizVUkYJVZZ1nczBxXlFopZBtoJ2diXGdNUymmJdFMAADs= C<URI> objects belonging to the data scheme support the common methods (described in L<URI>) and the following two scheme-specific methods: =over 4 =item $uri->media_type( [$new_media_type] ) Can be used to get or set the media type specified in the URI. If no media type is specified, then the default C<"text/plain;charset=US-ASCII"> is returned. =item $uri->data( [$new_data] ) Can be used to get or set the data contained in the URI. The data is passed unescaped (in binary form). The decision about whether to base64 encode the data in the URI is taken automatically, based on the encoding that produces the shorter URI string. =back =head1 SEE ALSO L<URI> =head1 COPYRIGHT Copyright 1995-1998 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[�M��k k lib/URI/_foreign.pmnu ��6�$ package URI::_foreign; use strict; use warnings; use parent 'URI::_generic'; our $VERSION = '5.29'; 1; PK � �[�Q��* * lib/URI/geo.pmnu ��6�$ package URI::geo; use warnings; use strict; use Carp; use URI::Split qw( uri_split uri_join ); use base qw( URI ); our $VERSION = '5.29'; sub _MINIMUM_LATITUDE { return -90 } sub _MAXIMUM_LATITUDE { return 90 } sub _MINIMUM_LONGITUDE { return -180 } sub _MAXIMUM_LONGITUDE { return 180 } sub _MAX_POINTY_PARAMETERS { return 3 } sub _can { my ($can_pt, @keys) = @_; for my $key (@keys) { return $key if $can_pt->can($key); } return; } sub _has { my ($has_pt, @keys) = @_; for my $key (@keys) { return $key if exists $has_pt->{$key}; } return; } # Try hard to extract location information from something. We handle lat, # lon, alt as scalars, arrays containing lat, lon, alt, hashes with # suitably named keys and objects with suitably named methods. sub _location_of_pointy_thing { my ($class, @parameters) = @_; my @lat = qw( lat latitude ); my @lon = qw( lon long longitude lng ); my @ele = qw( ele alt elevation altitude ); if (ref $parameters[0]) { my $pt = shift @parameters; if (@parameters) { croak q[Too many arguments]; } if (eval { $pt->can('can') }) { for my $m (qw( location latlong )) { return $pt->$m() if _can($pt, $m); } my $latk = _can($pt, @lat); my $lonk = _can($pt, @lon); my $elek = _can($pt, @ele); if (defined $latk && defined $lonk) { return $pt->$latk(), $pt->$lonk(), defined $elek ? $pt->$elek() : undef; } } elsif ('ARRAY' eq ref $pt) { return $class->_location_of_pointy_thing(@{$pt}); } elsif ('HASH' eq ref $pt) { my $latk = _has($pt, @lat); my $lonk = _has($pt, @lon); my $elek = _has($pt, @ele); if (defined $latk && defined $lonk) { return $pt->{$latk}, $pt->{$lonk}, defined $elek ? $pt->{$elek} : undef; } } croak q[Don't know how to convert point]; } else { croak q[Need lat, lon or lat, lon, alt] if @parameters < 2 || @parameters > _MAX_POINTY_PARAMETERS(); return my ($lat, $lon, $alt) = @parameters; } } sub _num { my ($class, $n) = @_; if (!defined $n) { return q[]; } (my $rep = sprintf '%f', $n) =~ s/[.]0*$//smx; return $rep; } sub new { my ($self, @parameters) = @_; my $class = ref $self || $self; my $uri = uri_join 'geo', undef, $class->_path(@parameters); return bless \$uri, $class; } sub _init { my ($class, $uri, $scheme) = @_; my $self = $class->SUPER::_init($uri, $scheme); # Normalise at poles. my $lat = $self->latitude; if ($lat == _MAXIMUM_LATITUDE() || $lat == _MINIMUM_LATITUDE()) { $self->longitude(0); } return $self; } sub location { my ($self, @parameters) = @_; if (@parameters) { my ($lat, $lon, $alt) = @parameters; return $self->latitude($lat)->longitude($lon)->altitude($alt); } return $self->latitude, $self->longitude, $self->altitude; } sub latitude { my ($self, @parameters) = @_; return $self->field('latitude', @parameters); } sub longitude { my ($self, @parameters) = @_; return $self->field('longitude', @parameters); } sub altitude { my ($self, @parameters) = @_; return $self->field('altitude', @parameters); } sub crs { my ($self, @parameters) = @_; return $self->field('crs', @parameters); } sub uncertainty { my ($self, @parameters) = @_; return $self->field('uncertainty', @parameters); } sub field { my ($self, $name, @remainder) = @_; my ($scheme, $auth, $v, $query, $frag) = $self->_parse; if (!exists $v->{$name}) { croak "No such field: $name"; } if (!@remainder) { return $v->{$name}; } $v->{$name} = shift @remainder; ${$self} = uri_join $scheme, $auth, $self->_format($v), $query, $frag; return $self; } { my $pnum = qr{\d+(?:[.]\d+)?}smx; my $num = qr{-?$pnum}smx; my $crsp = qr{(?:;crs=(\w+))}smx; my $uncp = qr{(?:;u=($pnum))}smx; my $parm = qr{(?:;\w+=[^;]*)+}smx; sub _parse { my $self = shift; my ($scheme, $auth, $path, $query, $frag) = uri_split ${$self}; $path =~ m{^ ($num), ($num) (?: , ($num) ) ? (?: $crsp ) ? (?: $uncp ) ? ( $parm ) ? $}smx or croak 'Badly formed geo uri'; # No named captures before 5.10.0 return $scheme, $auth, { latitude => $1, longitude => $2, altitude => $3, crs => $4, uncertainty => $5, parameters => (defined $6 ? substr $6, 1 : undef), }, $query, $frag; } } sub _format { my ($class, $v) = @_; return join q[;], ( join q[,], map { $class->_num($_) } @{$v}{'latitude', 'longitude'}, (defined $v->{altitude} ? ($v->{altitude}) : ()) ), (defined $v->{crs} ? ('crs=' . $class->_num($v->{crs})) : ()), ( defined $v->{uncertainty} ? ('u=' . $class->_num($v->{uncertainty})) : ()), (defined $v->{parameters} ? ($v->{parameters}) : ()); } sub _path { my ($class, @parameters) = @_; my ($lat, $lon, $alt) = $class->_location_of_pointy_thing(@parameters); croak 'Latitude out of range' if $lat < _MINIMUM_LATITUDE() || $lat > _MAXIMUM_LATITUDE(); croak 'Longitude out of range' if $lon < _MINIMUM_LONGITUDE() || $lon > _MAXIMUM_LONGITUDE(); if ($lat == _MINIMUM_LATITUDE() || $lat == _MAXIMUM_LATITUDE()) { $lat = 0; } return $class->_format( {latitude => $lat, longitude => $lon, altitude => $alt}); } 1; __END__ =head1 NAME URI::geo - URI scheme for geo Identifiers =head1 SYNOPSIS use URI; # Geo URI from textual uri my $guri = URI->new( 'geo:54.786989,-2.344214' ); # From coordinates my $guri = URI::geo->new( 54.786989, -2.344214 ); # Decode my ( $lat, $lon, $alt ) = $guri->location; my $latitude = $guri->latitude; # Update $guri->location( 55, -1 ); $guri->longitude( -43.23 ); =head1 DESCRIPTION From L<http://geouri.org/>: More and more protocols and data formats are being extended by methods to add geographic information. However, all of those options are tied to that specific protocol or data format. A dedicated Uniform Resource Identifier (URI) scheme for geographic locations would be independent from any protocol, usable by any software/data format that can handle generich URIs. Like a "mailto:" URI launches your favourite mail application today, a "geo:" URI could soon launch your favourite mapping service, or queue that location for a navigation device. =head1 SUBROUTINES/METHODS =head2 C<< new >> Create a new URI::geo. The arguments should be either =over =item * latitude, longitude and optionally altitude =item * a reference to an array containing lat, lon, alt =item * a reference to a hash with suitably named keys or =item * a reference to an object with suitably named accessors =back To maximize the likelihood that you can pass in some object that represents a geographical location and have URI::geo do the right thing we try a number of different accessor names. If the object has a C<latlong> method (e.g. L<Geo::Point>) we'll use that. If there's a C<location> method we call that. Otherwise we look for accessors called C<lat>, C<latitude>, C<lon>, C<long>, C<longitude>, C<ele>, C<alt>, C<elevation> or C<altitude> and use them. Often if you have an object or hash reference that represents a point you can pass it directly to C<new>; so for example this will work: use URI::geo; use Geo::Point; my $pt = Geo::Point->latlong( 48.208333, 16.372778 ); my $guri = URI::geo->new( $pt ); As will this: my $guri = URI::geo->new( { lat => 55, lon => -1 } ); and this: my $guri = URI::geo->new( 55, -1 ); Note that you can also create a new C<URI::geo> by passing a Geo URI to C<URI::new>: use URI; my $guri = URI->new( 'geo:55,-1' ); =head2 C<location> Get or set the location of this geo URI. my ( $lat, $lon, $alt ) = $guri->location; $guri->location( 55.3, -3.7, 120 ); When setting the location it is possible to pass any of the argument types that can be passed to C<new>. =head2 C<latitude> Get or set the latitude of this geo URI. =head2 C<longitude> Get or set the longitude of this geo URI. =head2 C<altitude> Get or set the L<altitude|https://en.wikipedia.org/wiki/Geo_URI_scheme#Altitude> of this geo URI. To delete the altitude set it to C<undef>. =head2 C<crs> Get or set the L<Coordinate Reference System|https://en.wikipedia.org/wiki/Geo_URI_scheme#Coordinate_reference_systems> of this geo URI. To delete the CRS set it to C<undef>. =head2 C<uncertainty> Get or set the L<uncertainty|https://en.wikipedia.org/wiki/Geo_URI_scheme#Uncertainty> of this geo URI. To delete the uncertainty set it to C<undef>. =head2 C<field> =head1 CONFIGURATION AND ENVIRONMENT URI::geo requires no configuration files or environment variables. =head1 DEPENDENCIES L<URI> =head1 DIAGNOSTICS =over =item C<< Too many arguments >> The L<new|/new> method can only accept three parameters; latitude, longitude and altitude. =item C<< Don't know how to convert point >> The L<new|/new> method doesn't know how to convert the supplied parameters into a URI::geo object. =item C<< Need lat, lon or lat, lon, alt >> The L<new|/new> method needs two (latitude and longitude) or three (latitude, longitude and altitude) parameters in a list. Any less or more than this is an error. =item C<< No such field: %s >> This field is not a known field for the L<URI::geo|URI::geo> object. =item C<< Badly formed geo uri >> The L<URI|URI> cannot be parsed as a URI =item C<< Badly formed geo uri >> The L<URI|URI> cannot be parsed as a URI =item C<< Latitude out of range >> Latitude may only be from -90 to +90 =item C<< Longitude out of range >> Longitude may only be from -180 to +180 =back =head1 INCOMPATIBILITIES None reported. =head1 BUGS AND LIMITATIONS To report a bug, or view the current list of bugs, please visit L<https://github.com/libwww-perl/URI/issues> =head1 AUTHOR Andy Armstrong C<< <andy@hexten.net> >> =head1 LICENSE AND COPYRIGHT Copyright (c) 2009, Andy Armstrong C<< <andy@hexten.net> >>. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See L<perlartistic>. PK � �[��"�� � lib/URI/sips.pmnu ��6�$ package URI::sips; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::sip'; sub default_port { 5061 } sub secure { 1 } 1; PK � �[ c� � lib/URI/nntps.pmnu ��6�$ package URI::nntps; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::nntp'; sub default_port { 563 } sub secure { 1 } 1; PK � �[��+4 lib/URI/WithBase.pmnu ��6�$ package URI::WithBase; use strict; use warnings; use URI (); use Scalar::Util qw(blessed); our $VERSION = '5.29'; use overload '""' => "as_string", fallback => 1; sub as_string; # help overload find it sub new { my($class, $uri, $base) = @_; my $ibase = $base; if ($base && blessed($base) && $base->isa(__PACKAGE__)) { $base = $base->abs; $ibase = $base->[0]; } bless [URI->new($uri, $ibase), $base], $class; } sub new_abs { my $class = shift; my $self = $class->new(@_); $self->abs; } sub _init { my $class = shift; my($str, $scheme) = @_; bless [URI->new($str, $scheme), undef], $class; } sub eq { my($self, $other) = @_; $other = $other->[0] if blessed($other) and $other->isa(__PACKAGE__); $self->[0]->eq($other); } our $AUTOLOAD; sub AUTOLOAD { my $self = shift; my $method = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2); return if $method eq "DESTROY"; $self->[0]->$method(@_); } sub can { # override UNIVERSAL::can my $self = shift; $self->SUPER::can(@_) || ( ref($self) ? $self->[0]->can(@_) : undef ) } sub base { my $self = shift; my $base = $self->[1]; if (@_) { # set my $new_base = shift; # ensure absoluteness $new_base = $new_base->abs if ref($new_base) && $new_base->isa(__PACKAGE__); $self->[1] = $new_base; } return unless defined wantarray; # The base attribute supports 'lazy' conversion from URL strings # to URL objects. Strings may be stored but when a string is # fetched it will automatically be converted to a URL object. # The main benefit is to make it much cheaper to say: # URI::WithBase->new($random_url_string, 'http:') if (defined($base) && !ref($base)) { $base = ref($self)->new($base); $self->[1] = $base unless @_; } $base; } sub clone { my $self = shift; my $base = $self->[1]; $base = $base->clone if ref($base); bless [$self->[0]->clone, $base], ref($self); } sub abs { my $self = shift; my $base = shift || $self->base || return $self->clone; $base = $base->as_string if ref($base); bless [$self->[0]->abs($base, @_), $base], ref($self); } sub rel { my $self = shift; my $base = shift || $self->base || return $self->clone; $base = $base->as_string if ref($base); bless [$self->[0]->rel($base, @_), $base], ref($self); } 1; __END__ =head1 NAME URI::WithBase - URIs which remember their base =head1 SYNOPSIS $u1 = URI::WithBase->new($str, $base); $u2 = $u1->abs; $base = $u1->base; $u1->base( $new_base ) =head1 DESCRIPTION This module provides the C<URI::WithBase> class. Objects of this class are like C<URI> objects, but can keep their base too. The base represents the context where this URI was found and can be used to absolutize or relativize the URI. All the methods described in L<URI> are supported for C<URI::WithBase> objects. The methods provided in addition to or modified from those of C<URI> are: =over 4 =item $uri = URI::WithBase->new($str, [$base]) The constructor takes an optional base URI as the second argument. If provided, this argument initializes the base attribute. =item $uri->base( [$new_base] ) Can be used to get or set the value of the base attribute. The return value, which is the old value, is a URI object or C<undef>. =item $uri->abs( [$base_uri] ) The $base_uri argument is now made optional as the object carries its base with it. A new object is returned even if $uri is already absolute (while plain URI objects simply return themselves in that case). =item $uri->rel( [$base_uri] ) The $base_uri argument is now made optional as the object carries its base with it. A new object is always returned. =back =head1 SEE ALSO L<URI> =head1 COPYRIGHT Copyright 1998-2002 Gisle Aas. =cut PK � �[@��~ ~ lib/URI/rtspu.pmnu ��6�$ package URI::rtspu; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::rtsp'; sub default_port { 554 } 1; PK � �[qi|ې � lib/URI/https.pmnu ��6�$ package URI::https; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::http'; sub default_port { 443 } sub secure { 1 } 1; PK � �[��M��% �% lib/URI/file.pmnu ��6�$ package URI::file; use strict; use warnings; use parent 'URI::_generic'; our $VERSION = '5.29'; use URI::Escape qw(uri_unescape); our $DEFAULT_AUTHORITY = ""; # Map from $^O values to implementation classes. The Unix # class is the default. our %OS_CLASS = ( os2 => "OS2", mac => "Mac", MacOS => "Mac", MSWin32 => "Win32", win32 => "Win32", msdos => "FAT", dos => "FAT", qnx => "QNX", ); sub os_class { my($OS) = shift || $^O; my $class = "URI::file::" . ($OS_CLASS{$OS} || "Unix"); no strict 'refs'; unless (%{"$class\::"}) { eval "require $class"; die $@ if $@; } $class; } sub host { uri_unescape(shift->authority(@_)) } sub new { my($class, $path, $os) = @_; os_class($os)->new($path); } sub new_abs { my $class = shift; my $file = $class->new(@_); return $file->abs($class->cwd) unless $$file =~ /^file:/; $file; } sub cwd { my $class = shift; require Cwd; my $cwd = Cwd::cwd(); $cwd = VMS::Filespec::unixpath($cwd) if $^O eq 'VMS'; $cwd = $class->new($cwd); $cwd .= "/" unless substr($cwd, -1, 1) eq "/"; $cwd; } sub canonical { my $self = shift; my $other = $self->SUPER::canonical; my $scheme = $other->scheme; my $auth = $other->authority; return $other if !defined($scheme) && !defined($auth); # relative if (!defined($auth) || $auth eq "" || lc($auth) eq "localhost" || (defined($DEFAULT_AUTHORITY) && lc($auth) eq lc($DEFAULT_AUTHORITY)) ) { # avoid cloning if $auth already match if ((defined($auth) || defined($DEFAULT_AUTHORITY)) && (!defined($auth) || !defined($DEFAULT_AUTHORITY) || $auth ne $DEFAULT_AUTHORITY) ) { $other = $other->clone if $self == $other; $other->authority($DEFAULT_AUTHORITY); } } $other; } sub file { my($self, $os) = @_; os_class($os)->file($self); } sub dir { my($self, $os) = @_; os_class($os)->dir($self); } 1; __END__ =head1 NAME URI::file - URI that maps to local file names =head1 SYNOPSIS use URI::file; $u1 = URI->new("file:/foo/bar"); $u2 = URI->new("foo/bar", "file"); $u3 = URI::file->new($path); $u4 = URI::file->new("c:\\windows\\", "win32"); $u1->file; $u1->file("mac"); =head1 DESCRIPTION The C<URI::file> class supports C<URI> objects belonging to the I<file> URI scheme. This scheme allows us to map the conventional file names found on various computer systems to the URI name space, see L<RFC 8089|https://www.rfc-editor.org/rfc/rfc8089.html>. If you simply want to construct I<file> URI objects from URI strings, use the normal C<URI> constructor. If you want to construct I<file> URI objects from the actual file names used by various systems, then use one of the following C<URI::file> constructors: =over 4 =item $u = URI::file->new( $filename, [$os] ) Maps a file name to the I<file:> URI name space, creates a URI object and returns it. The $filename is interpreted as belonging to the indicated operating system ($os), which defaults to the value of the $^O variable. The $filename can be either absolute or relative, and the corresponding type of URI object for $os is returned. =item $u = URI::file->new_abs( $filename, [$os] ) Same as URI::file->new, but makes sure that the URI returned represents an absolute file name. If the $filename argument is relative, then the name is resolved relative to the current directory, i.e. this constructor is really the same as: URI::file->new($filename)->abs(URI::file->cwd); =item $u = URI::file->cwd Returns a I<file> URI that represents the current working directory. See L<Cwd>. =back The following methods are supported for I<file> URI (in addition to the common and generic methods described in L<URI>): =over 4 =item $u->file( [$os] ) Returns a file name. It maps from the URI name space to the file name space of the indicated operating system. It might return C<undef> if the name can not be represented in the indicated file system. =item $u->dir( [$os] ) Some systems use a different form for names of directories than for plain files. Use this method if you know you want to use the name for a directory. =back The C<URI::file> module can be used to map generic file names to names suitable for the current system. As such, it can work as a nice replacement for the C<File::Spec> module. For instance, the following code translates the UNIX-style file name F<Foo/Bar.pm> to a name suitable for the local system: $file = URI::file->new("Foo/Bar.pm", "unix")->file; die "Can't map filename Foo/Bar.pm for $^O" unless defined $file; open(FILE, $file) || die "Can't open '$file': $!"; # do something with FILE =head1 MAPPING NOTES Most computer systems today have hierarchically organized file systems. Mapping the names used in these systems to the generic URI syntax allows us to work with relative file URIs that behave as they should when resolved using the generic algorithm for URIs (specified in L<RFC 3986|https://www.rfc-editor.org/rfc/rfc3986.html>). Mapping a file name to the generic URI syntax involves mapping the path separator character to "/" and encoding any reserved characters that appear in the path segments of the file name. If path segments consisting of the strings "." or ".." have a different meaning than what is specified for generic URIs, then these must be encoded as well. If the file system has device, volume or drive specifications as the root of the name space, then it makes sense to map them to the authority field of the generic URI syntax. This makes sure that relative URIs can not be resolved "above" them, i.e. generally how relative file names work in those systems. Another common use of the authority field is to encode the host on which this file name is valid. The host name "localhost" is special and generally has the same meaning as a missing or empty authority field. This use is in conflict with using it as a device specification, but can often be resolved for device specifications having characters not legal in plain host names. File name to URI mapping in normally not one-to-one. There are usually many URIs that map to any given file name. For instance, an authority of "localhost" maps the same as a URI with a missing or empty authority. Example 1: The Mac classic (Mac OS 9 and earlier) used ":" as path separator, but not in the same way as a generic URI. ":foo" was a relative name. "foo:bar" was an absolute name. Also, path segments could contain the "/" character as well as the literal "." or "..". So the mapping looks like this: Mac classic URI ---------- ------------------- :foo:bar <==> foo/bar : <==> ./ ::foo:bar <==> ../foo/bar ::: <==> ../../ foo:bar <==> file:/foo/bar foo:bar: <==> file:/foo/bar/ .. <==> %2E%2E <undef> <== / foo/ <== file:/foo%2F ./foo.txt <== file:/.%2Ffoo.txt Note that if you want a relative URL, you *must* begin the path with a :. Any path that begins with [^:] is treated as absolute. Example 2: The UNIX file system is easy to map, as it uses the same path separator as URIs, has a single root, and segments of "." and ".." have the same meaning. URIs that have the character "\0" or "/" as part of any path segment can not be turned into valid UNIX file names. UNIX URI ---------- ------------------ foo/bar <==> foo/bar /foo/bar <==> file:/foo/bar /foo/bar <== file://localhost/foo/bar file: ==> ./file: <undef> <== file:/fo%00/bar / <==> file:/ =cut RFC 1630 [...] There is clearly a danger of confusion that a link made to a local file should be followed by someone on a different system, with unexpected and possibly harmful results. Therefore, the convention is that even a "file" URL is provided with a host part. This allows a client on another system to know that it cannot access the file system, or perhaps to use some other local mechanism to access the file. The special value "localhost" is used in the host field to indicate that the filename should really be used on whatever host one is. This for example allows links to be made to files which are distributed on many machines, or to "your unix local password file" subject of course to consistency across the users of the data. A void host field is equivalent to "localhost". =head1 CONFIGURATION VARIABLES The following configuration variables influence how the class and its methods behave: =over =item %URI::file::OS_CLASS This hash maps OS identifiers to implementation classes. You might want to add or modify this if you want to plug in your own file handler class. Normally the keys should match the $^O values in use. If there is no mapping then the "Unix" implementation is used. =item $URI::file::DEFAULT_AUTHORITY This determines what "authority" string to include in absolute file URIs. It defaults to "". If you prefer verbose URIs you might set it to be "localhost". Setting this value to C<undef> forces behaviour compatible to URI v1.31 and earlier. In this mode host names in UNC paths and drive letters are mapped to the authority component on Windows, while we produce authority-less URIs on Unix. =back =head1 SEE ALSO L<URI>, L<File::Spec>, L<perlport> =head1 COPYRIGHT Copyright 1995-1998,2004 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[9c�� � lib/URI/rlogin.pmnu ��6�$ package URI::rlogin; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_login'; sub default_port { 513 } 1; PK � �[j�Ne� � lib/URI/_login.pmnu ��6�$ package URI::_login; use strict; use warnings; use parent qw(URI::_server URI::_userpass); our $VERSION = '5.29'; # Generic terminal logins. This is used as a base class for 'telnet', # 'tn3270', and 'rlogin' URL schemes. 1; PK � �[�,�Y� � lib/URI/ssh.pmnu ��6�$ package URI::ssh; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_login'; # ssh://[USER@]HOST[:PORT]/SRC sub default_port { 22 } sub secure { 1 } 1; PK � �[���| | lib/URI/gopher.pmnu ��6�$ package URI::gopher; # <draft-murali-url-gopher>, Dec 4, 1996 use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_server'; use URI::Escape qw(uri_unescape); # A Gopher URL follows the common internet scheme syntax as defined in # section 4.3 of [RFC-URL-SYNTAX]: # # gopher://<host>[:<port>]/<gopher-path> # # where # # <gopher-path> := <gopher-type><selector> | # <gopher-type><selector>%09<search> | # <gopher-type><selector>%09<search>%09<gopher+_string> # # <gopher-type> := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' # '8' | '9' | '+' | 'I' | 'g' | 'T' # # <selector> := *pchar Refer to RFC 1808 [4] # <search> := *pchar # <gopher+_string> := *uchar Refer to RFC 1738 [3] # # If the optional port is omitted, the port defaults to 70. sub default_port { 70 } sub _gopher_type { my $self = shift; my $path = $self->path_query; $path =~ s,^/,,; my $gtype = $1 if $path =~ s/^(.)//s; if (@_) { my $new_type = shift; if (defined($new_type)) { Carp::croak("Bad gopher type '$new_type'") unless length($new_type) == 1; substr($path, 0, 0) = $new_type; $self->path_query($path); } else { Carp::croak("Can't delete gopher type when selector is present") if length($path); $self->path_query(undef); } } return $gtype; } sub gopher_type { my $self = shift; my $gtype = $self->_gopher_type(@_); $gtype = "1" unless defined $gtype; $gtype; } sub gtype { goto &gopher_type } # URI::URL compatibility sub selector { shift->_gfield(0, @_) } sub search { shift->_gfield(1, @_) } sub string { shift->_gfield(2, @_) } sub _gfield { my $self = shift; my $fno = shift; my $path = $self->path_query; # not according to spec., but many popular browsers accept # gopher URLs with a '?' before the search string. $path =~ s/\?/\t/; $path = uri_unescape($path); $path =~ s,^/,,; my $gtype = $1 if $path =~ s,^(.),,s; my @path = split(/\t/, $path, 3); if (@_) { # modify my $new = shift; $path[$fno] = $new; pop(@path) while @path && !defined($path[-1]); for (@path) { $_="" unless defined } $path = $gtype; $path = "1" unless defined $path; $path .= join("\t", @path); $self->path_query($path); } $path[$fno]; } 1; PK � �[�1�� � lib/URI/tn3270.pmnu ��6�$ package URI::tn3270; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_login'; sub default_port { 23 } 1; PK � �[ �I� � lib/URI/http.pmnu ��6�$ package URI::http; use strict; use warnings; our $VERSION = '5.29'; use parent 'URI::_server'; sub default_port { 80 } sub canonical { my $self = shift; my $other = $self->SUPER::canonical; my $slash_path = defined($other->authority) && !length($other->path) && !defined($other->query); if ($slash_path) { $other = $other->clone if $other == $self; $other->path("/"); } $other; } 1; PK � �[ �+L lib/URI/_punycode.pmnu ��6�$ package URI::_punycode; use strict; use warnings; our $VERSION = '5.29'; use Exporter 'import'; our @EXPORT = qw(encode_punycode decode_punycode); use integer; our $DEBUG = 0; use constant BASE => 36; use constant TMIN => 1; use constant TMAX => 26; use constant SKEW => 38; use constant DAMP => 700; use constant INITIAL_BIAS => 72; use constant INITIAL_N => 128; my $Delimiter = chr 0x2D; my $BasicRE = qr/[\x00-\x7f]/; sub _croak { require Carp; Carp::croak(@_); } sub _digit_value { my $code = shift; return ord($code) - ord("A") if $code =~ /[A-Z]/; return ord($code) - ord("a") if $code =~ /[a-z]/; return ord($code) - ord("0") + 26 if $code =~ /[0-9]/; return; } sub _code_point { my $digit = shift; return $digit + ord('a') if 0 <= $digit && $digit <= 25; return $digit + ord('0') - 26 if 26 <= $digit && $digit <= 36; die 'NOT COME HERE'; } sub _adapt { my($delta, $numpoints, $firsttime) = @_; $delta = $firsttime ? $delta / DAMP : $delta / 2; $delta += $delta / $numpoints; my $k = 0; while ($delta > ((BASE - TMIN) * TMAX) / 2) { $delta /= BASE - TMIN; $k += BASE; } return $k + (((BASE - TMIN + 1) * $delta) / ($delta + SKEW)); } sub decode_punycode { my $code = shift; my $n = INITIAL_N; my $i = 0; my $bias = INITIAL_BIAS; my @output; if ($code =~ s/(.*)$Delimiter//o) { push @output, map ord, split //, $1; return _croak('non-basic code point') unless $1 =~ /^$BasicRE*$/o; } while ($code) { my $oldi = $i; my $w = 1; LOOP: for (my $k = BASE; 1; $k += BASE) { my $cp = substr($code, 0, 1, ''); my $digit = _digit_value($cp); defined $digit or return _croak("invalid punycode input"); $i += $digit * $w; my $t = ($k <= $bias) ? TMIN : ($k >= $bias + TMAX) ? TMAX : $k - $bias; last LOOP if $digit < $t; $w *= (BASE - $t); } $bias = _adapt($i - $oldi, @output + 1, $oldi == 0); warn "bias becomes $bias" if $DEBUG; $n += $i / (@output + 1); $i = $i % (@output + 1); splice(@output, $i, 0, $n); warn join " ", map sprintf('%04x', $_), @output if $DEBUG; $i++; } return join '', map chr, @output; } sub encode_punycode { my $input = shift; my @input = split //, $input; my $n = INITIAL_N; my $delta = 0; my $bias = INITIAL_BIAS; my @output; my @basic = grep /$BasicRE/, @input; my $h = my $b = @basic; push @output, @basic; push @output, $Delimiter if $b && $h < @input; warn "basic codepoints: (@output)" if $DEBUG; while ($h < @input) { my $m = _min(grep { $_ >= $n } map ord, @input); warn sprintf "next code point to insert is %04x", $m if $DEBUG; $delta += ($m - $n) * ($h + 1); $n = $m; for my $i (@input) { my $c = ord($i); $delta++ if $c < $n; if ($c == $n) { my $q = $delta; LOOP: for (my $k = BASE; 1; $k += BASE) { my $t = ($k <= $bias) ? TMIN : ($k >= $bias + TMAX) ? TMAX : $k - $bias; last LOOP if $q < $t; my $cp = _code_point($t + (($q - $t) % (BASE - $t))); push @output, chr($cp); $q = ($q - $t) / (BASE - $t); } push @output, chr(_code_point($q)); $bias = _adapt($delta, $h + 1, $h == $b); warn "bias becomes $bias" if $DEBUG; $delta = 0; $h++; } } $delta++; $n++; } return join '', @output; } sub _min { my $min = shift; for (@_) { $min = $_ if $_ <= $min } return $min; } 1; __END__ =encoding utf8 =head1 NAME URI::_punycode - encodes Unicode string in Punycode =head1 SYNOPSIS use strict; use warnings; use utf8; use URI::_punycode qw(encode_punycode decode_punycode); # encode a unicode string my $punycode = encode_punycode('http://☃.net'); # http://.net-xc8g $punycode = encode_punycode('bücher'); # bcher-kva $punycode = encode_punycode('他们为什么不说中文'); # ihqwcrb4cv8a8dqg056pqjye # decode a punycode string back into a unicode string my $unicode = decode_punycode('http://.net-xc8g'); # http://☃.net $unicode = decode_punycode('bcher-kva'); # bücher $unicode = decode_punycode('ihqwcrb4cv8a8dqg056pqjye'); # 他们为什么不说中文 =head1 DESCRIPTION L<URI::_punycode> is a module to encode / decode Unicode strings into L<Punycode|https://tools.ietf.org/html/rfc3492>, an efficient encoding of Unicode for use with L<IDNA|https://tools.ietf.org/html/rfc5890>. =head1 FUNCTIONS All functions throw exceptions on failure. You can C<catch> them with L<Syntax::Keyword::Try> or L<Try::Tiny>. The following functions are exported by default. =head2 encode_punycode my $punycode = encode_punycode('http://☃.net'); # http://.net-xc8g $punycode = encode_punycode('bücher'); # bcher-kva $punycode = encode_punycode('他们为什么不说中文') # ihqwcrb4cv8a8dqg056pqjye Takes a Unicode string (UTF8-flagged variable) and returns a Punycode encoding for it. =head2 decode_punycode my $unicode = decode_punycode('http://.net-xc8g'); # http://☃.net $unicode = decode_punycode('bcher-kva'); # bücher $unicode = decode_punycode('ihqwcrb4cv8a8dqg056pqjye'); # 他们为什么不说中文 Takes a Punycode encoding and returns original Unicode string. =head1 AUTHOR Tatsuhiko Miyagawa <F<miyagawa@bulknews.net>> is the author of L<IDNA::Punycode> which was the basis for this module. =head1 SEE ALSO L<IDNA::Punycode>, L<RFC 3492|https://tools.ietf.org/html/rfc3492>, L<RFC 5891|https://tools.ietf.org/html/rfc5891> =head1 COPYRIGHT AND LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[�Dvo o lib/URI/URL.pmnu ��6�$ package URI::URL; use strict; use warnings; use parent 'URI::WithBase'; our $VERSION = '5.29'; # Provide as much as possible of the old URI::URL interface for backwards # compatibility... use Exporter 5.57 'import'; our @EXPORT = qw(url); # Easy to use constructor sub url ($;$) { URI::URL->new(@_); } use URI::Escape qw(uri_unescape); sub new { my $class = shift; my $self = $class->SUPER::new(@_); $self->[0] = $self->[0]->canonical; $self; } sub newlocal { my $class = shift; require URI::file; bless [URI::file->new_abs(shift)], $class; } {package URI::_foreign; sub _init # hope it is not defined { my $class = shift; die "Unknown URI::URL scheme $_[1]:" if $URI::URL::STRICT; $class->SUPER::_init(@_); } } sub strict { my $old = $URI::URL::STRICT; $URI::URL::STRICT = shift if @_; $old; } sub print_on { my $self = shift; require Data::Dumper; print STDERR Data::Dumper::Dumper($self); } sub _try { my $self = shift; my $method = shift; scalar(eval { $self->$method(@_) }); } sub crack { # should be overridden by subclasses my $self = shift; (scalar($self->scheme), $self->_try("user"), $self->_try("password"), $self->_try("host"), $self->_try("port"), $self->_try("path"), $self->_try("params"), $self->_try("query"), scalar($self->fragment), ) } sub full_path { my $self = shift; my $path = $self->path_query; $path = "/" unless length $path; $path; } sub netloc { shift->authority(@_); } sub epath { my $path = shift->SUPER::path(@_); $path =~ s/;.*//; $path; } sub eparams { my $self = shift; my @p = $self->path_segments; return undef unless ref($p[-1]); @p = @{$p[-1]}; shift @p; join(";", @p); } sub params { shift->eparams(@_); } sub path { my $self = shift; my $old = $self->epath(@_); return unless defined wantarray; return '/' if !defined($old) || !length($old); Carp::croak("Path components contain '/' (you must call epath)") if $old =~ /%2[fF]/ and !@_; $old = "/$old" if $old !~ m|^/| && defined $self->netloc; return uri_unescape($old); } sub path_components { shift->path_segments(@_); } sub query { my $self = shift; my $old = $self->equery(@_); if (defined(wantarray) && defined($old)) { if ($old =~ /%(?:26|2[bB]|3[dD])/) { # contains escaped '=' '&' or '+' my $mess; for ($old) { $mess = "Query contains both '+' and '%2B'" if /\+/ && /%2[bB]/; $mess = "Form query contains escaped '=' or '&'" if /=/ && /%(?:3[dD]|26)/; } if ($mess) { Carp::croak("$mess (you must call equery)"); } } # Now it should be safe to unescape the string without losing # information return uri_unescape($old); } undef; } sub abs { my $self = shift; my $base = shift; my $allow_scheme = shift; $allow_scheme = $URI::URL::ABS_ALLOW_RELATIVE_SCHEME unless defined $allow_scheme; local $URI::ABS_ALLOW_RELATIVE_SCHEME = $allow_scheme; local $URI::ABS_REMOTE_LEADING_DOTS = $URI::URL::ABS_REMOTE_LEADING_DOTS; $self->SUPER::abs($base); } sub frag { shift->fragment(@_); } sub keywords { shift->query_keywords(@_); } # file: sub local_path { shift->file; } sub unix_path { shift->file("unix"); } sub dos_path { shift->file("dos"); } sub mac_path { shift->file("mac"); } sub vms_path { shift->file("vms"); } # mailto: sub address { shift->to(@_); } sub encoded822addr { shift->to(@_); } sub URI::mailto::authority { shift->to(@_); } # make 'netloc' method work # news: sub groupart { shift->_group(@_); } sub article { shift->message(@_); } 1; __END__ =head1 NAME URI::URL - Uniform Resource Locators =head1 SYNOPSIS $u1 = URI::URL->new($str, $base); $u2 = $u1->abs; =head1 DESCRIPTION This module is provided for backwards compatibility with modules that depend on the interface provided by the C<URI::URL> class that used to be distributed with the libwww-perl library. The following differences exist compared to the C<URI> class interface: =over 3 =item * The URI::URL module exports the url() function as an alternate constructor interface. =item * The constructor takes an optional $base argument. The C<URI::URL> class is a subclass of C<URI::WithBase>. =item * The URI::URL->newlocal class method is the same as URI::file->new_abs. =item * URI::URL::strict(1) =item * $url->print_on method =item * $url->crack method =item * $url->full_path: same as ($uri->abs_path || "/") =item * $url->netloc: same as $uri->authority =item * $url->epath, $url->equery: same as $uri->path, $uri->query =item * $url->path and $url->query pass unescaped strings. =item * $url->path_components: same as $uri->path_segments (if you don't consider path segment parameters) =item * $url->params and $url->eparams methods =item * $url->base method. See L<URI::WithBase>. =item * $url->abs and $url->rel have an optional $base argument. See L<URI::WithBase>. =item * $url->frag: same as $uri->fragment =item * $url->keywords: same as $uri->query_keywords =item * $url->localpath and friends map to $uri->file. =item * $url->address and $url->encoded822addr: same as $uri->to for mailto URI =item * $url->groupart method for news URI =item * $url->article: same as $uri->message =back =head1 SEE ALSO L<URI>, L<URI::WithBase> =head1 COPYRIGHT Copyright 1998-2000 Gisle Aas. =cut PK � �[d��� lib/URI/ftp.pmnu ��6�$ package URI::ftp; use strict; use warnings; our $VERSION = '5.29'; use parent qw(URI::_server URI::_userpass); sub default_port { 21 } sub path { shift->path_query(@_) } # XXX sub _user { shift->SUPER::user(@_); } sub _password { shift->SUPER::password(@_); } sub user { my $self = shift; my $user = $self->_user(@_); $user = "anonymous" unless defined $user; $user; } sub password { my $self = shift; my $pass = $self->_password(@_); unless (defined $pass) { my $user = $self->user; if ($user eq 'anonymous' || $user eq 'ftp') { # anonymous ftp login password # If there is no ftp anonymous password specified # then we'll just use 'anonymous@' # We don't try to send the read e-mail address because: # - We want to remain anonymous # - We want to stop SPAM # - We don't want to let ftp sites to discriminate by the user, # host, country or ftp client being used. $pass = 'anonymous@'; } } $pass; } 1; PK � �[F�M� � lib/URI/_segment.pmnu ��6�$ package URI::_segment; # Represents a generic path_segment so that it can be treated as # a string too. use strict; use warnings; use URI::Escape qw(uri_unescape); use overload '""' => sub { $_[0]->[0] }, fallback => 1; our $VERSION = '5.29'; sub new { my $class = shift; my @segment = split(';', shift, -1); $segment[0] = uri_unescape($segment[0]); bless \@segment, $class; } 1; PK � �[�.J�=! =! lib/URI/otpauth.pmnu ��6�$ package URI::otpauth; use warnings; use strict; use MIME::Base32(); use URI::Split(); use URI::Escape(); use parent qw( URI URI::_query ); our $VERSION = '5.29'; sub new { my ($class, @parameters) = @_; my %fields = $class->_set(@parameters); my $uri = URI::Split::uri_join( 'otpauth', $fields{type}, $class->_path(%fields), $class->_query(%fields), ); return bless \$uri, $class; } sub _parse { my $self = shift; my ($scheme, $type, $path, $query, $frag) = URI::Split::uri_split(${$self}); $path =~ s/^\///smxg; my @path_parts = split /:/smx, $path; my ($issuer_prefix, $account_name); if (scalar @path_parts == 1) { $account_name = $path_parts[0]; } else { $issuer_prefix = $path_parts[0]; $account_name = $path_parts[1]; } my %fields = (label => $path, type => $type, account_name => $account_name); my $issuer_parameter = $self->query_param('issuer'); if (defined $issuer_parameter) { if ((defined $issuer_prefix) && ($issuer_prefix ne $issuer_parameter)) { Carp::carp( "Issuer prefix from label '$issuer_prefix' does not match issuer parameter '$issuer_parameter'" ); } $fields{issuer} = $issuer_parameter; } elsif (defined $issuer_prefix) { $fields{issuer} = URI::Escape::uri_unescape($issuer_prefix); } if (my $encoded_secret = $self->query_param('secret')) { $fields{secret} = MIME::Base32::decode_base32($encoded_secret); } foreach my $name (qw(algorithm digits counter period)) { if (my $value = $self->query_param($name)) { $fields{$name} = $value; } } %fields = $self->_set(%fields); return ($scheme, $fields{type}, \%fields, $query, $frag); } my $label_escape_regex = qr/[^[:alnum:]@.]/smx; sub _set { my ($self, %fields) = @_; delete $fields{label}; if (defined $fields{account_name}) { if (defined $fields{issuer}) { $fields{label} = $fields{issuer} . q[:] . $fields{account_name}; } else { $fields{label} = $fields{account_name}; } } if (!length $fields{type}) { $fields{type} = 'totp'; } return %fields; } my %field_names = map { $_ => 1 } qw(secret label counter algorithm period digits issuer type account_name); my @query_names = qw(secret issuer algorithm digits counter period); my %defaults = (algorithm => 'SHA1', digits => 6, type => 'totp', period => 30); sub _field { my ($self, $name, @remainder) = @_; my ($scheme, $type, $fields, $query, $frag) = $self->_parse(); if (!@remainder) { if (defined $fields->{$name}) { return $fields->{$name}; } else { return $defaults{$name}; } } $fields->{$name} = shift @remainder; ${$self} = URI::Split::uri_join( $scheme, $fields->{type}, $self->_path(%{$fields}), $self->_query(%{$fields}), $frag ); return $self; } sub _query { my ($class, %fields) = @_; if (defined $fields{secret}) { $fields{secret} = MIME::Base32::encode_base32($fields{secret}); } else { Carp::croak('secret is a mandatory parameter for ' . __PACKAGE__); } return join q[&], map { join q[=], $_ => $fields{$_} } grep { exists $fields{$_} } @query_names; } sub _path { my ($class, %fields) = @_; my $path = $fields{label}; return $path; } sub type { my ($self, @parameters) = @_; return $self->_field('type', @parameters); } sub label { my ($self, @parameters) = @_; return $self->_field('label', @parameters); } sub account_name { my ($self, @parameters) = @_; return $self->_field('account_name', @parameters); } sub issuer { my ($self, @parameters) = @_; return $self->_field('issuer', @parameters); } sub secret { my ($self, @parameters) = @_; return $self->_field('secret', @parameters); } sub algorithm { my ($self, @parameters) = @_; return $self->_field('algorithm', @parameters); } sub counter { my ($self, @parameters) = @_; return $self->_field('counter', @parameters); } sub digits { my ($self, @parameters) = @_; return $self->_field('digits', @parameters); } sub period { my ($self, @parameters) = @_; return $self->_field('period', @parameters); } 1; __END__ =head1 NAME URI::otpauth - URI scheme for secret keys for OTP secrets. Usually found in QR codes =head1 VERSION Version 5.29 =head1 SYNOPSIS use URI; # optauth URI from textual uri my $uri = URI->new( 'otpauth://totp/Example:alice@google.com?secret=NFZS25DINFZV643VOAZXELLTGNRXEM3UH4&issuer=Example' ); # same URI but created from arguments my $uri = URI::otpauth->new( type => 'totp', issuer => 'Example', account_name => 'alice@google.com', secret => 'is-this_sup3r-s3cr3t?' ); =head1 DESCRIPTION This URI scheme is defined in L<https://github.com/google/google-authenticator/wiki/Key-Uri-Format/>: =head1 SUBROUTINES/METHODS =head2 C<< new >> Create a new URI::otpauth. The available arguments are listed below; =over =item * account_name - this can be the account name (probably an email address) used when authenticating with this secret. It is an optional field. =item * algorithm - this is the L<cryptographic hash function|https://en.wikipedia.org/wiki/Cryptographic_hash_function> that should be used. Current values are L<SHA1|https://en.wikipedia.org/wiki/SHA-1>, L<SHA256|https://en.wikipedia.org/wiki/SHA-2> or L<SHA512|https://en.wikipedia.org/wiki/SHA-2>. It is an optional field and will default to SHA1. =item * counter - this is only required when the type is HOTP. =item * digits - this determines the L<length|https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#digits> of the code presented to the user. It is an optional field and will default to 6 digits. =item * issuer - this can be the L<application / system|https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#issuer> that this secret can be used to authenticate to. It is an optional field. =item * label - this is the L<issuer and the account name|https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#label> joined with a ":" character. It is an optional field. =item * period - this is the L<period that the TOTP code is valid for|https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#counter>. It is an optional field and will default to 30 seconds. =item * secret - this is the L<key|https://en.wikipedia.org/wiki/Key_(cryptography)> that the L<TOTP|https://en.wikipedia.org/wiki/Time-based_one-time_password>/L<HOTP|https://en.wikipedia.org/wiki/HMAC-based_one-time_password> algorithm uses to derive the value. It is an arbitrary byte string and must remain private. This field is mandatory. =item * type - this can be 'L<hotp|https://en.wikipedia.org/wiki/HMAC-based_one-time_password>' or 'L<totp|https://en.wikipedia.org/wiki/Time-based_one-time_password>'. This field will default to 'totp'. =back =head2 C<algorithm> Get or set the algorithm of this otpauth URI. =head2 C<account_name> Get or set the account_name of this otpauth URI. =head2 C<counter> Get or set the counter of this otpauth URI. =head2 C<digits> Get or set the digits of this otpauth URI. =head2 C<issuer> Get or set the issuer of this otpauth URI. =head2 C<label> Get or set the label of this otpauth URI. =head2 C<period> Get or set the period of this otpauth URI. =head2 C<secret> Get or set the secret of this otpauth URI. =head2 C<type> Get or set the type of this otpauth URI. my $type = $uri->type('hotp'); =head1 CONFIGURATION AND ENVIRONMENT URI::otpauth requires no configuration files or environment variables. =head1 DEPENDENCIES L<URI> =head1 DIAGNOSTICS =over =item C<< secret is a mandatory parameter for URI::otpauth >> The secret parameter was not detected for the URI::otpauth->new() method. =back =head1 INCOMPATIBILITIES None reported. =head1 BUGS AND LIMITATIONS To report a bug, or view the current list of bugs, please visit L<https://github.com/libwww-perl/URI/issues> =head1 AUTHOR David Dick C<< <ddick@cpan.org> >> =head1 LICENSE AND COPYRIGHT Copyright (c) 2024, David Dick C<< <ddick@cpan.org> >>. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See L<perlartistic>. PK � �[�m2M1 1 lib/URI/Split.pmnu ��6�$ package URI::Split; use strict; use warnings; our $VERSION = '5.29'; use Exporter 5.57 'import'; our @EXPORT_OK = qw(uri_split uri_join); use URI::Escape (); sub uri_split { return $_[0] =~ m,(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?,; } sub uri_join { my($scheme, $auth, $path, $query, $frag) = @_; my $uri = defined($scheme) ? "$scheme:" : ""; $path = "" unless defined $path; if (defined $auth) { $auth =~ s,([/?\#]), URI::Escape::escape_char($1),eg; $uri .= "//$auth"; $path = "/$path" if length($path) && $path !~ m,^/,; } elsif ($path =~ m,^//,) { $uri .= "//"; # XXX force empty auth } unless (length $uri) { $path =~ s,(:), URI::Escape::escape_char($1),e while $path =~ m,^[^:/?\#]+:,; } $path =~ s,([?\#]), URI::Escape::escape_char($1),eg; $uri .= $path; if (defined $query) { $query =~ s,(\#), URI::Escape::escape_char($1),eg; $uri .= "?$query"; } $uri .= "#$frag" if defined $frag; $uri; } 1; __END__ =head1 NAME URI::Split - Parse and compose URI strings =head1 SYNOPSIS use URI::Split qw(uri_split uri_join); ($scheme, $auth, $path, $query, $frag) = uri_split($uri); $uri = uri_join($scheme, $auth, $path, $query, $frag); =head1 DESCRIPTION Provides functions to parse and compose URI strings. The following functions are provided: =over =item ($scheme, $auth, $path, $query, $frag) = uri_split($uri) Breaks up a URI string into its component parts. An C<undef> value is returned for those parts that are not present. The $path part is always present (but can be the empty string) and is thus never returned as C<undef>. No sensible value is returned if this function is called in a scalar context. =item $uri = uri_join($scheme, $auth, $path, $query, $frag) Puts together a URI string from its parts. Missing parts are signaled by passing C<undef> for the corresponding argument. Minimal escaping is applied to parts that contain reserved chars that would confuse a parser. For instance, any occurrence of '?' or '#' in $path is always escaped, as it would otherwise be parsed back as a query or fragment. =back =head1 SEE ALSO L<URI>, L<URI::Escape> =head1 COPYRIGHT Copyright 2003, Gisle Aas This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[��ʰ� � lib/URI/Escape.pmnu ��6�$ package URI::Escape; use strict; use warnings; =head1 NAME URI::Escape - Percent-encode and percent-decode unsafe characters =head1 SYNOPSIS use URI::Escape; $safe = uri_escape("10% is enough\n"); $verysafe = uri_escape("foo", "\0-\377"); $str = uri_unescape($safe); =head1 DESCRIPTION This module provides functions to percent-encode and percent-decode URI strings as defined by RFC 3986. Percent-encoding URI's is informally called "URI escaping". This is the terminology used by this module, which predates the formalization of the terms by the RFC by several years. A URI consists of a restricted set of characters. The restricted set of characters consists of digits, letters, and a few graphic symbols chosen from those common to most of the character encodings and input facilities available to Internet users. They are made up of the "unreserved" and "reserved" character sets as defined in RFC 3986. unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" reserved = ":" / "/" / "?" / "#" / "[" / "]" / "@" "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" In addition, any byte (octet) can be represented in a URI by an escape sequence: a triplet consisting of the character "%" followed by two hexadecimal digits. A byte can also be represented directly by a character, using the US-ASCII character for that octet. Some of the characters are I<reserved> for use as delimiters or as part of certain URI components. These must be escaped if they are to be treated as ordinary data. Read RFC 3986 for further details. The functions provided (and exported by default) from this module are: =over 4 =item uri_escape( $string ) =item uri_escape( $string, $unsafe ) Replaces each unsafe character in the $string with the corresponding escape sequence and returns the result. The $string argument should be a string of bytes. The uri_escape() function will croak if given a characters with code above 255. Use uri_escape_utf8() if you know you have such chars or/and want chars in the 128 .. 255 range treated as UTF-8. The uri_escape() function takes an optional second argument that overrides the set of characters that are to be escaped. The set is specified as a string that can be used in a regular expression character class (between [ ]). E.g.: "\x00-\x1f\x7f-\xff" # all control and hi-bit characters "a-z" # all lower case characters "^A-Za-z" # everything not a letter The default set of characters to be escaped is all those which are I<not> part of the C<unreserved> character class shown above as well as the reserved characters. I.e. the default is: "^A-Za-z0-9\-\._~" The second argument can also be specified as a regular expression object: qr/[^A-Za-z]/ Any strings matched by this regular expression will have all of their characters escaped. =item uri_escape_utf8( $string ) =item uri_escape_utf8( $string, $unsafe ) Works like uri_escape(), but will encode chars as UTF-8 before escaping them. This makes this function able to deal with characters with code above 255 in $string. Note that chars in the 128 .. 255 range will be escaped differently by this function compared to what uri_escape() would. For chars in the 0 .. 127 range there is no difference. Equivalent to: utf8::encode($string); my $uri = uri_escape($string); Note: JavaScript has a function called escape() that produces the sequence "%uXXXX" for chars in the 256 .. 65535 range. This function has really nothing to do with URI escaping but some folks got confused since it "does the right thing" in the 0 .. 255 range. Because of this you sometimes see "URIs" with these kind of escapes. The JavaScript encodeURIComponent() function is similar to uri_escape_utf8(). =item uri_unescape($string,...) Returns a string with each %XX sequence replaced with the actual byte (octet). This does the same as: $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; but does not modify the string in-place as this RE would. Using the uri_unescape() function instead of the RE might make the code look cleaner and is a few characters less to type. In a simple benchmark test I did, calling the function (instead of the inline RE above) if a few chars were unescaped was something like 40% slower, and something like 700% slower if none were. If you are going to unescape a lot of times it might be a good idea to inline the RE. If the uri_unescape() function is passed multiple strings, then each one is returned unescaped. =back The module can also export the C<%escapes> hash, which contains the mapping from all 256 bytes to the corresponding escape codes. Lookup in this hash is faster than evaluating C<sprintf("%%%02X", ord($byte))> each time. =head1 SEE ALSO L<URI> =head1 COPYRIGHT Copyright 1995-2004 Gisle Aas. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut use Exporter 5.57 'import'; our %escapes; our @EXPORT = qw(uri_escape uri_unescape uri_escape_utf8); our @EXPORT_OK = qw(%escapes); our $VERSION = '5.29'; use Carp (); # Build a char->hex map for (0..255) { $escapes{chr($_)} = sprintf("%%%02X", $_); } my %subst; # compiled patterns my %Unsafe = ( RFC2732 => qr/[^A-Za-z0-9\-_.!~*'()]/, RFC3986 => qr/[^A-Za-z0-9\-\._~]/, ); sub uri_escape { my($text, $patn) = @_; return undef unless defined $text; my $re; if (defined $patn){ if (ref $patn eq 'Regexp') { $text =~ s{($patn)}{ join('', map +($escapes{$_} || _fail_hi($_)), split //, "$1") }ge; return $text; } $re = $subst{$patn}; if (!defined $re) { $re = $patn; # we need to escape the [] characters, except for those used in # posix classes. if they are prefixed by a backslash, allow them # through unmodified. $re =~ s{(\[:\w+:\])|(\\)?([\[\]]|\\\z)}{ defined $1 ? $1 : defined $2 ? "$2$3" : "\\$3" }ge; eval { # disable the warnings here, since they will trigger later # when used, and we only want them to appear once per call, # but every time the same pattern is used. no warnings 'regexp'; $re = $subst{$patn} = qr{[$re]}; 1; } or Carp::croak("uri_escape: $@"); } } else { $re = $Unsafe{RFC3986}; } $text =~ s/($re)/$escapes{$1} || _fail_hi($1)/ge; $text; } sub _fail_hi { my $chr = shift; Carp::croak(sprintf "Can't escape \\x{%04X}, try uri_escape_utf8() instead", ord($chr)); } sub uri_escape_utf8 { my $text = shift; return undef unless defined $text; utf8::encode($text); return uri_escape($text, @_); } sub uri_unescape { # Note from RFC1630: "Sequences which start with a percent sign # but are not followed by two hexadecimal characters are reserved # for future extension" my $str = shift; if (@_ && wantarray) { # not executed for the common case of a single argument my @str = ($str, @_); # need to copy for (@str) { s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; } return @str; } $str =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg if defined $str; $str; } # XXX FIXME escape_char is buggy as it assigns meaning to the string's storage format. sub escape_char { # Old versions of utf8::is_utf8() didn't properly handle magical vars (e.g. $1). # The following forces a fetch to occur beforehand. my $dummy = substr($_[0], 0, 0); if (utf8::is_utf8($_[0])) { my $s = shift; utf8::encode($s); unshift(@_, $s); } return join '', @URI::Escape::escapes{split //, $_[0]}; } 1; PK � �[�Ѳ� lib/URI/Heuristic.pmnu ��6�$ package URI::Heuristic; =head1 NAME URI::Heuristic - Expand URI using heuristics =head1 SYNOPSIS use URI::Heuristic qw(uf_uristr); $u = uf_uristr("example"); # http://www.example.com $u = uf_uristr("www.sol.no/sol"); # http://www.sol.no/sol $u = uf_uristr("aas"); # http://www.aas.no $u = uf_uristr("ftp.funet.fi"); # ftp://ftp.funet.fi $u = uf_uristr("/etc/passwd"); # file:/etc/passwd =head1 DESCRIPTION This module provides functions that expand strings into real absolute URIs using some built-in heuristics. Strings that already represent absolute URIs (i.e. that start with a C<scheme:> part) are never modified and are returned unchanged. The main use of these functions is to allow abbreviated URIs similar to what many web browsers allow for URIs typed in by the user. The following functions are provided: =over 4 =item uf_uristr($str) Tries to make the argument string into a proper absolute URI string. The "uf_" prefix stands for "User Friendly". Under MacOS, it assumes that any string with a common URL scheme (http, ftp, etc.) is a URL rather than a local path. So don't name your volumes after common URL schemes and expect uf_uristr() to construct valid file: URL's on those volumes for you, because it won't. =item uf_uri($str) Works the same way as uf_uristr() but returns a C<URI> object. =back =head1 ENVIRONMENT If the hostname portion of a URI does not contain any dots, then certain qualified guesses are made. These guesses are governed by the following environment variables: =over 10 =item COUNTRY The two-letter country code (ISO 3166) for your location. If the domain name of your host ends with two letters, then it is taken to be the default country. See also L<Locale::Country>. =item HTTP_ACCEPT_LANGUAGE, LC_ALL, LANG If COUNTRY is not set, these standard environment variables are examined and country (not language) information possibly found in them is used as the default country. =item URL_GUESS_PATTERN Contains a space-separated list of URL patterns to try. The string "ACME" is for some reason used as a placeholder for the host name in the URL provided. Example: URL_GUESS_PATTERN="www.ACME.no www.ACME.se www.ACME.com" export URL_GUESS_PATTERN Specifying URL_GUESS_PATTERN disables any guessing rules based on country. An empty URL_GUESS_PATTERN disables any guessing that involves host name lookups. =back =head1 COPYRIGHT Copyright 1997-1998, Gisle Aas This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut use strict; use warnings; use Exporter 5.57 'import'; our @EXPORT_OK = qw(uf_uri uf_uristr uf_url uf_urlstr); our $VERSION = '5.29'; our ($MY_COUNTRY, $DEBUG); sub MY_COUNTRY() { for ($MY_COUNTRY) { return $_ if defined; # First try the environment. $_ = $ENV{COUNTRY}; return $_ if defined; # Try the country part of LC_ALL and LANG from environment my @srcs = ($ENV{LC_ALL}, $ENV{LANG}); # ...and HTTP_ACCEPT_LANGUAGE before those if present if (my $httplang = $ENV{HTTP_ACCEPT_LANGUAGE}) { # TODO: q-value processing/ordering for $httplang (split(/\s*,\s*/, $httplang)) { if ($httplang =~ /^\s*([a-zA-Z]+)[_-]([a-zA-Z]{2})\s*$/) { unshift(@srcs, "${1}_${2}"); last; } } } for (@srcs) { next unless defined; return lc($1) if /^[a-zA-Z]+_([a-zA-Z]{2})(?:[.@]|$)/; } # Last bit of domain name. This may access the network. require Net::Domain; my $fqdn = Net::Domain::hostfqdn(); $_ = lc($1) if $fqdn =~ /\.([a-zA-Z]{2})$/; return $_ if defined; # Give up. Defined but false. return ($_ = 0); } } our %LOCAL_GUESSING = ( 'us' => [qw(www.ACME.gov www.ACME.mil)], 'gb' => [qw(www.ACME.co.uk www.ACME.org.uk www.ACME.ac.uk)], 'au' => [qw(www.ACME.com.au www.ACME.org.au www.ACME.edu.au)], 'il' => [qw(www.ACME.co.il www.ACME.org.il www.ACME.net.il)], # send corrections and new entries to <gisle@aas.no> ); # Backwards compatibility; uk != United Kingdom in ISO 3166 $LOCAL_GUESSING{uk} = $LOCAL_GUESSING{gb}; sub uf_uristr ($) { local($_) = @_; print STDERR "uf_uristr: resolving $_\n" if $DEBUG; return unless defined; s/^\s+//; s/\s+$//; if (/^(www|web|home)[a-z0-9-]*(?:\.|$)/i) { $_ = "http://$_"; } elsif (/^(ftp|gopher|news|wais|https|http)[a-z0-9-]*(?:\.|$)/i) { $_ = lc($1) . "://$_"; } elsif ($^O ne "MacOS" && (m,^/, || # absolute file name m,^\.\.?/, || # relative file name m,^[a-zA-Z]:[/\\],) # dosish file name ) { $_ = "file:$_"; } elsif ($^O eq "MacOS" && m/:/) { # potential MacOS file name unless (m/^(ftp|gopher|news|wais|http|https|mailto):/) { require URI::file; my $a = URI::file->new($_)->as_string; $_ = ($a =~ m/^file:/) ? $a : "file:$a"; } } elsif (/^\w+([\.\-]\w+)*\@(\w+\.)+\w{2,3}$/) { $_ = "mailto:$_"; } elsif (!/^[a-zA-Z][a-zA-Z0-9.+\-]*:/) { # no scheme specified if (s/^([-\w]+(?:\.[-\w]+)*)([\/:\?\#]|$)/$2/) { my $host = $1; my $scheme = "http"; if (/^:(\d+)\b/) { # Some more or less well known ports if ($1 =~ /^[56789]?443$/) { $scheme = "https"; } elsif ($1 eq "21") { $scheme = "ftp"; } } if ($host !~ /\./ && $host ne "localhost") { my @guess; if (exists $ENV{URL_GUESS_PATTERN}) { @guess = map { s/\bACME\b/$host/; $_ } split(' ', $ENV{URL_GUESS_PATTERN}); } else { if (MY_COUNTRY()) { my $special = $LOCAL_GUESSING{MY_COUNTRY()}; if ($special) { my @special = @$special; push(@guess, map { s/\bACME\b/$host/; $_ } @special); } else { push(@guess, "www.$host." . MY_COUNTRY()); } } push(@guess, map "www.$host.$_", "com", "org", "net", "edu", "int"); } my $guess; for $guess (@guess) { print STDERR "uf_uristr: gethostbyname('$guess.')..." if $DEBUG; if (gethostbyname("$guess.")) { print STDERR "yes\n" if $DEBUG; $host = $guess; last; } print STDERR "no\n" if $DEBUG; } } $_ = "$scheme://$host$_"; } else { # pure junk, just return it unchanged... } } print STDERR "uf_uristr: ==> $_\n" if $DEBUG; $_; } sub uf_uri ($) { require URI; URI->new(uf_uristr($_[0])); } # legacy *uf_urlstr = \*uf_uristr; sub uf_url ($) { require URI::URL; URI::URL->new(uf_uristr($_[0])); } 1; PK � �[�G�j lib/URI/_idna.pmnu ��6�$ package URI::_idna; # This module implements the RFCs 3490 (IDNA) and 3491 (Nameprep) # based on Python-2.6.4/Lib/encodings/idna.py use strict; use warnings; use URI::_punycode qw(decode_punycode encode_punycode); use Carp qw(croak); our $VERSION = '5.29'; BEGIN { *URI::_idna::_ENV_::JOIN_LEAKS_UTF8_FLAGS = "$]" < 5.008_003 ? sub () { 1 } : sub () { 0 } ; } my $ASCII = qr/^[\x00-\x7F]*\z/; sub encode { my $idomain = shift; my @labels = split(/\./, $idomain, -1); my @last_empty; push(@last_empty, pop @labels) if @labels > 1 && $labels[-1] eq ""; for (@labels) { $_ = ToASCII($_); } return eval 'join(".", @labels, @last_empty)' if URI::_idna::_ENV_::JOIN_LEAKS_UTF8_FLAGS; return join(".", @labels, @last_empty); } sub decode { my $domain = shift; return join(".", map ToUnicode($_), split(/\./, $domain, -1)) } sub nameprep { # XXX real implementation missing my $label = shift; $label = lc($label); return $label; } sub check_size { my $label = shift; croak "Label empty" if $label eq ""; croak "Label too long" if length($label) > 63; return $label; } sub ToASCII { my $label = shift; return check_size($label) if $label =~ $ASCII; # Step 2: nameprep $label = nameprep($label); # Step 3: UseSTD3ASCIIRules is false # Step 4: try ASCII again return check_size($label) if $label =~ $ASCII; # Step 5: Check ACE prefix if ($label =~ /^xn--/) { croak "Label starts with ACE prefix"; } # Step 6: Encode with PUNYCODE $label = encode_punycode($label); # Step 7: Prepend ACE prefix $label = "xn--$label"; # Step 8: Check size return check_size($label); } sub ToUnicode { my $label = shift; $label = nameprep($label) unless $label =~ $ASCII; return $label unless $label =~ /^xn--/; my $result = decode_punycode(substr($label, 4)); my $label2 = ToASCII($result); if (lc($label) ne $label2) { croak "IDNA does not round-trip: '\L$label\E' vs '$label2'"; } return $result; } 1; PK � �[�̃_� � lib/URI/icaps.pmnu ��6�$ package URI::icaps; use strict; use warnings; use base qw(URI::icap); our $VERSION = '5.29'; sub secure { return 1 } 1; __END__ =head1 NAME URI::icaps - URI scheme for ICAPS Identifiers =head1 VERSION Version 5.20 =head1 SYNOPSIS use URI::icaps; my $uri = URI->new('icaps://icap-proxy.example.com/'); =head1 DESCRIPTION This module implements the C<icaps:> URI scheme defined in L<RFC 3507|http://tools.ietf.org/html/rfc3507>, for the L<Internet Content Adaptation Protocol|https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol>. =head1 SUBROUTINES/METHODS This module inherits the behaviour of L<URI::icap|URI::icap> and overrides the L<secure|URI#$uri->secure> method. =head2 secure returns 1 as icaps is a secure protocol =head1 DIAGNOSTICS See L<URI::icap|URI::icap> =head1 CONFIGURATION AND ENVIRONMENT See L<URI::icap|URI::icap> =head1 DEPENDENCIES None =head1 INCOMPATIBILITIES None reported =head1 BUGS AND LIMITATIONS See L<URI::icap|URI::icap> =head1 SEE ALSO L<RFC 3507|http://tools.ietf.org/html/rfc3507> =head1 AUTHOR David Dick, C<< <ddick at cpan.org> >> =head1 LICENSE AND COPYRIGHT Copyright 2016 David Dick. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See L<http://dev.perl.org/licenses/> for more information. PK � �[�ys�S S man3/Exporter::Heavy.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Exporter::Heavy 3" .TH Exporter::Heavy 3 "2023-12-30" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Exporter::Heavy \- Exporter guts .SH "SYNOPSIS" .IX Header "SYNOPSIS" (internal use only) .SH "DESCRIPTION" .IX Header "DESCRIPTION" No user-serviceable parts inside. PK � �[�i>�U �U man3/Exporter.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Exporter 3" .TH Exporter 3 "2023-12-30" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Exporter \- Implements default import method for modules .SH "SYNOPSIS" .IX Header "SYNOPSIS" In module \fIYourModule.pm\fR: .PP .Vb 3 \& package YourModule; \& use Exporter \*(Aqimport\*(Aq; \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request .Ve .PP or .PP .Vb 4 \& package YourModule; \& require Exporter; \& our @ISA = qw(Exporter); # inherit all of Exporter\*(Aqs methods \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request .Ve .PP or .PP .Vb 3 \& package YourModule; \& use parent \*(AqExporter\*(Aq; # inherit all of Exporter\*(Aqs methods \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request .Ve .PP In other files which wish to use \f(CW\*(C`YourModule\*(C'\fR: .PP .Vb 2 \& use YourModule qw(frobnicate); # import listed symbols \& frobnicate ($left, $right) # calls YourModule::frobnicate .Ve .PP Take a look at \*(L"Good Practices\*(R" for some variants you will like to use in modern Perl code. .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Exporter module implements an \f(CW\*(C`import\*(C'\fR method which allows a module to export functions and variables to its users' namespaces. Many modules use Exporter rather than implementing their own \f(CW\*(C`import\*(C'\fR method because Exporter provides a highly flexible interface, with an implementation optimised for the common case. .PP Perl automatically calls the \f(CW\*(C`import\*(C'\fR method when processing a \&\f(CW\*(C`use\*(C'\fR statement for a module. Modules and \f(CW\*(C`use\*(C'\fR are documented in perlfunc and perlmod. Understanding the concept of modules and how the \f(CW\*(C`use\*(C'\fR statement operates is important to understanding the Exporter. .SS "How to Export" .IX Subsection "How to Export" The arrays \f(CW@EXPORT\fR and \f(CW@EXPORT_OK\fR in a module hold lists of symbols that are going to be exported into the users name space by default, or which they can request to be exported, respectively. The symbols can represent functions, scalars, arrays, hashes, or typeglobs. The symbols must be given by full name with the exception that the ampersand in front of a function is optional, e.g. .PP .Vb 2 \& our @EXPORT = qw(afunc $scalar @array); # afunc is a function \& our @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc .Ve .PP If you are only exporting function names it is recommended to omit the ampersand, as the implementation is faster this way. .SS "Selecting What to Export" .IX Subsection "Selecting What to Export" Do \fBnot\fR export method names! .PP Do \fBnot\fR export anything else by default without a good reason! .PP Exports pollute the namespace of the module user. If you must export try to use \f(CW@EXPORT_OK\fR in preference to \f(CW@EXPORT\fR and avoid short or common symbol names to reduce the risk of name clashes. .PP Generally anything not exported is still accessible from outside the module using the \f(CW\*(C`YourModule::item_name\*(C'\fR (or \f(CW\*(C`$blessed_ref\->method\*(C'\fR) syntax. By convention you can use a leading underscore on names to informally indicate that they are 'internal' and not for public use. .PP (It is actually possible to get private functions by saying: .PP .Vb 3 \& my $subref = sub { ... }; \& $subref\->(@args); # Call it as a function \& $obj\->$subref(@args); # Use it as a method .Ve .PP However if you use them for methods it is up to you to figure out how to make inheritance work.) .PP As a general rule, if the module is trying to be object oriented then export nothing. If it's just a collection of functions then \&\f(CW@EXPORT_OK\fR anything but use \f(CW@EXPORT\fR with caution. For function and method names use barewords in preference to names prefixed with ampersands for the export lists. .PP Other module design guidelines can be found in perlmod. .SS "How to Import" .IX Subsection "How to Import" In other files which wish to use your module there are three basic ways for them to load your module and import its symbols: .ie n .IP """use YourModule;""" 4 .el .IP "\f(CWuse YourModule;\fR" 4 .IX Item "use YourModule;" This imports all the symbols from YourModule's \f(CW@EXPORT\fR into the namespace of the \f(CW\*(C`use\*(C'\fR statement. .ie n .IP """use YourModule ();""" 4 .el .IP "\f(CWuse YourModule ();\fR" 4 .IX Item "use YourModule ();" This causes perl to load your module but does not import any symbols. .ie n .IP """use YourModule qw(...);""" 4 .el .IP "\f(CWuse YourModule qw(...);\fR" 4 .IX Item "use YourModule qw(...);" This imports only the symbols listed by the caller into their namespace. All listed symbols must be in your \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR, else an error occurs. The advanced export features of Exporter are accessed like this, but with list entries that are syntactically distinct from symbol names. .PP Unless you want to use its advanced features, this is probably all you need to know to use Exporter. .SH "Advanced Features" .IX Header "Advanced Features" .SS "Specialised Import Lists" .IX Subsection "Specialised Import Lists" If any of the entries in an import list begins with !, : or / then the list is treated as a series of specifications which either add to or delete from the list of names to import. They are processed left to right. Specifications are in the form: .PP .Vb 4 \& [!]name This name only \& [!]:DEFAULT All names in @EXPORT \& [!]:tag All names in $EXPORT_TAGS{tag} anonymous array \& [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match .Ve .PP A leading ! indicates that matching names should be deleted from the list of names to import. If the first specification is a deletion it is treated as though preceded by :DEFAULT. If you just want to import extra names in addition to the default set you will still need to include :DEFAULT explicitly. .PP e.g., \fIModule.pm\fR defines: .PP .Vb 3 \& our @EXPORT = qw(A1 A2 A3 A4 A5); \& our @EXPORT_OK = qw(B1 B2 B3 B4 B5); \& our %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); .Ve .PP Note that you cannot use tags in \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. .PP Names in \s-1EXPORT_TAGS\s0 must also appear in \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. .PP An application using Module can say something like: .PP .Vb 1 \& use Module qw(:DEFAULT :T2 !B3 A3); .Ve .PP Other examples include: .PP .Vb 2 \& use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); \& use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/); .Ve .PP Remember that most patterns (using //) will need to be anchored with a leading ^, e.g., \f(CW\*(C`/^EXIT/\*(C'\fR rather than \f(CW\*(C`/EXIT/\*(C'\fR. .PP You can say \f(CW\*(C`BEGIN { $Exporter::Verbose=1 }\*(C'\fR to see how the specifications are being processed and what is actually being imported into modules. .SS "Exporting Without Using Exporter's import Method" .IX Subsection "Exporting Without Using Exporter's import Method" Exporter has a special method, 'export_to_level' which is used in situations where you can't directly call Exporter's import method. The export_to_level method looks like: .PP .Vb 3 \& MyPackage\->export_to_level( \& $where_to_export, $package, @what_to_export \& ); .Ve .PP where \f(CW$where_to_export\fR is an integer telling how far up the calling stack to export your symbols, and \f(CW@what_to_export\fR is an array telling what symbols *to* export (usually this is \f(CW@_\fR). The \f(CW$package\fR argument is currently unused. .PP For example, suppose that you have a module, A, which already has an import function: .PP .Vb 1 \& package A; \& \& our @ISA = qw(Exporter); \& our @EXPORT_OK = qw($b); \& \& sub import \& { \& $A::b = 1; # not a very useful import method \& } .Ve .PP and you want to Export symbol \f(CW$A::b\fR back to the module that called package A. Since Exporter relies on the import method to work, via inheritance, as it stands \fBExporter::import()\fR will never get called. Instead, say the following: .PP .Vb 3 \& package A; \& our @ISA = qw(Exporter); \& our @EXPORT_OK = qw($b); \& \& sub import \& { \& $A::b = 1; \& A\->export_to_level(1, @_); \& } .Ve .PP This will export the symbols one level 'above' the current package \- ie: to the program or module that used package A. .PP Note: Be careful not to modify \f(CW@_\fR at all before you call export_to_level \&\- or people using your package will get very unexplained results! .SS "Exporting Without Inheriting from Exporter" .IX Subsection "Exporting Without Inheriting from Exporter" By including Exporter in your \f(CW@ISA\fR you inherit an Exporter's \fBimport()\fR method but you also inherit several other helper methods which you probably don't want and complicate the inheritance tree. To avoid this you can do: .PP .Vb 2 \& package YourModule; \& use Exporter qw(import); .Ve .PP which will export Exporter's own \fBimport()\fR method into YourModule. Everything will work as before but you won't need to include Exporter in \&\f(CW@YourModule::ISA\fR. .PP Note: This feature was introduced in version 5.57 of Exporter, released with perl 5.8.3. .SS "Module Version Checking" .IX Subsection "Module Version Checking" The Exporter module will convert an attempt to import a number from a module into a call to \f(CW\*(C`$module_name\->VERSION($value)\*(C'\fR. This can be used to validate that the version of the module being used is greater than or equal to the required version. .PP For historical reasons, Exporter supplies a \f(CW\*(C`require_version\*(C'\fR method that simply delegates to \f(CW\*(C`VERSION\*(C'\fR. Originally, before \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR existed, Exporter would call \f(CW\*(C`require_version\*(C'\fR. .PP Since the \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR method treats the \f(CW$VERSION\fR number as a simple numeric value it will regard version 1.10 as lower than 1.9. For this reason it is strongly recommended that you use numbers with at least two decimal places, e.g., 1.09. .SS "Managing Unknown Symbols" .IX Subsection "Managing Unknown Symbols" In some situations you may want to prevent certain symbols from being exported. Typically this applies to extensions which have functions or constants that may not exist on some systems. .PP The names of any symbols that cannot be exported should be listed in the \f(CW@EXPORT_FAIL\fR array. .PP If a module attempts to import any of these symbols the Exporter will give the module an opportunity to handle the situation before generating an error. The Exporter will call an export_fail method with a list of the failed symbols: .PP .Vb 1 \& @failed_symbols = $module_name\->export_fail(@failed_symbols); .Ve .PP If the \f(CW\*(C`export_fail\*(C'\fR method returns an empty list then no error is recorded and all the requested symbols are exported. If the returned list is not empty then an error is generated for each symbol and the export fails. The Exporter provides a default \f(CW\*(C`export_fail\*(C'\fR method which simply returns the list unchanged. .PP Uses for the \f(CW\*(C`export_fail\*(C'\fR method include giving better error messages for some symbols and performing lazy architectural checks (put more symbols into \f(CW@EXPORT_FAIL\fR by default and then take them out if someone actually tries to use them and an expensive check shows that they are usable on that platform). .SS "Tag Handling Utility Functions" .IX Subsection "Tag Handling Utility Functions" Since the symbols listed within \f(CW%EXPORT_TAGS\fR must also appear in either \&\f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR, two utility functions are provided which allow you to easily add tagged sets of symbols to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR: .PP .Vb 1 \& our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); \& \& Exporter::export_tags(\*(Aqfoo\*(Aq); # add aa, bb and cc to @EXPORT \& Exporter::export_ok_tags(\*(Aqbar\*(Aq); # add aa, cc and dd to @EXPORT_OK .Ve .PP Any names which are not tags are added to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR unchanged but will trigger a warning (with \f(CW\*(C`\-w\*(C'\fR) to avoid misspelt tags names being silently added to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. Future versions may make this a fatal error. .SS "Generating Combined Tags" .IX Subsection "Generating Combined Tags" If several symbol categories exist in \f(CW%EXPORT_TAGS\fR, it's usually useful to create the utility \*(L":all\*(R" to simplify \*(L"use\*(R" statements. .PP The simplest way to do this is: .PP .Vb 1 \& our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); \& \& # add all the other ":class" tags to the ":all" class, \& # deleting duplicates \& { \& my %seen; \& \& push @{$EXPORT_TAGS{all}}, \& grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS; \& } .Ve .PP \&\fI\s-1CGI\s0.pm\fR creates an \*(L":all\*(R" tag which contains some (but not really all) of its categories. That could be done with one small change: .PP .Vb 4 \& # add some of the other ":class" tags to the ":all" class, \& # deleting duplicates \& { \& my %seen; \& \& push @{$EXPORT_TAGS{all}}, \& grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} \& foreach qw/html2 html3 netscape form cgi internal/; \& } .Ve .PP Note that the tag names in \f(CW%EXPORT_TAGS\fR don't have the leading ':'. .ie n .SS """AUTOLOAD""ed Constants" .el .SS "\f(CWAUTOLOAD\fPed Constants" .IX Subsection "AUTOLOADed Constants" Many modules make use of \f(CW\*(C`AUTOLOAD\*(C'\fRing for constant subroutines to avoid having to compile and waste memory on rarely used values (see perlsub for details on constant subroutines). Calls to such constant subroutines are not optimized away at compile time because they can't be checked at compile time for constancy. .PP Even if a prototype is available at compile time, the body of the subroutine is not (it hasn't been \f(CW\*(C`AUTOLOAD\*(C'\fRed yet). perl needs to examine both the \f(CW\*(C`()\*(C'\fR prototype and the body of a subroutine at compile time to detect that it can safely replace calls to that subroutine with the constant value. .PP A workaround for this is to call the constants once in a \f(CW\*(C`BEGIN\*(C'\fR block: .PP .Vb 1 \& package My ; \& \& use Socket ; \& \& foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime \& BEGIN { SO_LINGER } \& foo( SO_LINGER ); ## SO_LINGER optimized away at compile time. .Ve .PP This forces the \f(CW\*(C`AUTOLOAD\*(C'\fR for \f(CW\*(C`SO_LINGER\*(C'\fR to take place before \&\s-1SO_LINGER\s0 is encountered later in \f(CW\*(C`My\*(C'\fR package. .PP If you are writing a package that \f(CW\*(C`AUTOLOAD\*(C'\fRs, consider forcing an \f(CW\*(C`AUTOLOAD\*(C'\fR for any constants explicitly imported by other packages or which are usually used when your package is \f(CW\*(C`use\*(C'\fRd. .SH "Good Practices" .IX Header "Good Practices" .ie n .SS "Declaring @EXPORT_OK and Friends" .el .SS "Declaring \f(CW@EXPORT_OK\fP and Friends" .IX Subsection "Declaring @EXPORT_OK and Friends" When using \f(CW\*(C`Exporter\*(C'\fR with the standard \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR pragmas, the \f(CW\*(C`our\*(C'\fR keyword is needed to declare the package variables \f(CW@EXPORT_OK\fR, \f(CW@EXPORT\fR, \f(CW@ISA\fR, etc. .PP .Vb 2 \& our @ISA = qw(Exporter); \& our @EXPORT_OK = qw(munge frobnicate); .Ve .PP If backward compatibility for Perls \fBunder\fR 5.6 is important, one must write instead a \f(CW\*(C`use vars\*(C'\fR statement. .PP .Vb 3 \& use vars qw(@ISA @EXPORT_OK); \& @ISA = qw(Exporter); \& @EXPORT_OK = qw(munge frobnicate); .Ve .SS "Playing Safe" .IX Subsection "Playing Safe" There are some caveats with the use of runtime statements like \f(CW\*(C`require Exporter\*(C'\fR and the assignment to package variables, which can be very subtle for the unaware programmer. This may happen for instance with mutually recursive modules, which are affected by the time the relevant constructions are executed. .PP The ideal way to never have to think about that is to use \&\f(CW\*(C`BEGIN\*(C'\fR blocks and the simple import method. So the first part of the \*(L"\s-1SYNOPSIS\*(R"\s0 code could be rewritten as: .PP .Vb 1 \& package YourModule; \& \& use strict; \& use warnings; \& \& use Exporter \*(Aqimport\*(Aq; \& BEGIN { \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request \& } .Ve .PP Or if you need to inherit from Exporter: .PP .Vb 1 \& package YourModule; \& \& use strict; \& use warnings; \& \& BEGIN { \& require Exporter; \& our @ISA = qw(Exporter); # inherit all of Exporter\*(Aqs methods \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request \& } .Ve .PP The \f(CW\*(C`BEGIN\*(C'\fR will assure that the loading of \fIExporter.pm\fR and the assignments to \f(CW@ISA\fR and \f(CW@EXPORT_OK\fR happen immediately like \f(CW\*(C`use\*(C'\fR, leaving no room for something to get awry or just plain wrong. .PP With respect to loading \f(CW\*(C`Exporter\*(C'\fR and inheriting, there are alternatives with the use of modules like \f(CW\*(C`base\*(C'\fR and \f(CW\*(C`parent\*(C'\fR. .PP .Vb 3 \& use base qw(Exporter); \& # or \& use parent qw(Exporter); .Ve .PP Any of these statements are nice replacements for \&\f(CW\*(C`BEGIN { require Exporter; our @ISA = qw(Exporter); }\*(C'\fR with the same compile-time effect. The basic difference is that \f(CW\*(C`base\*(C'\fR code interacts with declared \f(CW\*(C`fields\*(C'\fR while \f(CW\*(C`parent\*(C'\fR is a streamlined version of the older \&\f(CW\*(C`base\*(C'\fR code to just establish the IS-A relationship. .PP For more details, see the documentation and code of base and parent. .PP Another thorough remedy to that runtime vs. compile-time trap is to use Exporter::Easy, which is a wrapper of Exporter that allows all boilerplate code at a single gulp in the use statement. .PP .Vb 5 \& use Exporter::Easy ( \& OK => [ qw(munge frobnicate) ], \& ); \& # @ISA setup is automatic \& # all assignments happen at compile time .Ve .SS "What Not to Export" .IX Subsection "What Not to Export" You have been warned already in \*(L"Selecting What to Export\*(R" to not export: .IP "\(bu" 4 method names (because you don't need to and that's likely to not do what you want), .IP "\(bu" 4 anything by default (because you don't want to surprise your users... badly) .IP "\(bu" 4 anything you don't need to (because less is more) .PP There's one more item to add to this list. Do \fBnot\fR export variable names. Just because \f(CW\*(C`Exporter\*(C'\fR lets you do that, it does not mean you should. .PP .Vb 1 \& @EXPORT_OK = qw($svar @avar %hvar); # DON\*(AqT! .Ve .PP Exporting variables is not a good idea. They can change under the hood, provoking horrible effects at-a-distance that are too hard to track and to fix. Trust me: they are not worth it. .PP To provide the capability to set/get class-wide settings, it is best instead to provide accessors as subroutines or class methods instead. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\f(CW\*(C`Exporter\*(C'\fR is definitely not the only module with symbol exporter capabilities. At \s-1CPAN,\s0 you may find a bunch of them. Some are lighter. Some provide improved APIs and features. Pick the one that fits your needs. The following is a sample list of such modules. .PP .Vb 6 \& Exporter::Easy \& Exporter::Lite \& Exporter::Renaming \& Exporter::Tidy \& Sub::Exporter / Sub::Installer \& Perl6::Export / Perl6::Export::Attrs .Ve .SH "LICENSE" .IX Header "LICENSE" This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. PK � �[ arch/auto/Exporter/.existsnu �[��� PK � �[Ӛ�� � lib/Exporter/Heavy.pmnu ��6�$ package Exporter::Heavy; use strict; no strict 'refs'; # On one line so MakeMaker will see it. our $VERSION = '5.78'; =head1 NAME Exporter::Heavy - Exporter guts =head1 SYNOPSIS (internal use only) =head1 DESCRIPTION No user-serviceable parts inside. =cut # # We go to a lot of trouble not to 'require Carp' at file scope, # because Carp requires Exporter, and something has to give. # sub _rebuild_cache { my ($pkg, $exports, $cache) = @_; s/^&// foreach @$exports; @{$cache}{@$exports} = (1) x @$exports; my $ok = \@{"${pkg}::EXPORT_OK"}; if (@$ok) { s/^&// foreach @$ok; @{$cache}{@$ok} = (1) x @$ok; } } sub heavy_export { # Save the old __WARN__ handler in case it was defined my $oldwarn = $SIG{__WARN__}; # First make import warnings look like they're coming from the "use". local $SIG{__WARN__} = sub { # restore it back so proper stacking occurs local $SIG{__WARN__} = $oldwarn; my $text = shift; if ($text =~ s/ at \S*Exporter\S*.pm line \d+.*\n//) { require Carp; local $Carp::CarpLevel = 1; # ignore package calling us too. Carp::carp($text); } else { warn $text; } }; local $SIG{__DIE__} = sub { require Carp; local $Carp::CarpLevel = 1; # ignore package calling us too. Carp::croak("$_[0]Illegal null symbol in \@${1}::EXPORT") if $_[0] =~ /^Unable to create sub named "(.*?)::"/; }; my($pkg, $callpkg, @imports) = @_; my($type, $sym, $cache_is_current, $oops); my($exports, $export_cache) = (\@{"${pkg}::EXPORT"}, $Exporter::Cache{$pkg} ||= {}); if (@imports) { if (!%$export_cache) { _rebuild_cache ($pkg, $exports, $export_cache); $cache_is_current = 1; } if (grep m{^[/!:]}, @imports) { my $tagsref = \%{"${pkg}::EXPORT_TAGS"}; my $tagdata; my %imports; my($remove, $spec, @names, @allexports); # negated first item implies starting with default set: unshift @imports, ':DEFAULT' if $imports[0] =~ m/^!/; foreach $spec (@imports){ $remove = $spec =~ s/^!//; if ($spec =~ s/^://){ if ($spec eq 'DEFAULT'){ @names = @$exports; } elsif ($tagdata = $tagsref->{$spec}) { @names = @$tagdata; } else { warn qq["$spec" is not defined in %${pkg}::EXPORT_TAGS]; ++$oops; next; } } elsif ($spec =~ m:^/(.*)/$:){ my $patn = $1; @allexports = keys %$export_cache unless @allexports; # only do keys once @names = grep(/$patn/, @allexports); # not anchored by default } else { @names = ($spec); # is a normal symbol name } warn "Import ".($remove ? "del":"add").": @names " if $Exporter::Verbose; if ($remove) { foreach $sym (@names) { delete $imports{$sym} } } else { @imports{@names} = (1) x @names; } } @imports = keys %imports; } my @carp; foreach $sym (@imports) { if (!$export_cache->{$sym}) { if ($sym =~ m/^\d/) { $pkg->VERSION($sym); # inherit from UNIVERSAL # If the version number was the only thing specified # then we should act as if nothing was specified: if (@imports == 1) { @imports = @$exports; last; } # We need a way to emulate 'use Foo ()' but still # allow an easy version check: "use Foo 1.23, ''"; if (@imports == 2 and !$imports[1]) { @imports = (); last; } } elsif ($sym !~ s/^&// || !$export_cache->{$sym}) { # Last chance - see if they've updated EXPORT_OK since we # cached it. unless ($cache_is_current) { %$export_cache = (); _rebuild_cache ($pkg, $exports, $export_cache); $cache_is_current = 1; } if (!$export_cache->{$sym}) { # accumulate the non-exports push @carp, qq["$sym" is not exported by the $pkg module]; $oops++; } } } } if ($oops) { require Carp; Carp::croak(join("\n", @carp, "Can't continue after import errors")); } } else { @imports = @$exports; } my($fail, $fail_cache) = (\@{"${pkg}::EXPORT_FAIL"}, $Exporter::FailCache{$pkg} ||= {}); if (@$fail) { if (!%$fail_cache) { # Build cache of symbols. Optimise the lookup by adding # barewords twice... both with and without a leading &. # (Technique could be applied to $export_cache at cost of memory) my @expanded = map { /^\w/ ? ($_, '&'.$_) : $_ } @$fail; warn "${pkg}::EXPORT_FAIL cached: @expanded" if $Exporter::Verbose; @{$fail_cache}{@expanded} = (1) x @expanded; } my @failed; foreach $sym (@imports) { push(@failed, $sym) if $fail_cache->{$sym} } if (@failed) { @failed = $pkg->export_fail(@failed); foreach $sym (@failed) { require Carp; Carp::carp(qq["$sym" is not implemented by the $pkg module ], "on this architecture"); } if (@failed) { require Carp; Carp::croak("Can't continue after import errors"); } } } warn "Importing into $callpkg from $pkg: ", join(", ",sort @imports) if $Exporter::Verbose; foreach $sym (@imports) { # shortcut for the common case of no type character (*{"${callpkg}::$sym"} = \&{"${pkg}::$sym"}, next) unless $sym =~ s/^(\W)//; $type = $1; no warnings 'once'; *{"${callpkg}::$sym"} = $type eq '&' ? \&{"${pkg}::$sym"} : $type eq '$' ? \${"${pkg}::$sym"} : $type eq '@' ? \@{"${pkg}::$sym"} : $type eq '%' ? \%{"${pkg}::$sym"} : $type eq '*' ? *{"${pkg}::$sym"} : do { require Carp; Carp::croak("Can't export symbol: $type$sym") }; } } sub heavy_export_to_level { my $pkg = shift; my $level = shift; (undef) = shift; # XXX redundant arg my $callpkg = caller($level); $pkg->export($callpkg, @_); } # Utility functions sub _push_tags { my($pkg, $var, $syms) = @_; my @nontag = (); my $export_tags = \%{"${pkg}::EXPORT_TAGS"}; push(@{"${pkg}::$var"}, map { $export_tags->{$_} ? @{$export_tags->{$_}} : scalar(push(@nontag,$_),$_) } (@$syms) ? @$syms : keys %$export_tags); if (@nontag and $^W) { # This may change to a die one day require Carp; Carp::carp(join(", ", @nontag)." are not tags of $pkg"); } } sub heavy_require_version { my($self, $wanted) = @_; my $pkg = ref $self || $self; return ${pkg}->VERSION($wanted); } sub heavy_export_tags { _push_tags((caller)[0], "EXPORT", \@_); } sub heavy_export_ok_tags { _push_tags((caller)[0], "EXPORT_OK", \@_); } 1; PK � �[�^C2 K K lib/Exporter.pmnu ��6�$ package Exporter; use strict; no strict 'refs'; our $Debug = 0; our $ExportLevel = 0; our $Verbose ||= 0; our $VERSION = '5.78'; our %Cache; sub as_heavy { require Exporter::Heavy; # Unfortunately, this does not work if the caller is aliased as *name = \&foo # Thus the need to create a lot of identical subroutines my $c = (caller(1))[3]; $c =~ s/.*:://; \&{"Exporter::Heavy::heavy_$c"}; } sub export { goto &{as_heavy()}; } sub import { my $pkg = shift; my $callpkg = caller($ExportLevel); if ($pkg eq "Exporter" and @_ and $_[0] eq "import") { *{$callpkg."::import"} = \&import; return; } # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-( my $exports = \@{"$pkg\::EXPORT"}; # But, avoid creating things if they don't exist, which saves a couple of # hundred bytes per package processed. my $fail = ${$pkg . '::'}{EXPORT_FAIL} && \@{"$pkg\::EXPORT_FAIL"}; return export $pkg, $callpkg, @_ if $Verbose or $Debug or $fail && @$fail > 1; my $export_cache = ($Cache{$pkg} ||= {}); my $args = @_ or @_ = @$exports; if ($args and not %$export_cache) { s/^&//, $export_cache->{$_} = 1 foreach (@$exports, @{"$pkg\::EXPORT_OK"}); } my $heavy; # Try very hard not to use {} and hence have to enter scope on the foreach # We bomb out of the loop with last as soon as heavy is set. if ($args or $fail) { ($heavy = (/\W/ or $args and not exists $export_cache->{$_} or $fail and @$fail and $_ eq $fail->[0])) and last foreach (@_); } else { ($heavy = /\W/) and last foreach (@_); } return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy; local $SIG{__WARN__} = sub {require Carp; &Carp::carp} if not $SIG{__WARN__}; # shortcut for the common case of no type character *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_; } # Default methods sub export_fail { my $self = shift; @_; } # Unfortunately, caller(1)[3] "does not work" if the caller is aliased as # *name = \&foo. Thus the need to create a lot of identical subroutines # Otherwise we could have aliased them to export(). sub export_to_level { goto &{as_heavy()}; } sub export_tags { goto &{as_heavy()}; } sub export_ok_tags { goto &{as_heavy()}; } sub require_version { goto &{as_heavy()}; } 1; __END__ =head1 NAME Exporter - Implements default import method for modules =head1 SYNOPSIS In module F<YourModule.pm>: package YourModule; use Exporter 'import'; our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request or package YourModule; require Exporter; our @ISA = qw(Exporter); # inherit all of Exporter's methods our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request or package YourModule; use parent 'Exporter'; # inherit all of Exporter's methods our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request In other files which wish to use C<YourModule>: use YourModule qw(frobnicate); # import listed symbols frobnicate ($left, $right) # calls YourModule::frobnicate Take a look at L</Good Practices> for some variants you will like to use in modern Perl code. =head1 DESCRIPTION The Exporter module implements an C<import> method which allows a module to export functions and variables to its users' namespaces. Many modules use Exporter rather than implementing their own C<import> method because Exporter provides a highly flexible interface, with an implementation optimised for the common case. Perl automatically calls the C<import> method when processing a C<use> statement for a module. Modules and C<use> are documented in L<perlfunc> and L<perlmod>. Understanding the concept of modules and how the C<use> statement operates is important to understanding the Exporter. =head2 How to Export The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of symbols that are going to be exported into the users name space by default, or which they can request to be exported, respectively. The symbols can represent functions, scalars, arrays, hashes, or typeglobs. The symbols must be given by full name with the exception that the ampersand in front of a function is optional, e.g. our @EXPORT = qw(afunc $scalar @array); # afunc is a function our @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc If you are only exporting function names it is recommended to omit the ampersand, as the implementation is faster this way. =head2 Selecting What to Export Do B<not> export method names! Do B<not> export anything else by default without a good reason! Exports pollute the namespace of the module user. If you must export try to use C<@EXPORT_OK> in preference to C<@EXPORT> and avoid short or common symbol names to reduce the risk of name clashes. Generally anything not exported is still accessible from outside the module using the C<YourModule::item_name> (or C<< $blessed_ref->method >>) syntax. By convention you can use a leading underscore on names to informally indicate that they are 'internal' and not for public use. (It is actually possible to get private functions by saying: my $subref = sub { ... }; $subref->(@args); # Call it as a function $obj->$subref(@args); # Use it as a method However if you use them for methods it is up to you to figure out how to make inheritance work.) As a general rule, if the module is trying to be object oriented then export nothing. If it's just a collection of functions then C<@EXPORT_OK> anything but use C<@EXPORT> with caution. For function and method names use barewords in preference to names prefixed with ampersands for the export lists. Other module design guidelines can be found in L<perlmod>. =head2 How to Import In other files which wish to use your module there are three basic ways for them to load your module and import its symbols: =over 4 =item C<use YourModule;> This imports all the symbols from YourModule's C<@EXPORT> into the namespace of the C<use> statement. =item C<use YourModule ();> This causes perl to load your module but does not import any symbols. =item C<use YourModule qw(...);> This imports only the symbols listed by the caller into their namespace. All listed symbols must be in your C<@EXPORT> or C<@EXPORT_OK>, else an error occurs. The advanced export features of Exporter are accessed like this, but with list entries that are syntactically distinct from symbol names. =back Unless you want to use its advanced features, this is probably all you need to know to use Exporter. =head1 Advanced Features =head2 Specialised Import Lists If any of the entries in an import list begins with !, : or / then the list is treated as a series of specifications which either add to or delete from the list of names to import. They are processed left to right. Specifications are in the form: [!]name This name only [!]:DEFAULT All names in @EXPORT [!]:tag All names in $EXPORT_TAGS{tag} anonymous array [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match A leading ! indicates that matching names should be deleted from the list of names to import. If the first specification is a deletion it is treated as though preceded by :DEFAULT. If you just want to import extra names in addition to the default set you will still need to include :DEFAULT explicitly. e.g., F<Module.pm> defines: our @EXPORT = qw(A1 A2 A3 A4 A5); our @EXPORT_OK = qw(B1 B2 B3 B4 B5); our %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); Note that you cannot use tags in @EXPORT or @EXPORT_OK. Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK. An application using Module can say something like: use Module qw(:DEFAULT :T2 !B3 A3); Other examples include: use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/); Remember that most patterns (using //) will need to be anchored with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>. You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the specifications are being processed and what is actually being imported into modules. =head2 Exporting Without Using Exporter's import Method Exporter has a special method, 'export_to_level' which is used in situations where you can't directly call Exporter's import method. The export_to_level method looks like: MyPackage->export_to_level( $where_to_export, $package, @what_to_export ); where C<$where_to_export> is an integer telling how far up the calling stack to export your symbols, and C<@what_to_export> is an array telling what symbols *to* export (usually this is C<@_>). The C<$package> argument is currently unused. For example, suppose that you have a module, A, which already has an import function: package A; our @ISA = qw(Exporter); our @EXPORT_OK = qw($b); sub import { $A::b = 1; # not a very useful import method } and you want to Export symbol C<$A::b> back to the module that called package A. Since Exporter relies on the import method to work, via inheritance, as it stands Exporter::import() will never get called. Instead, say the following: package A; our @ISA = qw(Exporter); our @EXPORT_OK = qw($b); sub import { $A::b = 1; A->export_to_level(1, @_); } This will export the symbols one level 'above' the current package - ie: to the program or module that used package A. Note: Be careful not to modify C<@_> at all before you call export_to_level - or people using your package will get very unexplained results! =head2 Exporting Without Inheriting from Exporter By including Exporter in your C<@ISA> you inherit an Exporter's import() method but you also inherit several other helper methods which you probably don't want and complicate the inheritance tree. To avoid this you can do: package YourModule; use Exporter qw(import); which will export Exporter's own import() method into YourModule. Everything will work as before but you won't need to include Exporter in C<@YourModule::ISA>. Note: This feature was introduced in version 5.57 of Exporter, released with perl 5.8.3. =head2 Module Version Checking The Exporter module will convert an attempt to import a number from a module into a call to C<< $module_name->VERSION($value) >>. This can be used to validate that the version of the module being used is greater than or equal to the required version. For historical reasons, Exporter supplies a C<require_version> method that simply delegates to C<VERSION>. Originally, before C<UNIVERSAL::VERSION> existed, Exporter would call C<require_version>. Since the C<UNIVERSAL::VERSION> method treats the C<$VERSION> number as a simple numeric value it will regard version 1.10 as lower than 1.9. For this reason it is strongly recommended that you use numbers with at least two decimal places, e.g., 1.09. =head2 Managing Unknown Symbols In some situations you may want to prevent certain symbols from being exported. Typically this applies to extensions which have functions or constants that may not exist on some systems. The names of any symbols that cannot be exported should be listed in the C<@EXPORT_FAIL> array. If a module attempts to import any of these symbols the Exporter will give the module an opportunity to handle the situation before generating an error. The Exporter will call an export_fail method with a list of the failed symbols: @failed_symbols = $module_name->export_fail(@failed_symbols); If the C<export_fail> method returns an empty list then no error is recorded and all the requested symbols are exported. If the returned list is not empty then an error is generated for each symbol and the export fails. The Exporter provides a default C<export_fail> method which simply returns the list unchanged. Uses for the C<export_fail> method include giving better error messages for some symbols and performing lazy architectural checks (put more symbols into C<@EXPORT_FAIL> by default and then take them out if someone actually tries to use them and an expensive check shows that they are usable on that platform). =head2 Tag Handling Utility Functions Since the symbols listed within C<%EXPORT_TAGS> must also appear in either C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>: our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK> unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions may make this a fatal error. =head2 Generating Combined Tags If several symbol categories exist in C<%EXPORT_TAGS>, it's usually useful to create the utility ":all" to simplify "use" statements. The simplest way to do this is: our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); # add all the other ":class" tags to the ":all" class, # deleting duplicates { my %seen; push @{$EXPORT_TAGS{all}}, grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS; } F<CGI.pm> creates an ":all" tag which contains some (but not really all) of its categories. That could be done with one small change: # add some of the other ":class" tags to the ":all" class, # deleting duplicates { my %seen; push @{$EXPORT_TAGS{all}}, grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach qw/html2 html3 netscape form cgi internal/; } Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'. =head2 C<AUTOLOAD>ed Constants Many modules make use of C<AUTOLOAD>ing for constant subroutines to avoid having to compile and waste memory on rarely used values (see L<perlsub> for details on constant subroutines). Calls to such constant subroutines are not optimized away at compile time because they can't be checked at compile time for constancy. Even if a prototype is available at compile time, the body of the subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to examine both the C<()> prototype and the body of a subroutine at compile time to detect that it can safely replace calls to that subroutine with the constant value. A workaround for this is to call the constants once in a C<BEGIN> block: package My ; use Socket ; foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime BEGIN { SO_LINGER } foo( SO_LINGER ); ## SO_LINGER optimized away at compile time. This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before SO_LINGER is encountered later in C<My> package. If you are writing a package that C<AUTOLOAD>s, consider forcing an C<AUTOLOAD> for any constants explicitly imported by other packages or which are usually used when your package is C<use>d. =head1 Good Practices =head2 Declaring C<@EXPORT_OK> and Friends When using C<Exporter> with the standard C<strict> and C<warnings> pragmas, the C<our> keyword is needed to declare the package variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc. our @ISA = qw(Exporter); our @EXPORT_OK = qw(munge frobnicate); If backward compatibility for Perls B<under> 5.6 is important, one must write instead a C<use vars> statement. use vars qw(@ISA @EXPORT_OK); @ISA = qw(Exporter); @EXPORT_OK = qw(munge frobnicate); =head2 Playing Safe There are some caveats with the use of runtime statements like C<require Exporter> and the assignment to package variables, which can be very subtle for the unaware programmer. This may happen for instance with mutually recursive modules, which are affected by the time the relevant constructions are executed. The ideal way to never have to think about that is to use C<BEGIN> blocks and the simple import method. So the first part of the L</SYNOPSIS> code could be rewritten as: package YourModule; use strict; use warnings; use Exporter 'import'; BEGIN { our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request } Or if you need to inherit from Exporter: package YourModule; use strict; use warnings; BEGIN { require Exporter; our @ISA = qw(Exporter); # inherit all of Exporter's methods our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request } The C<BEGIN> will assure that the loading of F<Exporter.pm> and the assignments to C<@ISA> and C<@EXPORT_OK> happen immediately like C<use>, leaving no room for something to get awry or just plain wrong. With respect to loading C<Exporter> and inheriting, there are alternatives with the use of modules like C<base> and C<parent>. use base qw(Exporter); # or use parent qw(Exporter); Any of these statements are nice replacements for C<BEGIN { require Exporter; our @ISA = qw(Exporter); }> with the same compile-time effect. The basic difference is that C<base> code interacts with declared C<fields> while C<parent> is a streamlined version of the older C<base> code to just establish the IS-A relationship. For more details, see the documentation and code of L<base> and L<parent>. Another thorough remedy to that runtime vs. compile-time trap is to use L<Exporter::Easy>, which is a wrapper of Exporter that allows all boilerplate code at a single gulp in the use statement. use Exporter::Easy ( OK => [ qw(munge frobnicate) ], ); # @ISA setup is automatic # all assignments happen at compile time =head2 What Not to Export You have been warned already in L</Selecting What to Export> to not export: =over 4 =item * method names (because you don't need to and that's likely to not do what you want), =item * anything by default (because you don't want to surprise your users... badly) =item * anything you don't need to (because less is more) =back There's one more item to add to this list. Do B<not> export variable names. Just because C<Exporter> lets you do that, it does not mean you should. @EXPORT_OK = qw($svar @avar %hvar); # DON'T! Exporting variables is not a good idea. They can change under the hood, provoking horrible effects at-a-distance that are too hard to track and to fix. Trust me: they are not worth it. To provide the capability to set/get class-wide settings, it is best instead to provide accessors as subroutines or class methods instead. =head1 SEE ALSO C<Exporter> is definitely not the only module with symbol exporter capabilities. At CPAN, you may find a bunch of them. Some are lighter. Some provide improved APIs and features. Pick the one that fits your needs. The following is a sample list of such modules. Exporter::Easy Exporter::Lite Exporter::Renaming Exporter::Tidy Sub::Exporter / Sub::Installer Perl6::Export / Perl6::Export::Attrs =head1 LICENSE This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[ lib/auto/Exporter/.existsnu �[��� PK � �[=D�� � man3/Mock::Config.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Mock::Config 3" .TH Mock::Config 3 "2016-04-18" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Mock::Config \- temporarily set Config or XSConfig values .SH "VERSION" .IX Header "VERSION" Version 0.02 .SH "SYNOPSIS" .IX Header "SYNOPSIS" XSConfig is readonly, so workaround that. .PP .Vb 1 \& use Mock::Config d_fork => 0, perl_patchlevel => \*(Aq\*(Aq; .Ve .PP The importer works only dynamically, not lexically yet. .PP .Vb 4 \& use Mock::Config; \& Mock::Config\->import(startperl => \*(Aq\*(Aq); \& print $Config{startperl}, \*(Aq mocked to empty\*(Aq; \& Mock::Config\->unimport; .Ve .SH "SUBROUTINES" .IX Header "SUBROUTINES" .SS "import" .IX Subsection "import" Set pair of Config values, even for the readonly XSConfig implementation, as used in cperl. .PP It does not store the mocked overrides lexically, just dynamically. .SS "unimport" .IX Subsection "unimport" This is unstacked and not lexical. It undoes all imported Config values at once. .SH "AUTHOR" .IX Header "AUTHOR" Reini Urban, \f(CW\*(C`<rurban at cpan.org>\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests at <https://github.com/perl11/Mock\-Config/issues>. .PP We will be notified, and then you'll automatically be notified of progress on your request as we make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Mock::Config .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker (report bugs here) .Sp <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mock\-Config> .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp <http://annocpan.org/dist/Mock\-Config> .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp <http://cpanratings.perl.org/d/Mock\-Config> .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp <http://search.cpan.org/dist/Mock\-Config/> .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2016 cPanel Inc. .PP This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: .PP <http://www.perlfoundation.org/artistic_license_2_0> .PP Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license. .PP If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license. .PP This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. .PP This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed. .PP Disclaimer of Warranty: \s-1THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS\s0' \s-1AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR\s0 NON-INFRINGEMENT \s-1ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[ arch/auto/Mock/Config/.existsnu �[��� PK � �[ lib/Mock/.existsnu �[��� PK � �[�i� e e lib/Mock/Config.pmnu ��6�$ package Mock::Config; use 5.006; use Config (); our %MockConfig; =head1 NAME Mock::Config - temporarily set Config or XSConfig values =head1 VERSION Version 0.02 =cut our $VERSION = '0.03'; =head1 SYNOPSIS XSConfig is readonly, so workaround that. use Mock::Config d_fork => 0, perl_patchlevel => ''; The importer works only dynamically, not lexically yet. use Mock::Config; Mock::Config->import(startperl => ''); print $Config{startperl}, ' mocked to empty'; Mock::Config->unimport; =head1 SUBROUTINES =head2 import Set pair of Config values, even for the readonly XSConfig implementation, as used in cperl. It does not store the mocked overrides lexically, just dynamically. =cut sub _set { my ($key, $val) = @_; # string context only? if (!exists $MockConfig{$key} or $MockConfig{$key} ne $val) { if (exists &Config::KEYS) { # compiled XSConfig $MockConfig{$key} = $val; # cache new value } else { $MockConfig{$key} = tied(%Config::Config)->{$key}; # store the old value tied(%Config::Config)->{$key} = $val; # set uncompiled Config } } } sub import { my $class = shift; if (exists &Config::KEYS) { # compiled XSConfig # initialize the mocker if (!exists &Config_FETCHorig) { *Config_FETCHorig = \&Config::FETCH; no warnings 'redefine'; *Config::FETCH = sub { if ($_[0] and exists $MockConfig{$_[1]}) { return $MockConfig{$_[1]}; } else { return Config_FETCHorig(@_); } } } } _set(shift, shift) while @_; } =head2 unimport This is unstacked and not lexical. It undoes all imported Config values at once. =cut sub unimport { my $class = shift; if (!exists &Config::KEYS) { for (keys %MockConfig) { tied(%Config::Config)->{$_} = $MockConfig{$_}; } } %MockConfig = (); } =head1 AUTHOR Reini Urban, C<< <rurban at cpan.org> >> =head1 BUGS Please report any bugs or feature requests at L<https://github.com/perl11/Mock-Config/issues>. We will be notified, and then you'll automatically be notified of progress on your request as we make changes. =head1 SUPPORT You can find documentation for this module with the perldoc command. perldoc Mock::Config You can also look for information at: =over 4 =item * RT: CPAN's request tracker (report bugs here) L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mock-Config> =item * AnnoCPAN: Annotated CPAN documentation L<http://annocpan.org/dist/Mock-Config> =item * CPAN Ratings L<http://cpanratings.perl.org/d/Mock-Config> =item * Search CPAN L<http://search.cpan.org/dist/Mock-Config/> =back =head1 ACKNOWLEDGEMENTS =head1 LICENSE AND COPYRIGHT Copyright 2016 cPanel Inc. This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: L<http://www.perlfoundation.org/artistic_license_2_0> Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license. If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license. This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed. Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. =cut 1; # End of Mock::Config PK � �[ lib/auto/Mock/Config/.existsnu �[��� PK � �[BM�;� � % man3/JSON::backportPP::Compat5005.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "JSON::backportPP::Compat5005 3" .TH JSON::backportPP::Compat5005 3 "2021-01-17" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::PP5005 \- Helper module in using JSON::PP in Perl 5.005 .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1JSON::PP\s0 calls internally. .SH "AUTHOR" .IX Header "AUTHOR" Makamaka Hannyaharamitu, <makamaka[at]cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2007\-2012 by Makamaka Hannyaharamitu .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[cm}��� �� man3/JSON.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "JSON 3" .TH JSON 3 "2022-10-09" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON \- JSON (JavaScript Object Notation) encoder/decoder .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use JSON; # imports encode_json, decode_json, to_json and from_json. \& \& # simple and fast interfaces (expect/generate UTF\-8) \& \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; \& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; \& \& # OO\-interface \& \& $json = JSON\->new\->allow_nonref; \& \& $json_text = $json\->encode( $perl_scalar ); \& $perl_scalar = $json\->decode( $json_text ); \& \& $pretty_printed = $json\->pretty\->encode( $perl_scalar ); # pretty\-printing .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is a thin wrapper for \s-1JSON::XS\s0\-compatible modules with a few additional features. All the backend modules convert a Perl data structure to a \s-1JSON\s0 text and vice versa. This module uses \s-1JSON::XS\s0 by default, and when \s-1JSON::XS\s0 is not available, falls back on \s-1JSON::PP\s0, which is in the Perl core since 5.14. If \s-1JSON::PP\s0 is not available either, this module then falls back on JSON::backportPP (which is actually \s-1JSON::PP\s0 in a different .pm file) bundled in the same distribution as this module. You can also explicitly specify to use Cpanel::JSON::XS, a fork of \&\s-1JSON::XS\s0 by Reini Urban. .PP All these backend modules have slight incompatibilities between them, including extra features that other modules don't support, but as long as you use only common features (most important ones are described below), migration from backend to backend should be reasonably easy. For details, see each backend module you use. .SH "CHOOSING BACKEND" .IX Header "CHOOSING BACKEND" This module respects an environmental variable called \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR when it decides a backend module to use. If this environmental variable is not set, it tries to load \s-1JSON::XS,\s0 and if \s-1JSON::XS\s0 is not available, it falls back on \s-1JSON::PP,\s0 and then JSON::backportPP if \s-1JSON::PP\s0 is not available either. .PP If you always don't want it to fall back on pure perl modules, set the variable like this (\f(CW\*(C`export\*(C'\fR may be \f(CW\*(C`setenv\*(C'\fR, \f(CW\*(C`set\*(C'\fR and the likes, depending on your environment): .PP .Vb 1 \& > export PERL_JSON_BACKEND=JSON::XS .Ve .PP If you prefer Cpanel::JSON::XS to \s-1JSON::XS,\s0 then: .PP .Vb 1 \& > export PERL_JSON_BACKEND=Cpanel::JSON::XS,JSON::XS,JSON::PP .Ve .PP You may also want to set this variable at the top of your test files, in order not to be bothered with incompatibilities between backends (you need to wrap this in \f(CW\*(C`BEGIN\*(C'\fR, and set before actually \f(CW\*(C`use\*(C'\fR\-ing \s-1JSON\s0 module, as it decides its backend as soon as it's loaded): .PP .Vb 2 \& BEGIN { $ENV{PERL_JSON_BACKEND}=\*(AqJSON::backportPP\*(Aq; } \& use JSON; .Ve .SH "USING OPTIONAL FEATURES" .IX Header "USING OPTIONAL FEATURES" There are a few options you can set when you \f(CW\*(C`use\*(C'\fR this module. These historical options are only kept for backward compatibility, and should not be used in a new application. .IP "\-support_by_pp" 4 .IX Item "-support_by_pp" .Vb 1 \& BEGIN { $ENV{PERL_JSON_BACKEND} = \*(AqJSON::XS\*(Aq } \& \& use JSON \-support_by_pp; \& \& my $json = JSON\->new; \& # escape_slash is for JSON::PP only. \& $json\->allow_nonref\->escape_slash\->encode("/"); .Ve .Sp With this option, this module loads its pure perl backend along with its \s-1XS\s0 backend (if available), and lets the \s-1XS\s0 backend to watch if you set a flag only \s-1JSON::PP\s0 supports. When you do, the internal \s-1JSON::XS\s0 object is replaced with a newly created \s-1JSON::PP\s0 object with the setting copied from the \s-1XS\s0 object, so that you can use \s-1JSON::PP\s0 flags (and its slower \&\f(CW\*(C`decode\*(C'\fR/\f(CW\*(C`encode\*(C'\fR methods) from then on. In other words, this is not something that allows you to hook \s-1JSON::XS\s0 to change its behavior while keeping its speed. \s-1JSON::XS\s0 and \s-1JSON::PP\s0 objects are quite different (\s-1JSON::XS\s0 object is a blessed scalar reference, while \s-1JSON::PP\s0 object is a blessed hash reference), and can't share their internals. .Sp To avoid needless overhead (by copying settings), you are advised not to use this option and just to use \s-1JSON::PP\s0 explicitly when you need \&\s-1JSON::PP\s0 features. .IP "\-convert_blessed_universally" 4 .IX Item "-convert_blessed_universally" .Vb 1 \& use JSON \-convert_blessed_universally; \& \& my $json = JSON\->new\->allow_nonref\->convert_blessed; \& my $object = bless {foo => \*(Aqbar\*(Aq}, \*(AqFoo\*(Aq; \& $json\->encode($object); # => {"foo":"bar"} .Ve .Sp JSON::XS\-compatible backend modules don't encode blessed objects by default (except for their boolean values, which are typically blessed JSON::PP::Boolean objects). If you need to encode a data structure that may contain objects, you usually need to look into the structure and replace objects with alternative non-blessed values, or enable \&\f(CW\*(C`convert_blessed\*(C'\fR and provide a \f(CW\*(C`TO_JSON\*(C'\fR method for each object's (base) class that may be found in the structure, in order to let the methods replace the objects with whatever scalar values the methods return. .Sp If you need to serialise data structures that may contain arbitrary objects, it's probably better to use other serialisers (such as Sereal or Storable for example), but if you do want to use this module for that purpose, \f(CW\*(C`\-convert_blessed_universally\*(C'\fR option may help, which tweaks \f(CW\*(C`encode\*(C'\fR method of the backend to install \&\f(CW\*(C`UNIVERSAL::TO_JSON\*(C'\fR method (locally) before encoding, so that all the objects that don't have their own \f(CW\*(C`TO_JSON\*(C'\fR method can fall back on the method in the \f(CW\*(C`UNIVERSAL\*(C'\fR namespace. Note that you still need to enable \f(CW\*(C`convert_blessed\*(C'\fR flag to actually encode objects in a data structure, and \f(CW\*(C`UNIVERSAL::TO_JSON\*(C'\fR method installed by this option only converts blessed hash/array references into their unblessed clone (including private keys/values that are not supposed to be exposed). Other blessed references will be converted into null. .Sp This feature is experimental and may be removed in the future. .IP "\-no_export" 4 .IX Item "-no_export" When you don't want to import functional interfaces from a module, you usually supply \f(CW\*(C`()\*(C'\fR to its \f(CW\*(C`use\*(C'\fR statement. .Sp .Vb 1 \& use JSON (); # no functional interfaces .Ve .Sp If you don't want to import functional interfaces, but you also want to use any of the above options, add \f(CW\*(C`\-no_export\*(C'\fR to the option list. .Sp .Vb 2 \& # no functional interfaces, while JSON::PP support is enabled. \& use JSON \-support_by_pp, \-no_export; .Ve .SH "FUNCTIONAL INTERFACE" .IX Header "FUNCTIONAL INTERFACE" This section is taken from \s-1JSON::XS.\s0 \f(CW\*(C`encode_json\*(C'\fR and \f(CW\*(C`decode_json\*(C'\fR are exported by default. .PP This module also exports \f(CW\*(C`to_json\*(C'\fR and \f(CW\*(C`from_json\*(C'\fR for backward compatibility. These are slower, and may expect/generate different stuff from what \f(CW\*(C`encode_json\*(C'\fR and \f(CW\*(C`decode_json\*(C'\fR do, depending on their options. It's better just to use Object-Oriented interfaces than using these two functions. .SS "encode_json" .IX Subsection "encode_json" .Vb 1 \& $json_text = encode_json $perl_scalar .Ve .PP Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string (that is, the string contains octets only). Croaks on error. .PP This function call is functionally identical to: .PP .Vb 1 \& $json_text = JSON\->new\->utf8\->encode($perl_scalar) .Ve .PP Except being faster. .SS "decode_json" .IX Subsection "decode_json" .Vb 1 \& $perl_scalar = decode_json $json_text .Ve .PP The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an \s-1UTF\-8\s0 (binary) string and tries to parse that as an \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the resulting reference. Croaks on error. .PP This function call is functionally identical to: .PP .Vb 1 \& $perl_scalar = JSON\->new\->utf8\->decode($json_text) .Ve .PP Except being faster. .SS "to_json" .IX Subsection "to_json" .Vb 1 \& $json_text = to_json($perl_scalar[, $optional_hashref]) .Ve .PP Converts the given Perl data structure to a Unicode string by default. Croaks on error. .PP Basically, this function call is functionally identical to: .PP .Vb 1 \& $json_text = JSON\->new\->encode($perl_scalar) .Ve .PP Except being slower. .PP You can pass an optional hash reference to modify its behavior, but that may change what \f(CW\*(C`to_json\*(C'\fR expects/generates (see \&\f(CW\*(C`ENCODING/CODESET FLAG NOTES\*(C'\fR for details). .PP .Vb 2 \& $json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1}) \& # => JSON\->new\->utf8(1)\->pretty(1)\->encode($perl_scalar) .Ve .SS "from_json" .IX Subsection "from_json" .Vb 1 \& $perl_scalar = from_json($json_text[, $optional_hashref]) .Ve .PP The opposite of \f(CW\*(C`to_json\*(C'\fR: expects a Unicode string and tries to parse it, returning the resulting reference. Croaks on error. .PP Basically, this function call is functionally identical to: .PP .Vb 1 \& $perl_scalar = JSON\->new\->decode($json_text) .Ve .PP You can pass an optional hash reference to modify its behavior, but that may change what \f(CW\*(C`from_json\*(C'\fR expects/generates (see \&\f(CW\*(C`ENCODING/CODESET FLAG NOTES\*(C'\fR for details). .PP .Vb 2 \& $perl_scalar = from_json($json_text, {utf8 => 1}) \& # => JSON\->new\->utf8(1)\->decode($json_text) .Ve .SS "JSON::is_bool" .IX Subsection "JSON::is_bool" .Vb 1 \& $is_boolean = JSON::is_bool($scalar) .Ve .PP Returns true if the passed scalar represents either JSON::true or JSON::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively and are also used to represent \s-1JSON\s0 \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings. .PP See \s-1MAPPING\s0, below, for more information on how \s-1JSON\s0 values are mapped to Perl. .SH "COMMON OBJECT-ORIENTED INTERFACE" .IX Header "COMMON OBJECT-ORIENTED INTERFACE" This section is also taken from \s-1JSON::XS.\s0 .PP The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. .SS "new" .IX Subsection "new" .Vb 1 \& $json = JSON\->new .Ve .PP Creates a new JSON::XS\-compatible backend object that can be used to de/encode \s-1JSON\s0 strings. All boolean flags described below are by default \fIdisabled\fR (with the exception of \f(CW\*(C`allow_nonref\*(C'\fR, which defaults to \fIenabled\fR since version \f(CW4.0\fR). .PP The mutators for flags all return the backend object again and thus calls can be chained: .PP .Vb 2 \& my $json = JSON\->new\->utf8\->space_after\->encode({a => [1,2]}) \& => {"a": [1, 2]} .Ve .SS "ascii" .IX Subsection "ascii" .Vb 1 \& $json = $json\->ascii([$enable]) \& \& $enabled = $json\->get_ascii .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not generate characters outside the code range \f(CW0..127\fR (which is \s-1ASCII\s0). Any Unicode characters outside that range will be escaped using either a single \euXXXX (\s-1BMP\s0 characters) or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627.\s0 The resulting encoded \s-1JSON\s0 text can be treated as a native Unicode string, an ascii-encoded, latin1\-encoded or \s-1UTF\-8\s0 encoded string, or any other superset of \s-1ASCII.\s0 .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode characters unless required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format. .PP See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .PP The main use for this flag is to produce \s-1JSON\s0 texts that can be transmitted over a 7\-bit channel, as the encoded \s-1JSON\s0 texts will not contain any 8 bit characters. .PP .Vb 2 \& JSON\->new\->ascii(1)\->encode([chr 0x10401]) \& => ["\eud801\eudc01"] .Ve .SS "latin1" .IX Subsection "latin1" .Vb 1 \& $json = $json\->latin1([$enable]) \& \& $enabled = $json\->get_latin1 .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode the resulting \s-1JSON\s0 text as latin1 (or iso\-8859\-1), escaping any characters outside the code range \f(CW0..255\fR. The resulting string can be treated as a latin1\-encoded \s-1JSON\s0 text or a native Unicode string. The \f(CW\*(C`decode\*(C'\fR method will not be affected in any way by this flag, as \f(CW\*(C`decode\*(C'\fR by default expects Unicode, which is a strict superset of latin1. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode characters unless required by the \s-1JSON\s0 syntax or other flags. .PP See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .PP The main use for this flag is efficiently encoding binary data as \s-1JSON\s0 text, as most octets will not be escaped, resulting in a smaller encoded size. The disadvantage is that the resulting \s-1JSON\s0 text is encoded in latin1 (and must correctly be treated as such when storing and transferring), a rare encoding for \s-1JSON.\s0 It is therefore most useful when you want to store data structures known to contain binary data efficiently in files or databases, not when talking to other \s-1JSON\s0 encoders/decoders. .PP .Vb 2 \& JSON\->new\->latin1\->encode (["\ex{89}\ex{abc}"] \& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) .Ve .SS "utf8" .IX Subsection "utf8" .Vb 1 \& $json = $json\->utf8([$enable]) \& \& $enabled = $json\->get_utf8 .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode the \s-1JSON\s0 result into \s-1UTF\-8,\s0 as required by many protocols, while the \&\f(CW\*(C`decode\*(C'\fR method expects to be handled an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not contain any characters outside the range \f(CW0..255\fR, they are thus useful for bytewise/binary I/O. In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0 encoding families, as described in \s-1RFC4627.\s0 .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will return the \s-1JSON\s0 string as a (non-encoded) Unicode string, while \f(CW\*(C`decode\*(C'\fR expects thus a Unicode string. Any decoding or encoding (e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module. .PP See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .PP Example, output UTF\-16BE\-encoded \s-1JSON:\s0 .PP .Vb 2 \& use Encode; \& $jsontext = encode "UTF\-16BE", JSON\->new\->encode ($object); .Ve .PP Example, decode UTF\-32LE\-encoded \s-1JSON:\s0 .PP .Vb 2 \& use Encode; \& $object = JSON\->new\->decode (decode "UTF\-32LE", $jsontext); .Ve .SS "pretty" .IX Subsection "pretty" .Vb 1 \& $json = $json\->pretty([$enable]) .Ve .PP This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and \&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to generate the most readable (or most compact) form possible. .SS "indent" .IX Subsection "indent" .Vb 1 \& $json = $json\->indent([$enable]) \& \& $enabled = $json\->get_indent .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, indenting them properly. .PP If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the resulting \s-1JSON\s0 text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR. .PP This setting has no effect when decoding \s-1JSON\s0 texts. .SS "space_before" .IX Subsection "space_before" .Vb 1 \& $json = $json\->space_before([$enable]) \& \& $enabled = $json\->get_space_before .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra space at those places. .PP This setting has no effect when decoding \s-1JSON\s0 texts. You will also most likely combine this setting with \f(CW\*(C`space_after\*(C'\fR. .PP Example, space_before enabled, space_after and indent disabled: .PP .Vb 1 \& {"key" :"value"} .Ve .SS "space_after" .IX Subsection "space_after" .Vb 1 \& $json = $json\->space_after([$enable]) \& \& $enabled = $json\->get_space_after .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array members. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra space at those places. .PP This setting has no effect when decoding \s-1JSON\s0 texts. .PP Example, space_before and indent disabled, space_after enabled: .PP .Vb 1 \& {"key": "value"} .Ve .SS "relaxed" .IX Subsection "relaxed" .Vb 1 \& $json = $json\->relaxed([$enable]) \& \& $enabled = $json\->get_relaxed .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be affected in any way. \fIBe aware that this option makes you accept invalid \&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept valid \s-1JSON\s0 texts. .PP Currently accepted extensions are: .IP "\(bu" 4 list items can have an end-comma .Sp \&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. This can be annoying if you write \s-1JSON\s0 texts manually and want to be able to quickly append elements, so this extension accepts comma at the end of such items not just between them: .Sp .Vb 8 \& [ \& 1, \& 2, <\- this comma not normally allowed \& ] \& { \& "k1": "v1", \& "k2": "v2", <\- this comma not normally allowed \& } .Ve .IP "\(bu" 4 shell-style '#'\-comments .Sp Whenever \s-1JSON\s0 allows whitespace, shell-style comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. .Sp .Vb 4 \& [ \& 1, # this comment not allowed in JSON \& # neither this one... \& ] .Ve .SS "canonical" .IX Subsection "canonical" .Vb 1 \& $json = $json\->canonical([$enable]) \& \& $enabled = $json\->get_canonical .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output \s-1JSON\s0 objects by sorting their keys. This is adding a comparatively high overhead. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value pairs in the order Perl stores them (which will likely change between runs of the same script, and can change even within the same run from 5.18 onwards). .PP This option is useful if you want the same data structure to be encoded as the same \s-1JSON\s0 text (given the same overall settings). If it is disabled, the same hash might be encoded differently even if contains the same data, as key-value pairs have no inherent ordering in Perl. .PP This setting has no effect when decoding \s-1JSON\s0 texts. .PP This setting has currently no effect on tied hashes. .SS "allow_nonref" .IX Subsection "allow_nonref" .Vb 1 \& $json = $json\->allow_nonref([$enable]) \& \& $enabled = $json\->get_allow_nonref .Ve .PP Unlike other boolean options, this option is enabled by default beginning with version \f(CW4.0\fR. .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a non-reference into its corresponding string, number or null \s-1JSON\s0 value, which is an extension to \s-1RFC4627.\s0 Likewise, \f(CW\*(C`decode\*(C'\fR will accept those \s-1JSON\s0 values instead of croaking. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a \&\s-1JSON\s0 object or array. .PP Example, encode a Perl scalar as \s-1JSON\s0 value with enabled \f(CW\*(C`allow_nonref\*(C'\fR, resulting in an invalid \s-1JSON\s0 text: .PP .Vb 2 \& JSON\->new\->allow_nonref\->encode ("Hello, World!") \& => "Hello, World!" .Ve .SS "allow_unknown" .IX Subsection "allow_unknown" .Vb 1 \& $json = $json\->allow_unknown ([$enable]) \& \& $enabled = $json\->get_allow_unknown .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will \fInot\fR throw an exception when it encounters values it cannot represent in \s-1JSON\s0 (for example, filehandles) but instead will encode a \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value. Note that blessed objects are not included here and are handled separately by c<allow_blessed>. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an exception when it encounters anything it cannot encode as \s-1JSON.\s0 .PP This option does not affect \f(CW\*(C`decode\*(C'\fR in any way, and it is recommended to leave it off unless you know your communications partner. .SS "allow_blessed" .IX Subsection "allow_blessed" .Vb 1 \& $json = $json\->allow_blessed([$enable]) \& \& $enabled = $json\->get_allow_blessed .Ve .PP See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not barf when it encounters a blessed reference that it cannot convert otherwise. Instead, a \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value is encoded instead of the object. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an exception when it encounters a blessed object that it cannot convert otherwise. .PP This setting has no effect on \f(CW\*(C`decode\*(C'\fR. .SS "convert_blessed" .IX Subsection "convert_blessed" .Vb 1 \& $json = $json\->convert_blessed([$enable]) \& \& $enabled = $json\->get_convert_blessed .Ve .PP See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method on the object's class. If found, it will be called in scalar context and the resulting scalar will be encoded instead of the object. .PP The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR returns other blessed objects, those will be handled in the same way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other methods called by the Perl core (== not by the user of the object) are usually in upper case letters and to avoid collisions with any \f(CW\*(C`to_json\*(C'\fR function or method. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider this type of conversion. .PP This setting has no effect on \f(CW\*(C`decode\*(C'\fR. .SS "allow_tags (since version 3.0)" .IX Subsection "allow_tags (since version 3.0)" .Vb 1 \& $json = $json\->allow_tags([$enable]) \& \& $enabled = $json\->get_allow_tags .Ve .PP See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a blessed object, will check for the availability of the \f(CW\*(C`FREEZE\*(C'\fR method on the object's class. If found, it will be used to serialise the object into a nonstandard tagged \s-1JSON\s0 value (that \s-1JSON\s0 decoders cannot decode). .PP It also causes \f(CW\*(C`decode\*(C'\fR to parse such tagged \s-1JSON\s0 values and deserialise them via a call to the \f(CW\*(C`THAW\*(C'\fR method. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider this type of conversion, and tagged \s-1JSON\s0 values will cause a parse error in \f(CW\*(C`decode\*(C'\fR, as if tags were not part of the grammar. .SS "boolean_values (since version 4.0)" .IX Subsection "boolean_values (since version 4.0)" .Vb 1 \& $json\->boolean_values([$false, $true]) \& \& ($false, $true) = $json\->get_boolean_values .Ve .PP By default, \s-1JSON\s0 booleans will be decoded as overloaded \&\f(CW$JSON::false\fR and \f(CW$JSON::true\fR objects. .PP With this method you can specify your own boolean values for decoding \- on decode, \s-1JSON\s0 \f(CW\*(C`false\*(C'\fR will be decoded as a copy of \f(CW$false\fR, and \s-1JSON\s0 \&\f(CW\*(C`true\*(C'\fR will be decoded as \f(CW$true\fR (\*(L"copy\*(R" here is the same thing as assigning a value to another variable, i.e. \f(CW\*(C`$copy = $false\*(C'\fR). .PP This is useful when you want to pass a decoded data structure directly to other serialisers like \s-1YAML,\s0 Data::MessagePack and so on. .PP Note that this works only when you \f(CW\*(C`decode\*(C'\fR. You can set incompatible boolean objects (like boolean), but when you \f(CW\*(C`encode\*(C'\fR a data structure with such boolean objects, you still need to enable \f(CW\*(C`convert_blessed\*(C'\fR (and add a \f(CW\*(C`TO_JSON\*(C'\fR method if necessary). .PP Calling this method without any arguments will reset the booleans to their default values. .PP \&\f(CW\*(C`get_boolean_values\*(C'\fR will return both \f(CW$false\fR and \f(CW$true\fR values, or the empty list when they are set to the default. .SS "filter_json_object" .IX Subsection "filter_json_object" .Vb 1 \& $json = $json\->filter_json_object([$coderef]) .Ve .PP When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each time it decodes a \s-1JSON\s0 object. The only argument is a reference to the newly-created hash. If the code references returns a single scalar (which need not be a reference), this value (or rather a copy of it) is inserted into the deserialised data structure. If it returns an empty list (\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original deserialised hash will be inserted. This setting can slow down decoding considerably. .PP When \f(CW$coderef\fR is omitted or undefined, any existing callback will be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any way. .PP Example, convert all \s-1JSON\s0 objects into the integer 5: .PP .Vb 5 \& my $js = JSON\->new\->filter_json_object(sub { 5 }); \& # returns [5] \& $js\->decode(\*(Aq[{}]\*(Aq); \& # returns 5 \& $js\->decode(\*(Aq{"a":1, "b":2}\*(Aq); .Ve .SS "filter_json_single_key_object" .IX Subsection "filter_json_single_key_object" .Vb 1 \& $json = $json\->filter_json_single_key_object($key [=> $coderef]) .Ve .PP Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for \&\s-1JSON\s0 objects having a single key named \f(CW$key\fR. .PP This \f(CW$coderef\fR is called before the one specified via \&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the \s-1JSON\s0 object. If it returns a single value, it will be inserted into the data structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list), the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no single-key callback were specified. .PP If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be disabled. There can only ever be one callback for a given key. .PP As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR one, decoding speed will not usually suffer as much. Therefore, single-key objects make excellent targets to serialise Perl objects into, especially as single-key \s-1JSON\s0 objects are as close to the type-tagged value concept as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JSON\s0 does not support this in any way, so you need to make sure your data never looks like a serialised Perl hash. .PP Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or \&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing with real hashes. .PP Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR into the corresponding \f(CW$WIDGET{<id>}\fR object: .PP .Vb 7 \& # return whatever is in $WIDGET{5}: \& JSON \& \->new \& \->filter_json_single_key_object (_\|_widget_\|_ => sub { \& $WIDGET{ $_[0] } \& }) \& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq) \& \& # this can be used with a TO_JSON method in some "widget" class \& # for serialisation to json: \& sub WidgetBase::TO_JSON { \& my ($self) = @_; \& \& unless ($self\->{id}) { \& $self\->{id} = ..get..some..id..; \& $WIDGET{$self\->{id}} = $self; \& } \& \& { _\|_widget_\|_ => $self\->{id} } \& } .Ve .SS "max_depth" .IX Subsection "max_depth" .Vb 1 \& $json = $json\->max_depth([$maximum_nesting_depth]) \& \& $max_depth = $json\->get_max_depth .Ve .PP Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl data structure, then the encoder and decoder will stop and croak at that point. .PP Nesting level is defined by number of hash\- or arrayrefs that the encoder needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR characters without their matching closing parenthesis crossed to reach a given character in a string. .PP Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. .PP If no argument is given, the highest possible setting will be used, which is rarely useful. .PP See \*(L"\s-1SECURITY CONSIDERATIONS\*(R"\s0 in \s-1JSON::XS\s0 for more info on why this is useful. .SS "max_size" .IX Subsection "max_size" .Vb 1 \& $json = $json\->max_size([$maximum_string_size]) \& \& $max_size = $json\->get_max_size .Ve .PP Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR is called on a string that is longer then this many bytes, it will not attempt to decode the string but throw an exception. This setting has no effect on \f(CW\*(C`encode\*(C'\fR (yet). .PP If no argument is given, the limit check will be deactivated (same as when \&\f(CW0\fR is specified). .PP See \*(L"\s-1SECURITY CONSIDERATIONS\*(R"\s0 in \s-1JSON::XS\s0 for more info on why this is useful. .SS "encode" .IX Subsection "encode" .Vb 1 \& $json_text = $json\->encode($perl_scalar) .Ve .PP Converts the given Perl value or data structure to its \s-1JSON\s0 representation. Croaks on error. .SS "decode" .IX Subsection "decode" .Vb 1 \& $perl_scalar = $json\->decode($json_text) .Ve .PP The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries to parse it, returning the resulting simple scalar or reference. Croaks on error. .SS "decode_prefix" .IX Subsection "decode_prefix" .Vb 1 \& ($perl_scalar, $characters) = $json\->decode_prefix($json_text) .Ve .PP This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception when there is trailing garbage after the first \s-1JSON\s0 object, it will silently stop parsing there and return the number of characters consumed so far. .PP This is useful if your \s-1JSON\s0 texts are not delimited by an outer protocol and you need to know where the \s-1JSON\s0 text ends. .PP .Vb 2 \& JSON\->new\->decode_prefix ("[1] the tail") \& => ([1], 3) .Ve .SH "ADDITIONAL METHODS" .IX Header "ADDITIONAL METHODS" The following methods are for this module only. .SS "backend" .IX Subsection "backend" .Vb 1 \& $backend = $json\->backend .Ve .PP Since 2.92, \f(CW\*(C`backend\*(C'\fR method returns an abstract backend module used currently, which should be JSON::Backend::XS (which inherits \s-1JSON::XS\s0 or Cpanel::JSON::XS), or JSON::Backend::PP (which inherits \s-1JSON::PP\s0), not to monkey-patch the actual backend module globally. .PP If you need to know what is used actually, use \f(CW\*(C`isa\*(C'\fR, instead of string comparison. .SS "is_xs" .IX Subsection "is_xs" .Vb 1 \& $boolean = $json\->is_xs .Ve .PP Returns true if the backend inherits \s-1JSON::XS\s0 or Cpanel::JSON::XS. .SS "is_pp" .IX Subsection "is_pp" .Vb 1 \& $boolean = $json\->is_pp .Ve .PP Returns true if the backend inherits \s-1JSON::PP.\s0 .SS "property" .IX Subsection "property" .Vb 1 \& $settings = $json\->property() .Ve .PP Returns a reference to a hash that holds all the common flag settings. .PP .Vb 2 \& $json = $json\->property(\*(Aqutf8\*(Aq => 1) \& $value = $json\->property(\*(Aqutf8\*(Aq) # 1 .Ve .PP You can use this to get/set a value of a particular flag. .SS "boolean" .IX Subsection "boolean" .Vb 1 \& $boolean_object = JSON\->boolean($scalar) .Ve .PP Returns \f(CW$JSON::true\fR if \f(CW$scalar\fR contains a true value, \f(CW$JSON::false\fR otherwise. You can use this as a full-qualified function (\f(CW\*(C`JSON::boolean($scalar)\*(C'\fR). .SH "INCREMENTAL PARSING" .IX Header "INCREMENTAL PARSING" This section is also taken from \s-1JSON::XS.\s0 .PP In some cases, there is the need for incremental parsing of \s-1JSON\s0 texts. While this module always has to keep both \s-1JSON\s0 text and resulting Perl data structure in memory at one time, it does allow you to parse a \&\s-1JSON\s0 stream incrementally. It does so by accumulating text until it has a full \s-1JSON\s0 object, which it then can decode. This process is similar to using \f(CW\*(C`decode_prefix\*(C'\fR to see if a full \s-1JSON\s0 object is available, but is much more efficient (and can be implemented with a minimum of method calls). .PP This module will only attempt to parse the \s-1JSON\s0 text once it is sure it has enough text to get a decisive result, using a very simple but truly incremental parser. This means that it sometimes won't stop as early as the full parser, for example, it doesn't detect mismatched parentheses. The only thing it guarantees is that it starts decoding as soon as a syntactically valid \s-1JSON\s0 text has been seen. This means you need to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop parsing in the presence if syntax errors. .PP The following methods implement this incremental parser. .SS "incr_parse" .IX Subsection "incr_parse" .Vb 1 \& $json\->incr_parse( [$string] ) # void context \& \& $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context \& \& @obj_or_empty = $json\->incr_parse( [$string] ) # list context .Ve .PP This is the central parsing function. It can both append new text and extract objects from the stream accumulated so far (both of these functions are optional). .PP If \f(CW$string\fR is given, then this string is appended to the already existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object. .PP After that, if the function is called in void context, it will simply return without doing anything further. This can be used to add more text in as many chunks as you want. .PP If the method is called in scalar context, then it will try to extract exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error, this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use \&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of using the method. .PP And finally, in list context, it will try to extract as many objects from the stream as it can find and return them, or the empty list otherwise. For this to work, there must be no separators (other than whitespace) between the \s-1JSON\s0 objects or arrays, instead they must be concatenated back-to-back. If an error occurs, an exception will be raised as in the scalar context case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be lost. .PP Example: Parse some \s-1JSON\s0 arrays/objects in a given string and return them. .PP .Vb 1 \& my @objs = JSON\->new\->incr_parse ("[5][7][1,2]"); .Ve .SS "incr_text" .IX Subsection "incr_text" .Vb 1 \& $lvalue_string = $json\->incr_text .Ve .PP This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that is, you can manipulate it. This \fIonly\fR works when a preceding call to \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under all other circumstances you must not call this function (I mean it. although in simple tests it might actually work, it \fIwill\fR fail under real world conditions). As a special exception, you can also call this method before having parsed anything. .PP That means you can only use this function to look at or manipulate text before or after complete \s-1JSON\s0 objects, not while the parser is in the middle of parsing a \s-1JSON\s0 object. .PP This function is useful in two cases: a) finding the trailing text after a \&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text (such as commas). .SS "incr_skip" .IX Subsection "incr_skip" .Vb 1 \& $json\->incr_skip .Ve .PP This will reset the state of the incremental parser and will remove the parsed text from the input buffer so far. This is useful after \&\f(CW\*(C`incr_parse\*(C'\fR died, in which case the input buffer and incremental parser state is left unchanged, to skip the text parsed so far and to reset the parse state. .PP The difference to \f(CW\*(C`incr_reset\*(C'\fR is that only text until the parse error occurred is removed. .SS "incr_reset" .IX Subsection "incr_reset" .Vb 1 \& $json\->incr_reset .Ve .PP This completely resets the incremental parser, that is, after this call, it will be as if the parser had never parsed anything. .PP This is useful if you want to repeatedly parse \s-1JSON\s0 objects and want to ignore any trailing data, which means you have to reset the parser after each successful decode. .SH "MAPPING" .IX Header "MAPPING" Most of this section is also taken from \s-1JSON::XS.\s0 .PP This section describes how the backend modules map Perl values to \s-1JSON\s0 values and vice versa. These mappings are designed to \*(L"do the right thing\*(R" in most circumstances automatically, preserving round-tripping characteristics (what you put in comes out as something equivalent). .PP For the more enlightened: note that in the following descriptions, lowercase \fIperl\fR refers to the Perl interpreter, while uppercase \fIPerl\fR refers to the abstract Perl language itself. .SS "\s-1JSON\s0 \-> \s-1PERL\s0" .IX Subsection "JSON -> PERL" .IP "object" 4 .IX Item "object" A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of object keys is preserved (\s-1JSON\s0 does not preserver object key ordering itself). .IP "array" 4 .IX Item "array" A \s-1JSON\s0 array becomes a reference to an array in Perl. .IP "string" 4 .IX Item "string" A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s-1JSON\s0 are represented by the same codepoints in the Perl string, so no manual decoding is necessary. .IP "number" 4 .IX Item "number" A \s-1JSON\s0 number becomes either an integer, numeric (floating point) or string scalar in perl, depending on its range and any fractional parts. On the Perl level, there is no difference between those as Perl handles all the conversion details, but an integer may take slightly less memory and might represent more values exactly than floating point numbers. .Sp If the number consists of digits only, this module will try to represent it as an integer value. If that fails, it will try to represent it as a numeric (floating point) value if that is possible without loss of precision. Otherwise it will preserve the number as a string value (in which case you lose roundtripping ability, as the \s-1JSON\s0 number will be re-encoded to a \s-1JSON\s0 string). .Sp Numbers containing a fractional or exponential part will always be represented as numeric (floating point) values, possibly at a loss of precision (in which case you might lose perfect roundtripping ability, but the \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number). .Sp Note that precision is not accuracy \- binary floating point values cannot represent most decimal fractions exactly, and when converting from and to floating point, this module only guarantees precision up to but not including the least significant bit. .IP "true, false" 4 .IX Item "true, false" These \s-1JSON\s0 atoms become \f(CW\*(C`JSON::true\*(C'\fR and \f(CW\*(C`JSON::false\*(C'\fR, respectively. They are overloaded to act almost exactly like the numbers \&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a \s-1JSON\s0 boolean by using the \f(CW\*(C`JSON::is_bool\*(C'\fR function. .IP "null" 4 .IX Item "null" A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl. .ie n .IP "shell-style comments (""# \fItext\fP"")" 4 .el .IP "shell-style comments (\f(CW# \f(CItext\f(CW\fR)" 4 .IX Item "shell-style comments (# text)" As a nonstandard extension to the \s-1JSON\s0 syntax that is enabled by the \&\f(CW\*(C`relaxed\*(C'\fR setting, shell-style comments are allowed. They can start anywhere outside strings and go till the end of the line. .ie n .IP "tagged values (""(\fItag\fP)\fIvalue\fP"")." 4 .el .IP "tagged values (\f(CW(\f(CItag\f(CW)\f(CIvalue\f(CW\fR)." 4 .IX Item "tagged values ((tag)value)." Another nonstandard extension to the \s-1JSON\s0 syntax, enabled with the \&\f(CW\*(C`allow_tags\*(C'\fR setting, are tagged values. In this implementation, the \&\fItag\fR must be a perl package/class name encoded as a \s-1JSON\s0 string, and the \&\fIvalue\fR must be a \s-1JSON\s0 array encoding optional constructor arguments. .Sp See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0, below, for details. .SS "\s-1PERL\s0 \-> \s-1JSON\s0" .IX Subsection "PERL -> JSON" The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by a Perl value. .IP "hash references" 4 .IX Item "hash references" Perl hash references become \s-1JSON\s0 objects. As there is no inherent ordering in hash keys (or \s-1JSON\s0 objects), they will usually be encoded in a pseudo-random order. This module can optionally sort the hash keys (determined by the \fIcanonical\fR flag), so the same data structure will serialise to the same \s-1JSON\s0 text (given same settings and version of the same backend), but this incurs a runtime overhead and is only rarely useful, e.g. when you want to compare some \s-1JSON\s0 text against another for equality. .IP "array references" 4 .IX Item "array references" Perl array references become \s-1JSON\s0 arrays. .IP "other references" 4 .IX Item "other references" Other unblessed references are generally not allowed and will cause an exception to be thrown, except for references to the integers \f(CW0\fR and \&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in \s-1JSON.\s0 You can also use \f(CW\*(C`JSON::false\*(C'\fR and \f(CW\*(C`JSON::true\*(C'\fR to improve readability. .Sp .Vb 1 \& encode_json [\e0,JSON::true] # yields [false,true] .Ve .IP "JSON::true, JSON::false, JSON::null" 4 .IX Item "JSON::true, JSON::false, JSON::null" These special values become \s-1JSON\s0 true and \s-1JSON\s0 false values, respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want. .IP "blessed objects" 4 .IX Item "blessed objects" Blessed objects are not directly representable in \s-1JSON,\s0 but \f(CW\*(C`JSON::XS\*(C'\fR allows various ways of handling objects. See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0, below, for details. .IP "simple scalars" 4 .IX Item "simple scalars" Simple Perl scalars (any scalar that is not a reference) are the most difficult objects to encode: this module will encode undefined scalars as \&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context before encoding as \s-1JSON\s0 strings, and anything else as number value: .Sp .Vb 4 \& # dump as number \& encode_json [2] # yields [2] \& encode_json [\-3.0e17] # yields [\-3e+17] \& my $value = 5; encode_json [$value] # yields [5] \& \& # used as string, so dump as string \& print $value; \& encode_json [$value] # yields ["5"] \& \& # undef becomes null \& encode_json [undef] # yields [null] .Ve .Sp You can force the type to be a string by stringifying it: .Sp .Vb 4 \& my $x = 3.1; # some variable containing a number \& "$x"; # stringified \& $x .= ""; # another, more awkward way to stringify \& print $x; # perl does it for you, too, quite often .Ve .Sp You can force the type to be a number by numifying it: .Sp .Vb 3 \& my $x = "3"; # some variable containing a string \& $x += 0; # numify it, ensuring it will be dumped as a number \& $x *= 1; # same thing, the choice is yours. .Ve .Sp You can not currently force the type in other, less obscure, ways. Tell me if you need this capability (but don't forget to explain why it's needed :). .Sp Since version 2.91_01, \s-1JSON::PP\s0 uses a different number detection logic that converts a scalar that is possible to turn into a number safely. The new logic is slightly faster, and tends to help people who use older perl or who want to encode complicated data structure. However, this may results in a different \s-1JSON\s0 text from the one \s-1JSON::XS\s0 encodes (and thus may break tests that compare entire \s-1JSON\s0 texts). If you do need the previous behavior for better compatibility or for finer control, set \s-1PERL_JSON_PP_USE_B\s0 environmental variable to true before you \&\f(CW\*(C`use\*(C'\fR \s-1JSON.\s0 .Sp Note that numerical precision has the same meaning as under Perl (so binary to decimal conversion follows the same rules as in Perl, which can differ to other languages). Also, your perl interpreter might expose extensions to the floating point numbers of your platform, such as infinities or NaN's \- these cannot be represented in \s-1JSON,\s0 and it is an error to pass those in. .Sp \&\s-1JSON\s0.pm backend modules trust what you pass to \f(CW\*(C`encode\*(C'\fR method (or \f(CW\*(C`encode_json\*(C'\fR function) is a clean, validated data structure with values that can be represented as valid \s-1JSON\s0 values only, because it's not from an external data source (as opposed to \s-1JSON\s0 texts you pass to \&\f(CW\*(C`decode\*(C'\fR or \f(CW\*(C`decode_json\*(C'\fR, which \s-1JSON\s0 backends consider tainted and don't trust). As \s-1JSON\s0 backends don't know exactly what you and consumers of your \s-1JSON\s0 texts want the unexpected values to be (you may want to convert them into null, or to stringify them with or without normalisation (string representation of infinities/NaN may vary depending on platforms), or to croak without conversion), you're advised to do what you and your consumers need before you encode, and also not to numify values that may start with values that look like a number (including infinities/NaN), without validating. .SS "\s-1OBJECT SERIALISATION\s0" .IX Subsection "OBJECT SERIALISATION" As \s-1JSON\s0 cannot directly represent Perl objects, you have to choose between a pure \s-1JSON\s0 representation (without the ability to deserialise the object automatically again), and a nonstandard extension to the \s-1JSON\s0 syntax, tagged values. .PP \fI\s-1SERIALISATION\s0\fR .IX Subsection "SERIALISATION" .PP What happens when this module encounters a Perl object depends on the \&\f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR and \f(CW\*(C`allow_tags\*(C'\fR settings, which are used in this order: .ie n .IP "1. ""allow_tags"" is enabled and the object has a ""FREEZE"" method." 4 .el .IP "1. \f(CWallow_tags\fR is enabled and the object has a \f(CWFREEZE\fR method." 4 .IX Item "1. allow_tags is enabled and the object has a FREEZE method." In this case, \f(CW\*(C`JSON\*(C'\fR creates a tagged \s-1JSON\s0 value, using a nonstandard extension to the \s-1JSON\s0 syntax. .Sp This works by invoking the \f(CW\*(C`FREEZE\*(C'\fR method on the object, with the first argument being the object to serialise, and the second argument being the constant string \f(CW\*(C`JSON\*(C'\fR to distinguish it from other serialisers. .Sp The \f(CW\*(C`FREEZE\*(C'\fR method can return any number of values (i.e. zero or more). These values and the package/classname of the object will then be encoded as a tagged \s-1JSON\s0 value in the following format: .Sp .Vb 1 \& ("classname")[FREEZE return values...] .Ve .Sp e.g.: .Sp .Vb 3 \& ("URI")["http://www.google.com/"] \& ("MyDate")[2013,10,29] \& ("ImageData::JPEG")["Z3...VlCg=="] .Ve .Sp For example, the hypothetical \f(CW\*(C`My::Object\*(C'\fR \f(CW\*(C`FREEZE\*(C'\fR method might use the objects \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`id\*(C'\fR members to encode the object: .Sp .Vb 2 \& sub My::Object::FREEZE { \& my ($self, $serialiser) = @_; \& \& ($self\->{type}, $self\->{id}) \& } .Ve .ie n .IP "2. ""convert_blessed"" is enabled and the object has a ""TO_JSON"" method." 4 .el .IP "2. \f(CWconvert_blessed\fR is enabled and the object has a \f(CWTO_JSON\fR method." 4 .IX Item "2. convert_blessed is enabled and the object has a TO_JSON method." In this case, the \f(CW\*(C`TO_JSON\*(C'\fR method of the object is invoked in scalar context. It must return a single scalar that can be directly encoded into \&\s-1JSON.\s0 This scalar replaces the object in the \s-1JSON\s0 text. .Sp For example, the following \f(CW\*(C`TO_JSON\*(C'\fR method will convert all \s-1URI\s0 objects to \s-1JSON\s0 strings when serialised. The fact that these values originally were \s-1URI\s0 objects is lost. .Sp .Vb 4 \& sub URI::TO_JSON { \& my ($uri) = @_; \& $uri\->as_string \& } .Ve .ie n .IP "3. ""allow_blessed"" is enabled." 4 .el .IP "3. \f(CWallow_blessed\fR is enabled." 4 .IX Item "3. allow_blessed is enabled." The object will be serialised as a \s-1JSON\s0 null value. .IP "4. none of the above" 4 .IX Item "4. none of the above" If none of the settings are enabled or the respective methods are missing, this module throws an exception. .PP \fI\s-1DESERIALISATION\s0\fR .IX Subsection "DESERIALISATION" .PP For deserialisation there are only two cases to consider: either nonstandard tagging was used, in which case \f(CW\*(C`allow_tags\*(C'\fR decides, or objects cannot be automatically be deserialised, in which case you can use postprocessing or the \f(CW\*(C`filter_json_object\*(C'\fR or \&\f(CW\*(C`filter_json_single_key_object\*(C'\fR callbacks to get some real objects our of your \s-1JSON.\s0 .PP This section only considers the tagged value case: a tagged \s-1JSON\s0 object is encountered during decoding and \f(CW\*(C`allow_tags\*(C'\fR is disabled, a parse error will result (as if tagged values were not part of the grammar). .PP If \f(CW\*(C`allow_tags\*(C'\fR is enabled, this module will look up the \f(CW\*(C`THAW\*(C'\fR method of the package/classname used during serialisation (it will not attempt to load the package as a Perl module). If there is no such method, the decoding will fail with an error. .PP Otherwise, the \f(CW\*(C`THAW\*(C'\fR method is invoked with the classname as first argument, the constant string \f(CW\*(C`JSON\*(C'\fR as second argument, and all the values from the \s-1JSON\s0 array (the values originally returned by the \&\f(CW\*(C`FREEZE\*(C'\fR method) as remaining arguments. .PP The method must then return the object. While technically you can return any Perl scalar, you might have to enable the \f(CW\*(C`allow_nonref\*(C'\fR setting to make that work in all cases, so better return an actual blessed reference. .PP As an example, let's implement a \f(CW\*(C`THAW\*(C'\fR function that regenerates the \&\f(CW\*(C`My::Object\*(C'\fR from the \f(CW\*(C`FREEZE\*(C'\fR example earlier: .PP .Vb 2 \& sub My::Object::THAW { \& my ($class, $serialiser, $type, $id) = @_; \& \& $class\->new (type => $type, id => $id) \& } .Ve .SH "ENCODING/CODESET FLAG NOTES" .IX Header "ENCODING/CODESET FLAG NOTES" This section is taken from \s-1JSON::XS.\s0 .PP The interested reader might have seen a number of flags that signify encodings or codesets \- \f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR. There seems to be some confusion on what these do, so here is a short comparison: .PP \&\f(CW\*(C`utf8\*(C'\fR controls whether the \s-1JSON\s0 text created by \f(CW\*(C`encode\*(C'\fR (and expected by \f(CW\*(C`decode\*(C'\fR) is \s-1UTF\-8\s0 encoded or not, while \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR only control whether \f(CW\*(C`encode\*(C'\fR escapes character values outside their respective codeset range. Neither of these flags conflict with each other, although some combinations make less sense than others. .PP Care has been taken to make all flags symmetrical with respect to \&\f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR, that is, texts encoded with any combination of these flag values will be correctly decoded when the same flags are used \&\- in general, if you use different flag settings while encoding vs. when decoding you likely have a bug somewhere. .PP Below comes a verbose discussion of these flags. Note that a \*(L"codeset\*(R" is simply an abstract set of character-codepoint pairs, while an encoding takes those codepoint numbers and \fIencodes\fR them, in our case into octets. Unicode is (among other things) a codeset, \s-1UTF\-8\s0 is an encoding, and \s-1ISO\-8859\-1\s0 (= latin 1) and \s-1ASCII\s0 are both codesets \fIand\fR encodings at the same time, which can be confusing. .ie n .IP """utf8"" flag disabled" 4 .el .IP "\f(CWutf8\fR flag disabled" 4 .IX Item "utf8 flag disabled" When \f(CW\*(C`utf8\*(C'\fR is disabled (the default), then \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR generate and expect Unicode strings, that is, characters with high ordinal Unicode values (> 255) will be encoded as such characters, and likewise such characters are decoded as-is, no changes to them will be done, except \&\*(L"(re\-)interpreting\*(R" them as Unicode codepoints or Unicode characters, respectively (to Perl, these are the same thing in strings unless you do funny/weird/dumb stuff). .Sp This is useful when you want to do the encoding yourself (e.g. when you want to have \s-1UTF\-16\s0 encoded \s-1JSON\s0 texts) or when some other layer does the encoding for you (for example, when printing to a terminal using a filehandle that transparently encodes to \s-1UTF\-8\s0 you certainly do \s-1NOT\s0 want to \s-1UTF\-8\s0 encode your data first and have Perl encode it another time). .ie n .IP """utf8"" flag enabled" 4 .el .IP "\f(CWutf8\fR flag enabled" 4 .IX Item "utf8 flag enabled" If the \f(CW\*(C`utf8\*(C'\fR\-flag is enabled, \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR will encode all characters using the corresponding \s-1UTF\-8\s0 multi-byte sequence, and will expect your input strings to be encoded as \s-1UTF\-8,\s0 that is, no \*(L"character\*(R" of the input string must have any value > 255, as \s-1UTF\-8\s0 does not allow that. .Sp The \f(CW\*(C`utf8\*(C'\fR flag therefore switches between two modes: disabled means you will get a Unicode string in Perl, enabled means you get an \s-1UTF\-8\s0 encoded octet/binary string in Perl. .ie n .IP """latin1"" or ""ascii"" flags enabled" 4 .el .IP "\f(CWlatin1\fR or \f(CWascii\fR flags enabled" 4 .IX Item "latin1 or ascii flags enabled" With \f(CW\*(C`latin1\*(C'\fR (or \f(CW\*(C`ascii\*(C'\fR) enabled, \f(CW\*(C`encode\*(C'\fR will escape characters with ordinal values > 255 (> 127 with \f(CW\*(C`ascii\*(C'\fR) and encode the remaining characters as specified by the \f(CW\*(C`utf8\*(C'\fR flag. .Sp If \f(CW\*(C`utf8\*(C'\fR is disabled, then the result is also correctly encoded in those character sets (as both are proper subsets of Unicode, meaning that a Unicode string with all character values < 256 is the same thing as a \&\s-1ISO\-8859\-1\s0 string, and a Unicode string with all character values < 128 is the same thing as an \s-1ASCII\s0 string in Perl). .Sp If \f(CW\*(C`utf8\*(C'\fR is enabled, you still get a correct UTF\-8\-encoded string, regardless of these flags, just some more characters will be escaped using \&\f(CW\*(C`\euXXXX\*(C'\fR then before. .Sp Note that \s-1ISO\-8859\-1\-\s0\fIencoded\fR strings are not compatible with \s-1UTF\-8\s0 encoding, while ASCII-encoded strings are. That is because the \s-1ISO\-8859\-1\s0 encoding is \s-1NOT\s0 a subset of \s-1UTF\-8\s0 (despite the \s-1ISO\-8859\-1\s0 \fIcodeset\fR being a subset of Unicode), while \s-1ASCII\s0 is. .Sp Surprisingly, \f(CW\*(C`decode\*(C'\fR will ignore these flags and so treat all input values as governed by the \f(CW\*(C`utf8\*(C'\fR flag. If it is disabled, this allows you to decode \s-1ISO\-8859\-1\-\s0 and ASCII-encoded strings, as both strict subsets of Unicode. If it is enabled, you can correctly decode \s-1UTF\-8\s0 encoded strings. .Sp So neither \f(CW\*(C`latin1\*(C'\fR nor \f(CW\*(C`ascii\*(C'\fR are incompatible with the \f(CW\*(C`utf8\*(C'\fR flag \- they only govern when the \s-1JSON\s0 output engine escapes a character or not. .Sp The main use for \f(CW\*(C`latin1\*(C'\fR is to relatively efficiently store binary data as \s-1JSON,\s0 at the expense of breaking compatibility with most \s-1JSON\s0 decoders. .Sp The main use for \f(CW\*(C`ascii\*(C'\fR is to force the output to not contain characters with values > 127, which means you can interpret the resulting string as \s-1UTF\-8, ISO\-8859\-1, ASCII, KOI8\-R\s0 or most about any character set and 8\-bit\-encoding, and still get the same data structure back. This is useful when your channel for \s-1JSON\s0 transfer is not 8\-bit clean or the encoding might be mangled in between (e.g. in mail), and works because \s-1ASCII\s0 is a proper subset of most 8\-bit and multibyte encodings in use in the world. .SH "BACKWARD INCOMPATIBILITY" .IX Header "BACKWARD INCOMPATIBILITY" Since version 2.90, stringification (and string comparison) for \&\f(CW\*(C`JSON::true\*(C'\fR and \f(CW\*(C`JSON::false\*(C'\fR has not been overloaded. It shouldn't matter as long as you treat them as boolean values, but a code that expects they are stringified as \*(L"true\*(R" or \*(L"false\*(R" doesn't work as you have expected any more. .PP .Vb 1 \& if (JSON::true eq \*(Aqtrue\*(Aq) { # now fails \& \& print "The result is $JSON::true now."; # => The result is 1 now. .Ve .PP And now these boolean values don't inherit JSON::Boolean, either. When you need to test a value is a \s-1JSON\s0 boolean value or not, use \&\f(CW\*(C`JSON::is_bool\*(C'\fR function, instead of testing the value inherits a particular boolean class or not. .SH "BUGS" .IX Header "BUGS" Please report bugs on backend selection and additional features this module provides to \s-1RT\s0 or GitHub issues for this module: .PP <https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON> .PP <https://github.com/makamaka/JSON/issues> .PP As for bugs on a specific behavior, please report to the author of the backend module you are using. .PP As for new features and requests to change common behaviors, please ask the author of \s-1JSON::XS\s0 (Marc Lehmann, <schmorp[at]schmorp.de>) first, by email (important!), to keep compatibility among \s-1JSON\s0.pm backends. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1JSON::XS\s0, Cpanel::JSON::XS, \s-1JSON::PP\s0 for backends. .PP JSON::MaybeXS, an alternative that prefers Cpanel::JSON::XS. .PP \&\f(CW\*(C`RFC4627\*(C'\fR(<http://www.ietf.org/rfc/rfc4627.txt>) .PP \&\s-1RFC7159\s0 (<http://www.ietf.org/rfc/rfc7159.txt>) .PP \&\s-1RFC8259\s0 (<http://www.ietf.org/rfc/rfc8259.txt>) .SH "AUTHOR" .IX Header "AUTHOR" Makamaka Hannyaharamitu, <makamaka[at]cpan.org> .PP \&\s-1JSON::XS\s0 was written by Marc Lehmann <schmorp[at]schmorp.de> .PP The release of this new version owes to the courtesy of Marc Lehmann. .SH "CURRENT MAINTAINER" .IX Header "CURRENT MAINTAINER" Kenichi Ishigaki, <ishigaki[at]cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2005\-2013 by Makamaka Hannyaharamitu .PP Most of the documentation is taken from \s-1JSON::XS\s0 by Marc Lehmann .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[=�I h h man3/JSON::backportPP.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "JSON::backportPP 3" .TH JSON::backportPP 3 "2022-10-08" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::PP \- JSON::XS compatible pure\-Perl module. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use JSON::PP; \& \& # exported functions, they croak on error \& # and expect/generate UTF\-8 \& \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; \& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; \& \& # OO\-interface \& \& $json = JSON::PP\->new\->ascii\->pretty\->allow_nonref; \& \& $pretty_printed_json_text = $json\->encode( $perl_scalar ); \& $perl_scalar = $json\->decode( $json_text ); \& \& # Note that JSON version 2.0 and above will automatically use \& # JSON::XS or JSON::PP, so you should be able to just: \& \& use JSON; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1JSON::PP\s0 is a pure perl \s-1JSON\s0 decoder/encoder, and (almost) compatible to much faster \s-1JSON::XS\s0 written by Marc Lehmann in C. \s-1JSON::PP\s0 works as a fallback module when you use \s-1JSON\s0 module without having installed \s-1JSON::XS.\s0 .PP Because of this fallback feature of \s-1JSON\s0.pm, \s-1JSON::PP\s0 tries not to be more JavaScript-friendly than \s-1JSON::XS\s0 (i.e. not to escape extra characters such as U+2028 and U+2029, etc), in order for you not to lose such JavaScript-friendliness silently when you use \s-1JSON\s0.pm and install \s-1JSON::XS\s0 for speed or by accident. If you need JavaScript-friendly RFC7159\-compliant pure perl module, try JSON::Tiny, which is derived from Mojolicious web framework and is also smaller and faster than \s-1JSON::PP.\s0 .PP \&\s-1JSON::PP\s0 has been in the Perl core since Perl 5.14, mainly for \&\s-1CPAN\s0 toolchain modules to parse \s-1META\s0.json. .SH "FUNCTIONAL INTERFACE" .IX Header "FUNCTIONAL INTERFACE" This section is taken from \s-1JSON::XS\s0 almost verbatim. \f(CW\*(C`encode_json\*(C'\fR and \f(CW\*(C`decode_json\*(C'\fR are exported by default. .SS "encode_json" .IX Subsection "encode_json" .Vb 1 \& $json_text = encode_json $perl_scalar .Ve .PP Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string (that is, the string contains octets only). Croaks on error. .PP This function call is functionally identical to: .PP .Vb 1 \& $json_text = JSON::PP\->new\->utf8\->encode($perl_scalar) .Ve .PP Except being faster. .SS "decode_json" .IX Subsection "decode_json" .Vb 1 \& $perl_scalar = decode_json $json_text .Ve .PP The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an \s-1UTF\-8\s0 (binary) string and tries to parse that as an \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the resulting reference. Croaks on error. .PP This function call is functionally identical to: .PP .Vb 1 \& $perl_scalar = JSON::PP\->new\->utf8\->decode($json_text) .Ve .PP Except being faster. .SS "JSON::PP::is_bool" .IX Subsection "JSON::PP::is_bool" .Vb 1 \& $is_boolean = JSON::PP::is_bool($scalar) .Ve .PP Returns true if the passed scalar represents either JSON::PP::true or JSON::PP::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively and are also used to represent \s-1JSON\s0 \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings. .PP On perl 5.36 and above, will also return true when given one of perl's standard boolean values, such as the result of a comparison. .PP See \s-1MAPPING\s0, below, for more information on how \s-1JSON\s0 values are mapped to Perl. .SH "OBJECT-ORIENTED INTERFACE" .IX Header "OBJECT-ORIENTED INTERFACE" This section is also taken from \s-1JSON::XS.\s0 .PP The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. .SS "new" .IX Subsection "new" .Vb 1 \& $json = JSON::PP\->new .Ve .PP Creates a new \s-1JSON::PP\s0 object that can be used to de/encode \s-1JSON\s0 strings. All boolean flags described below are by default \fIdisabled\fR (with the exception of \f(CW\*(C`allow_nonref\*(C'\fR, which defaults to \fIenabled\fR since version \f(CW4.0\fR). .PP The mutators for flags all return the \s-1JSON::PP\s0 object again and thus calls can be chained: .PP .Vb 2 \& my $json = JSON::PP\->new\->utf8\->space_after\->encode({a => [1,2]}) \& => {"a": [1, 2]} .Ve .SS "ascii" .IX Subsection "ascii" .Vb 1 \& $json = $json\->ascii([$enable]) \& \& $enabled = $json\->get_ascii .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not generate characters outside the code range \f(CW0..127\fR (which is \s-1ASCII\s0). Any Unicode characters outside that range will be escaped using either a single \euXXXX (\s-1BMP\s0 characters) or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627.\s0 The resulting encoded \s-1JSON\s0 text can be treated as a native Unicode string, an ascii-encoded, latin1\-encoded or \s-1UTF\-8\s0 encoded string, or any other superset of \s-1ASCII.\s0 .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode characters unless required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format. .PP See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .PP The main use for this flag is to produce \s-1JSON\s0 texts that can be transmitted over a 7\-bit channel, as the encoded \s-1JSON\s0 texts will not contain any 8 bit characters. .PP .Vb 2 \& JSON::PP\->new\->ascii(1)\->encode([chr 0x10401]) \& => ["\eud801\eudc01"] .Ve .SS "latin1" .IX Subsection "latin1" .Vb 1 \& $json = $json\->latin1([$enable]) \& \& $enabled = $json\->get_latin1 .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode the resulting \s-1JSON\s0 text as latin1 (or iso\-8859\-1), escaping any characters outside the code range \f(CW0..255\fR. The resulting string can be treated as a latin1\-encoded \s-1JSON\s0 text or a native Unicode string. The \f(CW\*(C`decode\*(C'\fR method will not be affected in any way by this flag, as \f(CW\*(C`decode\*(C'\fR by default expects Unicode, which is a strict superset of latin1. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode characters unless required by the \s-1JSON\s0 syntax or other flags. .PP See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .PP The main use for this flag is efficiently encoding binary data as \s-1JSON\s0 text, as most octets will not be escaped, resulting in a smaller encoded size. The disadvantage is that the resulting \s-1JSON\s0 text is encoded in latin1 (and must correctly be treated as such when storing and transferring), a rare encoding for \s-1JSON.\s0 It is therefore most useful when you want to store data structures known to contain binary data efficiently in files or databases, not when talking to other \s-1JSON\s0 encoders/decoders. .PP .Vb 2 \& JSON::PP\->new\->latin1\->encode (["\ex{89}\ex{abc}"] \& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) .Ve .SS "utf8" .IX Subsection "utf8" .Vb 1 \& $json = $json\->utf8([$enable]) \& \& $enabled = $json\->get_utf8 .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode the \s-1JSON\s0 result into \s-1UTF\-8,\s0 as required by many protocols, while the \&\f(CW\*(C`decode\*(C'\fR method expects to be handled an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not contain any characters outside the range \f(CW0..255\fR, they are thus useful for bytewise/binary I/O. In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0 encoding families, as described in \s-1RFC4627.\s0 .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will return the \s-1JSON\s0 string as a (non-encoded) Unicode string, while \f(CW\*(C`decode\*(C'\fR expects thus a Unicode string. Any decoding or encoding (e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module. .PP See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .PP Example, output UTF\-16BE\-encoded \s-1JSON:\s0 .PP .Vb 2 \& use Encode; \& $jsontext = encode "UTF\-16BE", JSON::PP\->new\->encode ($object); .Ve .PP Example, decode UTF\-32LE\-encoded \s-1JSON:\s0 .PP .Vb 2 \& use Encode; \& $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext); .Ve .SS "pretty" .IX Subsection "pretty" .Vb 1 \& $json = $json\->pretty([$enable]) .Ve .PP This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and \&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to generate the most readable (or most compact) form possible. .SS "indent" .IX Subsection "indent" .Vb 1 \& $json = $json\->indent([$enable]) \& \& $enabled = $json\->get_indent .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, indenting them properly. .PP If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the resulting \s-1JSON\s0 text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR. .PP This setting has no effect when decoding \s-1JSON\s0 texts. .PP The default indent space length is three. You can use \f(CW\*(C`indent_length\*(C'\fR to change the length. .SS "space_before" .IX Subsection "space_before" .Vb 1 \& $json = $json\->space_before([$enable]) \& \& $enabled = $json\->get_space_before .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra space at those places. .PP This setting has no effect when decoding \s-1JSON\s0 texts. You will also most likely combine this setting with \f(CW\*(C`space_after\*(C'\fR. .PP Example, space_before enabled, space_after and indent disabled: .PP .Vb 1 \& {"key" :"value"} .Ve .SS "space_after" .IX Subsection "space_after" .Vb 1 \& $json = $json\->space_after([$enable]) \& \& $enabled = $json\->get_space_after .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array members. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra space at those places. .PP This setting has no effect when decoding \s-1JSON\s0 texts. .PP Example, space_before and indent disabled, space_after enabled: .PP .Vb 1 \& {"key": "value"} .Ve .SS "relaxed" .IX Subsection "relaxed" .Vb 1 \& $json = $json\->relaxed([$enable]) \& \& $enabled = $json\->get_relaxed .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be affected in anyway. \fIBe aware that this option makes you accept invalid \&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept valid \s-1JSON\s0 texts. .PP Currently accepted extensions are: .IP "\(bu" 4 list items can have an end-comma .Sp \&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. This can be annoying if you write \s-1JSON\s0 texts manually and want to be able to quickly append elements, so this extension accepts comma at the end of such items not just between them: .Sp .Vb 8 \& [ \& 1, \& 2, <\- this comma not normally allowed \& ] \& { \& "k1": "v1", \& "k2": "v2", <\- this comma not normally allowed \& } .Ve .IP "\(bu" 4 shell-style '#'\-comments .Sp Whenever \s-1JSON\s0 allows whitespace, shell-style comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. .Sp .Vb 4 \& [ \& 1, # this comment not allowed in JSON \& # neither this one... \& ] .Ve .IP "\(bu" 4 C\-style multiple-line '/* */'\-comments (\s-1JSON::PP\s0 only) .Sp Whenever \s-1JSON\s0 allows whitespace, C\-style multiple-line comments are additionally allowed. Everything between \f(CW\*(C`/*\*(C'\fR and \f(CW\*(C`*/\*(C'\fR is a comment, after which more white-space and comments are allowed. .Sp .Vb 4 \& [ \& 1, /* this comment not allowed in JSON */ \& /* neither this one... */ \& ] .Ve .IP "\(bu" 4 \&\*(C+\-style one-line '//'\-comments (\s-1JSON::PP\s0 only) .Sp Whenever \s-1JSON\s0 allows whitespace, \*(C+\-style one-line comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. .Sp .Vb 4 \& [ \& 1, // this comment not allowed in JSON \& // neither this one... \& ] .Ve .IP "\(bu" 4 literal \s-1ASCII TAB\s0 characters in strings .Sp Literal \s-1ASCII TAB\s0 characters are now allowed in strings (and treated as \&\f(CW\*(C`\et\*(C'\fR). .Sp .Vb 4 \& [ \& "Hello\etWorld", \& "Hello<TAB>World", # literal <TAB> would not normally be allowed \& ] .Ve .SS "canonical" .IX Subsection "canonical" .Vb 1 \& $json = $json\->canonical([$enable]) \& \& $enabled = $json\->get_canonical .Ve .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output \s-1JSON\s0 objects by sorting their keys. This is adding a comparatively high overhead. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value pairs in the order Perl stores them (which will likely change between runs of the same script, and can change even within the same run from 5.18 onwards). .PP This option is useful if you want the same data structure to be encoded as the same \s-1JSON\s0 text (given the same overall settings). If it is disabled, the same hash might be encoded differently even if contains the same data, as key-value pairs have no inherent ordering in Perl. .PP This setting has no effect when decoding \s-1JSON\s0 texts. .PP This setting has currently no effect on tied hashes. .SS "allow_nonref" .IX Subsection "allow_nonref" .Vb 1 \& $json = $json\->allow_nonref([$enable]) \& \& $enabled = $json\->get_allow_nonref .Ve .PP Unlike other boolean options, this opotion is enabled by default beginning with version \f(CW4.0\fR. .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a non-reference into its corresponding string, number or null \s-1JSON\s0 value, which is an extension to \s-1RFC4627.\s0 Likewise, \f(CW\*(C`decode\*(C'\fR will accept those \s-1JSON\s0 values instead of croaking. .PP If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a \&\s-1JSON\s0 object or array. .PP Example, encode a Perl scalar as \s-1JSON\s0 value without enabled \f(CW\*(C`allow_nonref\*(C'\fR, resulting in an error: .PP .Vb 2 \& JSON::PP\->new\->allow_nonref(0)\->encode ("Hello, World!") \& => hash\- or arrayref expected... .Ve .SS "allow_unknown" .IX Subsection "allow_unknown" .Vb 1 \& $json = $json\->allow_unknown([$enable]) \& \& $enabled = $json\->get_allow_unknown .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will \fInot\fR throw an exception when it encounters values it cannot represent in \s-1JSON\s0 (for example, filehandles) but instead will encode a \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value. Note that blessed objects are not included here and are handled separately by c<allow_blessed>. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an exception when it encounters anything it cannot encode as \s-1JSON.\s0 .PP This option does not affect \f(CW\*(C`decode\*(C'\fR in any way, and it is recommended to leave it off unless you know your communications partner. .SS "allow_blessed" .IX Subsection "allow_blessed" .Vb 1 \& $json = $json\->allow_blessed([$enable]) \& \& $enabled = $json\->get_allow_blessed .Ve .PP See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .PP If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not barf when it encounters a blessed reference that it cannot convert otherwise. Instead, a \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value is encoded instead of the object. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an exception when it encounters a blessed object that it cannot convert otherwise. .PP This setting has no effect on \f(CW\*(C`decode\*(C'\fR. .SS "convert_blessed" .IX Subsection "convert_blessed" .Vb 1 \& $json = $json\->convert_blessed([$enable]) \& \& $enabled = $json\->get_convert_blessed .Ve .PP See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method on the object's class. If found, it will be called in scalar context and the resulting scalar will be encoded instead of the object. .PP The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR returns other blessed objects, those will be handled in the same way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other methods called by the Perl core (== not by the user of the object) are usually in upper case letters and to avoid collisions with any \f(CW\*(C`to_json\*(C'\fR function or method. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider this type of conversion. .PP This setting has no effect on \f(CW\*(C`decode\*(C'\fR. .SS "allow_tags" .IX Subsection "allow_tags" .Vb 1 \& $json = $json\->allow_tags([$enable]) \& \& $enabled = $json\->get_allow_tags .Ve .PP See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a blessed object, will check for the availability of the \f(CW\*(C`FREEZE\*(C'\fR method on the object's class. If found, it will be used to serialise the object into a nonstandard tagged \s-1JSON\s0 value (that \s-1JSON\s0 decoders cannot decode). .PP It also causes \f(CW\*(C`decode\*(C'\fR to parse such tagged \s-1JSON\s0 values and deserialise them via a call to the \f(CW\*(C`THAW\*(C'\fR method. .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider this type of conversion, and tagged \s-1JSON\s0 values will cause a parse error in \f(CW\*(C`decode\*(C'\fR, as if tags were not part of the grammar. .SS "boolean_values" .IX Subsection "boolean_values" .Vb 1 \& $json\->boolean_values([$false, $true]) \& \& ($false, $true) = $json\->get_boolean_values .Ve .PP By default, \s-1JSON\s0 booleans will be decoded as overloaded \&\f(CW$JSON::PP::false\fR and \f(CW$JSON::PP::true\fR objects. .PP With this method you can specify your own boolean values for decoding \- on decode, \s-1JSON\s0 \f(CW\*(C`false\*(C'\fR will be decoded as a copy of \f(CW$false\fR, and \s-1JSON\s0 \&\f(CW\*(C`true\*(C'\fR will be decoded as \f(CW$true\fR (\*(L"copy\*(R" here is the same thing as assigning a value to another variable, i.e. \f(CW\*(C`$copy = $false\*(C'\fR). .PP This is useful when you want to pass a decoded data structure directly to other serialisers like \s-1YAML,\s0 Data::MessagePack and so on. .PP Note that this works only when you \f(CW\*(C`decode\*(C'\fR. You can set incompatible boolean objects (like boolean), but when you \f(CW\*(C`encode\*(C'\fR a data structure with such boolean objects, you still need to enable \f(CW\*(C`convert_blessed\*(C'\fR (and add a \f(CW\*(C`TO_JSON\*(C'\fR method if necessary). .PP Calling this method without any arguments will reset the booleans to their default values. .PP \&\f(CW\*(C`get_boolean_values\*(C'\fR will return both \f(CW$false\fR and \f(CW$true\fR values, or the empty list when they are set to the default. .SS "core_bools" .IX Subsection "core_bools" .Vb 1 \& $json\->core_bools([$enable]); .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR, will produce standard perl boolean values. Equivalent to calling: .PP .Vb 1 \& $json\->boolean_values(!!1, !!0) .Ve .PP \&\f(CW\*(C`get_core_bools\*(C'\fR will return true if this has been set. On perl 5.36, it will also return true if the boolean values have been set to perl's core booleans using the \f(CW\*(C`boolean_values\*(C'\fR method. .PP The methods \f(CW\*(C`unblessed_bool\*(C'\fR and \f(CW\*(C`get_unblessed_bool\*(C'\fR are provided as aliases for compatibility with Cpanel::JSON::XS. .SS "filter_json_object" .IX Subsection "filter_json_object" .Vb 1 \& $json = $json\->filter_json_object([$coderef]) .Ve .PP When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each time it decodes a \s-1JSON\s0 object. The only argument is a reference to the newly-created hash. If the code references returns a single scalar (which need not be a reference), this value (or rather a copy of it) is inserted into the deserialised data structure. If it returns an empty list (\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original deserialised hash will be inserted. This setting can slow down decoding considerably. .PP When \f(CW$coderef\fR is omitted or undefined, any existing callback will be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any way. .PP Example, convert all \s-1JSON\s0 objects into the integer 5: .PP .Vb 5 \& my $js = JSON::PP\->new\->filter_json_object(sub { 5 }); \& # returns [5] \& $js\->decode(\*(Aq[{}]\*(Aq); \& # returns 5 \& $js\->decode(\*(Aq{"a":1, "b":2}\*(Aq); .Ve .SS "filter_json_single_key_object" .IX Subsection "filter_json_single_key_object" .Vb 1 \& $json = $json\->filter_json_single_key_object($key [=> $coderef]) .Ve .PP Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for \&\s-1JSON\s0 objects having a single key named \f(CW$key\fR. .PP This \f(CW$coderef\fR is called before the one specified via \&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the \s-1JSON\s0 object. If it returns a single value, it will be inserted into the data structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list), the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no single-key callback were specified. .PP If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be disabled. There can only ever be one callback for a given key. .PP As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR one, decoding speed will not usually suffer as much. Therefore, single-key objects make excellent targets to serialise Perl objects into, especially as single-key \s-1JSON\s0 objects are as close to the type-tagged value concept as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JSON\s0 does not support this in any way, so you need to make sure your data never looks like a serialised Perl hash. .PP Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or \&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing with real hashes. .PP Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR into the corresponding \f(CW$WIDGET{<id>}\fR object: .PP .Vb 7 \& # return whatever is in $WIDGET{5}: \& JSON::PP \& \->new \& \->filter_json_single_key_object (_\|_widget_\|_ => sub { \& $WIDGET{ $_[0] } \& }) \& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq) \& \& # this can be used with a TO_JSON method in some "widget" class \& # for serialisation to json: \& sub WidgetBase::TO_JSON { \& my ($self) = @_; \& \& unless ($self\->{id}) { \& $self\->{id} = ..get..some..id..; \& $WIDGET{$self\->{id}} = $self; \& } \& \& { _\|_widget_\|_ => $self\->{id} } \& } .Ve .SS "shrink" .IX Subsection "shrink" .Vb 1 \& $json = $json\->shrink([$enable]) \& \& $enabled = $json\->get_shrink .Ve .PP If \f(CW$enable\fR is true (or missing), the string returned by \f(CW\*(C`encode\*(C'\fR will be shrunk (i.e. downgraded if possible). .PP The actual definition of what shrink does might change in future versions, but it will always try to save space at the expense of time. .PP If \f(CW$enable\fR is false, then \s-1JSON::PP\s0 does nothing. .SS "max_depth" .IX Subsection "max_depth" .Vb 1 \& $json = $json\->max_depth([$maximum_nesting_depth]) \& \& $max_depth = $json\->get_max_depth .Ve .PP Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl data structure, then the encoder and decoder will stop and croak at that point. .PP Nesting level is defined by number of hash\- or arrayrefs that the encoder needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR characters without their matching closing parenthesis crossed to reach a given character in a string. .PP Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. .PP If no argument is given, the highest possible setting will be used, which is rarely useful. .PP See \*(L"\s-1SECURITY CONSIDERATIONS\*(R"\s0 in \s-1JSON::XS\s0 for more info on why this is useful. .SS "max_size" .IX Subsection "max_size" .Vb 1 \& $json = $json\->max_size([$maximum_string_size]) \& \& $max_size = $json\->get_max_size .Ve .PP Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR is called on a string that is longer then this many bytes, it will not attempt to decode the string but throw an exception. This setting has no effect on \f(CW\*(C`encode\*(C'\fR (yet). .PP If no argument is given, the limit check will be deactivated (same as when \&\f(CW0\fR is specified). .PP See \*(L"\s-1SECURITY CONSIDERATIONS\*(R"\s0 in \s-1JSON::XS\s0 for more info on why this is useful. .SS "encode" .IX Subsection "encode" .Vb 1 \& $json_text = $json\->encode($perl_scalar) .Ve .PP Converts the given Perl value or data structure to its \s-1JSON\s0 representation. Croaks on error. .SS "decode" .IX Subsection "decode" .Vb 1 \& $perl_scalar = $json\->decode($json_text) .Ve .PP The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries to parse it, returning the resulting simple scalar or reference. Croaks on error. .SS "decode_prefix" .IX Subsection "decode_prefix" .Vb 1 \& ($perl_scalar, $characters) = $json\->decode_prefix($json_text) .Ve .PP This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception when there is trailing garbage after the first \s-1JSON\s0 object, it will silently stop parsing there and return the number of characters consumed so far. .PP This is useful if your \s-1JSON\s0 texts are not delimited by an outer protocol and you need to know where the \s-1JSON\s0 text ends. .PP .Vb 2 \& JSON::PP\->new\->decode_prefix ("[1] the tail") \& => ([1], 3) .Ve .SH "FLAGS FOR JSON::PP ONLY" .IX Header "FLAGS FOR JSON::PP ONLY" The following flags and properties are for \s-1JSON::PP\s0 only. If you use any of these, you can't make your application run faster by replacing \&\s-1JSON::PP\s0 with \s-1JSON::XS.\s0 If you need these and also speed boost, you might want to try Cpanel::JSON::XS, a fork of \s-1JSON::XS\s0 by Reini Urban, which supports some of these (with a different set of incompatibilities). Most of these historical flags are only kept for backward compatibility, and should not be used in a new application. .SS "allow_singlequote" .IX Subsection "allow_singlequote" .Vb 2 \& $json = $json\->allow_singlequote([$enable]) \& $enabled = $json\->get_allow_singlequote .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept invalid \s-1JSON\s0 texts that contain strings that begin and end with single quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected in any way. \&\fIBe aware that this option makes you accept invalid \s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept valid \s-1JSON\s0 texts. .PP .Vb 3 \& $json\->allow_singlequote\->decode(qq|{"foo":\*(Aqbar\*(Aq}|); \& $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:"bar"}|); \& $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq}|); .Ve .SS "allow_barekey" .IX Subsection "allow_barekey" .Vb 2 \& $json = $json\->allow_barekey([$enable]) \& $enabled = $json\->get_allow_barekey .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept invalid \s-1JSON\s0 texts that contain \s-1JSON\s0 objects whose names don't begin and end with quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected in any way. \fIBe aware that this option makes you accept invalid \s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept valid \s-1JSON\s0 texts. .PP .Vb 1 \& $json\->allow_barekey\->decode(qq|{foo:"bar"}|); .Ve .SS "allow_bignum" .IX Subsection "allow_bignum" .Vb 2 \& $json = $json\->allow_bignum([$enable]) \& $enabled = $json\->get_allow_bignum .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert big integers Perl cannot handle as integer into Math::BigInt objects and convert floating numbers into Math::BigFloat objects. \f(CW\*(C`encode\*(C'\fR will convert \f(CW\*(C`Math::BigInt\*(C'\fR and \f(CW\*(C`Math::BigFloat\*(C'\fR objects into \s-1JSON\s0 numbers. .PP .Vb 4 \& $json\->allow_nonref\->allow_bignum; \& $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq); \& print $json\->encode($bigfloat); \& # => 2.000000000000000000000000001 .Ve .PP See also \s-1MAPPING\s0. .SS "loose" .IX Subsection "loose" .Vb 2 \& $json = $json\->loose([$enable]) \& $enabled = $json\->get_loose .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept invalid \s-1JSON\s0 texts that contain unescaped [\ex00\-\ex1f\ex22\ex5c] characters. \f(CW\*(C`encode\*(C'\fR will not be affected in any way. \&\fIBe aware that this option makes you accept invalid \s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) .PP If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept valid \s-1JSON\s0 texts. .PP .Vb 2 \& $json\->loose\->decode(qq|["abc \& def"]|); .Ve .SS "escape_slash" .IX Subsection "escape_slash" .Vb 2 \& $json = $json\->escape_slash([$enable]) \& $enabled = $json\->get_escape_slash .Ve .PP If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will explicitly escape \fIslash\fR (solidus; \f(CW\*(C`U+002F\*(C'\fR) characters to reduce the risk of \&\s-1XSS\s0 (cross site scripting) that may be caused by \f(CW\*(C`</script>\*(C'\fR in a \s-1JSON\s0 text, with the cost of bloating the size of \s-1JSON\s0 texts. .PP This option may be useful when you embed \s-1JSON\s0 in \s-1HTML,\s0 but embedding arbitrary \s-1JSON\s0 in \s-1HTML\s0 (by some \s-1HTML\s0 template toolkit or by string interpolation) is risky in general. You must escape necessary characters in correct order, depending on the context. .PP \&\f(CW\*(C`decode\*(C'\fR will not be affected in any way. .SS "indent_length" .IX Subsection "indent_length" .Vb 2 \& $json = $json\->indent_length($number_of_spaces) \& $length = $json\->get_indent_length .Ve .PP This option is only useful when you also enable \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR. .PP \&\s-1JSON::XS\s0 indents with three spaces when you \f(CW\*(C`encode\*(C'\fR (if requested by \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR), and the number cannot be changed. \&\s-1JSON::PP\s0 allows you to change/get the number of indent spaces with these mutator/accessor. The default number of spaces is three (the same as \&\s-1JSON::XS\s0), and the acceptable range is from \f(CW0\fR (no indentation; it'd be better to disable indentation by \f(CWindent(0)\fR) to \f(CW15\fR. .SS "sort_by" .IX Subsection "sort_by" .Vb 2 \& $json = $json\->sort_by($code_ref) \& $json = $json\->sort_by($subroutine_name) .Ve .PP If you just want to sort keys (names) in \s-1JSON\s0 objects when you \&\f(CW\*(C`encode\*(C'\fR, enable \f(CW\*(C`canonical\*(C'\fR option (see above) that allows you to sort object keys alphabetically. .PP If you do need to sort non-alphabetically for whatever reasons, you can give a code reference (or a subroutine name) to \f(CW\*(C`sort_by\*(C'\fR, then the argument will be passed to Perl's \f(CW\*(C`sort\*(C'\fR built-in function. .PP As the sorting is done in the \s-1JSON::PP\s0 scope, you usually need to prepend \f(CW\*(C`JSON::PP::\*(C'\fR to the subroutine name, and the special variables \&\f(CW$a\fR and \f(CW$b\fR used in the subrontine used by \f(CW\*(C`sort\*(C'\fR function. .PP Example: .PP .Vb 9 \& my %ORDER = (id => 1, class => 2, name => 3); \& $json\->sort_by(sub { \& ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999) \& or $JSON::PP::a cmp $JSON::PP::b \& }); \& print $json\->encode([ \& {name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq} \& ]); \& # [{"id":1,"name":"CPAN","href":"http://cpan.org"}] .Ve .PP Note that \f(CW\*(C`sort_by\*(C'\fR affects all the plain hashes in the data structure. If you need finer control, \f(CW\*(C`tie\*(C'\fR necessary hashes with a module that implements ordered hash (such as Hash::Ordered and Tie::IxHash). \&\f(CW\*(C`canonical\*(C'\fR and \f(CW\*(C`sort_by\*(C'\fR don't affect the key order in \f(CW\*(C`tie\*(C'\fRd hashes. .PP .Vb 5 \& use Hash::Ordered; \& tie my %hash, \*(AqHash::Ordered\*(Aq, \& (name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq); \& print $json\->encode([\e%hash]); \& # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept .Ve .SH "INCREMENTAL PARSING" .IX Header "INCREMENTAL PARSING" This section is also taken from \s-1JSON::XS.\s0 .PP In some cases, there is the need for incremental parsing of \s-1JSON\s0 texts. While this module always has to keep both \s-1JSON\s0 text and resulting Perl data structure in memory at one time, it does allow you to parse a \&\s-1JSON\s0 stream incrementally. It does so by accumulating text until it has a full \s-1JSON\s0 object, which it then can decode. This process is similar to using \f(CW\*(C`decode_prefix\*(C'\fR to see if a full \s-1JSON\s0 object is available, but is much more efficient (and can be implemented with a minimum of method calls). .PP \&\s-1JSON::PP\s0 will only attempt to parse the \s-1JSON\s0 text once it is sure it has enough text to get a decisive result, using a very simple but truly incremental parser. This means that it sometimes won't stop as early as the full parser, for example, it doesn't detect mismatched parentheses. The only thing it guarantees is that it starts decoding as soon as a syntactically valid \s-1JSON\s0 text has been seen. This means you need to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop parsing in the presence if syntax errors. .PP The following methods implement this incremental parser. .SS "incr_parse" .IX Subsection "incr_parse" .Vb 1 \& $json\->incr_parse( [$string] ) # void context \& \& $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context \& \& @obj_or_empty = $json\->incr_parse( [$string] ) # list context .Ve .PP This is the central parsing function. It can both append new text and extract objects from the stream accumulated so far (both of these functions are optional). .PP If \f(CW$string\fR is given, then this string is appended to the already existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object. .PP After that, if the function is called in void context, it will simply return without doing anything further. This can be used to add more text in as many chunks as you want. .PP If the method is called in scalar context, then it will try to extract exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error, this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use \&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of using the method. .PP And finally, in list context, it will try to extract as many objects from the stream as it can find and return them, or the empty list otherwise. For this to work, there must be no separators (other than whitespace) between the \s-1JSON\s0 objects or arrays, instead they must be concatenated back-to-back. If an error occurs, an exception will be raised as in the scalar context case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be lost. .PP Example: Parse some \s-1JSON\s0 arrays/objects in a given string and return them. .PP .Vb 1 \& my @objs = JSON::PP\->new\->incr_parse ("[5][7][1,2]"); .Ve .SS "incr_text" .IX Subsection "incr_text" .Vb 1 \& $lvalue_string = $json\->incr_text .Ve .PP This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that is, you can manipulate it. This \fIonly\fR works when a preceding call to \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under all other circumstances you must not call this function (I mean it. although in simple tests it might actually work, it \fIwill\fR fail under real world conditions). As a special exception, you can also call this method before having parsed anything. .PP That means you can only use this function to look at or manipulate text before or after complete \s-1JSON\s0 objects, not while the parser is in the middle of parsing a \s-1JSON\s0 object. .PP This function is useful in two cases: a) finding the trailing text after a \&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text (such as commas). .SS "incr_skip" .IX Subsection "incr_skip" .Vb 1 \& $json\->incr_skip .Ve .PP This will reset the state of the incremental parser and will remove the parsed text from the input buffer so far. This is useful after \&\f(CW\*(C`incr_parse\*(C'\fR died, in which case the input buffer and incremental parser state is left unchanged, to skip the text parsed so far and to reset the parse state. .PP The difference to \f(CW\*(C`incr_reset\*(C'\fR is that only text until the parse error occurred is removed. .SS "incr_reset" .IX Subsection "incr_reset" .Vb 1 \& $json\->incr_reset .Ve .PP This completely resets the incremental parser, that is, after this call, it will be as if the parser had never parsed anything. .PP This is useful if you want to repeatedly parse \s-1JSON\s0 objects and want to ignore any trailing data, which means you have to reset the parser after each successful decode. .SH "MAPPING" .IX Header "MAPPING" Most of this section is also taken from \s-1JSON::XS.\s0 .PP This section describes how \s-1JSON::PP\s0 maps Perl values to \s-1JSON\s0 values and vice versa. These mappings are designed to \*(L"do the right thing\*(R" in most circumstances automatically, preserving round-tripping characteristics (what you put in comes out as something equivalent). .PP For the more enlightened: note that in the following descriptions, lowercase \fIperl\fR refers to the Perl interpreter, while uppercase \fIPerl\fR refers to the abstract Perl language itself. .SS "\s-1JSON\s0 \-> \s-1PERL\s0" .IX Subsection "JSON -> PERL" .IP "object" 4 .IX Item "object" A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of object keys is preserved (\s-1JSON\s0 does not preserve object key ordering itself). .IP "array" 4 .IX Item "array" A \s-1JSON\s0 array becomes a reference to an array in Perl. .IP "string" 4 .IX Item "string" A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s-1JSON\s0 are represented by the same codepoints in the Perl string, so no manual decoding is necessary. .IP "number" 4 .IX Item "number" A \s-1JSON\s0 number becomes either an integer, numeric (floating point) or string scalar in perl, depending on its range and any fractional parts. On the Perl level, there is no difference between those as Perl handles all the conversion details, but an integer may take slightly less memory and might represent more values exactly than floating point numbers. .Sp If the number consists of digits only, \s-1JSON::PP\s0 will try to represent it as an integer value. If that fails, it will try to represent it as a numeric (floating point) value if that is possible without loss of precision. Otherwise it will preserve the number as a string value (in which case you lose roundtripping ability, as the \s-1JSON\s0 number will be re-encoded to a \s-1JSON\s0 string). .Sp Numbers containing a fractional or exponential part will always be represented as numeric (floating point) values, possibly at a loss of precision (in which case you might lose perfect roundtripping ability, but the \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number). .Sp Note that precision is not accuracy \- binary floating point values cannot represent most decimal fractions exactly, and when converting from and to floating point, \s-1JSON::PP\s0 only guarantees precision up to but not including the least significant bit. .Sp When \f(CW\*(C`allow_bignum\*(C'\fR is enabled, big integer values and any numeric values will be converted into Math::BigInt and Math::BigFloat objects respectively, without becoming string scalars or losing precision. .IP "true, false" 4 .IX Item "true, false" These \s-1JSON\s0 atoms become \f(CW\*(C`JSON::PP::true\*(C'\fR and \f(CW\*(C`JSON::PP::false\*(C'\fR, respectively. They are overloaded to act almost exactly like the numbers \&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a \s-1JSON\s0 boolean by using the \f(CW\*(C`JSON::PP::is_bool\*(C'\fR function. .IP "null" 4 .IX Item "null" A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl. .ie n .IP "shell-style comments (""# \fItext\fP"")" 4 .el .IP "shell-style comments (\f(CW# \f(CItext\f(CW\fR)" 4 .IX Item "shell-style comments (# text)" As a nonstandard extension to the \s-1JSON\s0 syntax that is enabled by the \&\f(CW\*(C`relaxed\*(C'\fR setting, shell-style comments are allowed. They can start anywhere outside strings and go till the end of the line. .ie n .IP "tagged values (""(\fItag\fP)\fIvalue\fP"")." 4 .el .IP "tagged values (\f(CW(\f(CItag\f(CW)\f(CIvalue\f(CW\fR)." 4 .IX Item "tagged values ((tag)value)." Another nonstandard extension to the \s-1JSON\s0 syntax, enabled with the \&\f(CW\*(C`allow_tags\*(C'\fR setting, are tagged values. In this implementation, the \&\fItag\fR must be a perl package/class name encoded as a \s-1JSON\s0 string, and the \&\fIvalue\fR must be a \s-1JSON\s0 array encoding optional constructor arguments. .Sp See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0, below, for details. .SS "\s-1PERL\s0 \-> \s-1JSON\s0" .IX Subsection "PERL -> JSON" The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by a Perl value. .IP "hash references" 4 .IX Item "hash references" Perl hash references become \s-1JSON\s0 objects. As there is no inherent ordering in hash keys (or \s-1JSON\s0 objects), they will usually be encoded in a pseudo-random order. \s-1JSON::PP\s0 can optionally sort the hash keys (determined by the \fIcanonical\fR flag and/or \fIsort_by\fR property), so the same data structure will serialise to the same \s-1JSON\s0 text (given same settings and version of \s-1JSON::PP\s0), but this incurs a runtime overhead and is only rarely useful, e.g. when you want to compare some \&\s-1JSON\s0 text against another for equality. .IP "array references" 4 .IX Item "array references" Perl array references become \s-1JSON\s0 arrays. .IP "other references" 4 .IX Item "other references" Other unblessed references are generally not allowed and will cause an exception to be thrown, except for references to the integers \f(CW0\fR and \&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in \s-1JSON.\s0 You can also use \f(CW\*(C`JSON::PP::false\*(C'\fR and \f(CW\*(C`JSON::PP::true\*(C'\fR to improve readability. .Sp .Vb 1 \& to_json [\e0, JSON::PP::true] # yields [false,true] .Ve .IP "JSON::PP::true, JSON::PP::false" 4 .IX Item "JSON::PP::true, JSON::PP::false" These special values become \s-1JSON\s0 true and \s-1JSON\s0 false values, respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want. .IP "JSON::PP::null" 4 .IX Item "JSON::PP::null" This special value becomes \s-1JSON\s0 null. .IP "blessed objects" 4 .IX Item "blessed objects" Blessed objects are not directly representable in \s-1JSON,\s0 but \f(CW\*(C`JSON::PP\*(C'\fR allows various ways of handling objects. See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0, below, for details. .IP "simple scalars" 4 .IX Item "simple scalars" Simple Perl scalars (any scalar that is not a reference) are the most difficult objects to encode: \s-1JSON::PP\s0 will encode undefined scalars as \&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context before encoding as \s-1JSON\s0 strings, and anything else as number value: .Sp .Vb 4 \& # dump as number \& encode_json [2] # yields [2] \& encode_json [\-3.0e17] # yields [\-3e+17] \& my $value = 5; encode_json [$value] # yields [5] \& \& # used as string, so dump as string \& print $value; \& encode_json [$value] # yields ["5"] \& \& # undef becomes null \& encode_json [undef] # yields [null] .Ve .Sp You can force the type to be a \s-1JSON\s0 string by stringifying it: .Sp .Vb 5 \& my $x = 3.1; # some variable containing a number \& "$x"; # stringified \& $x .= ""; # another, more awkward way to stringify \& print $x; # perl does it for you, too, quite often \& # (but for older perls) .Ve .Sp You can force the type to be a \s-1JSON\s0 number by numifying it: .Sp .Vb 3 \& my $x = "3"; # some variable containing a string \& $x += 0; # numify it, ensuring it will be dumped as a number \& $x *= 1; # same thing, the choice is yours. .Ve .Sp You can not currently force the type in other, less obscure, ways. .Sp Since version 2.91_01, \s-1JSON::PP\s0 uses a different number detection logic that converts a scalar that is possible to turn into a number safely. The new logic is slightly faster, and tends to help people who use older perl or who want to encode complicated data structure. However, this may results in a different \s-1JSON\s0 text from the one \s-1JSON::XS\s0 encodes (and thus may break tests that compare entire \s-1JSON\s0 texts). If you do need the previous behavior for compatibility or for finer control, set \s-1PERL_JSON_PP_USE_B\s0 environmental variable to true before you \&\f(CW\*(C`use\*(C'\fR \s-1JSON::PP\s0 (or \s-1JSON\s0.pm). .Sp Note that numerical precision has the same meaning as under Perl (so binary to decimal conversion follows the same rules as in Perl, which can differ to other languages). Also, your perl interpreter might expose extensions to the floating point numbers of your platform, such as infinities or NaN's \- these cannot be represented in \s-1JSON,\s0 and it is an error to pass those in. .Sp \&\s-1JSON::PP\s0 (and \s-1JSON::XS\s0) trusts what you pass to \f(CW\*(C`encode\*(C'\fR method (or \f(CW\*(C`encode_json\*(C'\fR function) is a clean, validated data structure with values that can be represented as valid \s-1JSON\s0 values only, because it's not from an external data source (as opposed to \s-1JSON\s0 texts you pass to \&\f(CW\*(C`decode\*(C'\fR or \f(CW\*(C`decode_json\*(C'\fR, which \s-1JSON::PP\s0 considers tainted and doesn't trust). As \s-1JSON::PP\s0 doesn't know exactly what you and consumers of your \s-1JSON\s0 texts want the unexpected values to be (you may want to convert them into null, or to stringify them with or without normalisation (string representation of infinities/NaN may vary depending on platforms), or to croak without conversion), you're advised to do what you and your consumers need before you encode, and also not to numify values that may start with values that look like a number (including infinities/NaN), without validating. .SS "\s-1OBJECT SERIALISATION\s0" .IX Subsection "OBJECT SERIALISATION" As \s-1JSON\s0 cannot directly represent Perl objects, you have to choose between a pure \s-1JSON\s0 representation (without the ability to deserialise the object automatically again), and a nonstandard extension to the \s-1JSON\s0 syntax, tagged values. .PP \fI\s-1SERIALISATION\s0\fR .IX Subsection "SERIALISATION" .PP What happens when \f(CW\*(C`JSON::PP\*(C'\fR encounters a Perl object depends on the \&\f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR, \f(CW\*(C`allow_tags\*(C'\fR and \f(CW\*(C`allow_bignum\*(C'\fR settings, which are used in this order: .ie n .IP "1. ""allow_tags"" is enabled and the object has a ""FREEZE"" method." 4 .el .IP "1. \f(CWallow_tags\fR is enabled and the object has a \f(CWFREEZE\fR method." 4 .IX Item "1. allow_tags is enabled and the object has a FREEZE method." In this case, \f(CW\*(C`JSON::PP\*(C'\fR creates a tagged \s-1JSON\s0 value, using a nonstandard extension to the \s-1JSON\s0 syntax. .Sp This works by invoking the \f(CW\*(C`FREEZE\*(C'\fR method on the object, with the first argument being the object to serialise, and the second argument being the constant string \f(CW\*(C`JSON\*(C'\fR to distinguish it from other serialisers. .Sp The \f(CW\*(C`FREEZE\*(C'\fR method can return any number of values (i.e. zero or more). These values and the paclkage/classname of the object will then be encoded as a tagged \s-1JSON\s0 value in the following format: .Sp .Vb 1 \& ("classname")[FREEZE return values...] .Ve .Sp e.g.: .Sp .Vb 3 \& ("URI")["http://www.google.com/"] \& ("MyDate")[2013,10,29] \& ("ImageData::JPEG")["Z3...VlCg=="] .Ve .Sp For example, the hypothetical \f(CW\*(C`My::Object\*(C'\fR \f(CW\*(C`FREEZE\*(C'\fR method might use the objects \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`id\*(C'\fR members to encode the object: .Sp .Vb 2 \& sub My::Object::FREEZE { \& my ($self, $serialiser) = @_; \& \& ($self\->{type}, $self\->{id}) \& } .Ve .ie n .IP "2. ""convert_blessed"" is enabled and the object has a ""TO_JSON"" method." 4 .el .IP "2. \f(CWconvert_blessed\fR is enabled and the object has a \f(CWTO_JSON\fR method." 4 .IX Item "2. convert_blessed is enabled and the object has a TO_JSON method." In this case, the \f(CW\*(C`TO_JSON\*(C'\fR method of the object is invoked in scalar context. It must return a single scalar that can be directly encoded into \&\s-1JSON.\s0 This scalar replaces the object in the \s-1JSON\s0 text. .Sp For example, the following \f(CW\*(C`TO_JSON\*(C'\fR method will convert all \s-1URI\s0 objects to \s-1JSON\s0 strings when serialised. The fact that these values originally were \s-1URI\s0 objects is lost. .Sp .Vb 4 \& sub URI::TO_JSON { \& my ($uri) = @_; \& $uri\->as_string \& } .Ve .ie n .IP "3. ""allow_bignum"" is enabled and the object is a ""Math::BigInt"" or ""Math::BigFloat""." 4 .el .IP "3. \f(CWallow_bignum\fR is enabled and the object is a \f(CWMath::BigInt\fR or \f(CWMath::BigFloat\fR." 4 .IX Item "3. allow_bignum is enabled and the object is a Math::BigInt or Math::BigFloat." The object will be serialised as a \s-1JSON\s0 number value. .ie n .IP "4. ""allow_blessed"" is enabled." 4 .el .IP "4. \f(CWallow_blessed\fR is enabled." 4 .IX Item "4. allow_blessed is enabled." The object will be serialised as a \s-1JSON\s0 null value. .IP "5. none of the above" 4 .IX Item "5. none of the above" If none of the settings are enabled or the respective methods are missing, \&\f(CW\*(C`JSON::PP\*(C'\fR throws an exception. .PP \fI\s-1DESERIALISATION\s0\fR .IX Subsection "DESERIALISATION" .PP For deserialisation there are only two cases to consider: either nonstandard tagging was used, in which case \f(CW\*(C`allow_tags\*(C'\fR decides, or objects cannot be automatically be deserialised, in which case you can use postprocessing or the \f(CW\*(C`filter_json_object\*(C'\fR or \&\f(CW\*(C`filter_json_single_key_object\*(C'\fR callbacks to get some real objects our of your \s-1JSON.\s0 .PP This section only considers the tagged value case: a tagged \s-1JSON\s0 object is encountered during decoding and \f(CW\*(C`allow_tags\*(C'\fR is disabled, a parse error will result (as if tagged values were not part of the grammar). .PP If \f(CW\*(C`allow_tags\*(C'\fR is enabled, \f(CW\*(C`JSON::PP\*(C'\fR will look up the \f(CW\*(C`THAW\*(C'\fR method of the package/classname used during serialisation (it will not attempt to load the package as a Perl module). If there is no such method, the decoding will fail with an error. .PP Otherwise, the \f(CW\*(C`THAW\*(C'\fR method is invoked with the classname as first argument, the constant string \f(CW\*(C`JSON\*(C'\fR as second argument, and all the values from the \s-1JSON\s0 array (the values originally returned by the \&\f(CW\*(C`FREEZE\*(C'\fR method) as remaining arguments. .PP The method must then return the object. While technically you can return any Perl scalar, you might have to enable the \f(CW\*(C`allow_nonref\*(C'\fR setting to make that work in all cases, so better return an actual blessed reference. .PP As an example, let's implement a \f(CW\*(C`THAW\*(C'\fR function that regenerates the \&\f(CW\*(C`My::Object\*(C'\fR from the \f(CW\*(C`FREEZE\*(C'\fR example earlier: .PP .Vb 2 \& sub My::Object::THAW { \& my ($class, $serialiser, $type, $id) = @_; \& \& $class\->new (type => $type, id => $id) \& } .Ve .SH "ENCODING/CODESET FLAG NOTES" .IX Header "ENCODING/CODESET FLAG NOTES" This section is taken from \s-1JSON::XS.\s0 .PP The interested reader might have seen a number of flags that signify encodings or codesets \- \f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR. There seems to be some confusion on what these do, so here is a short comparison: .PP \&\f(CW\*(C`utf8\*(C'\fR controls whether the \s-1JSON\s0 text created by \f(CW\*(C`encode\*(C'\fR (and expected by \f(CW\*(C`decode\*(C'\fR) is \s-1UTF\-8\s0 encoded or not, while \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR only control whether \f(CW\*(C`encode\*(C'\fR escapes character values outside their respective codeset range. Neither of these flags conflict with each other, although some combinations make less sense than others. .PP Care has been taken to make all flags symmetrical with respect to \&\f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR, that is, texts encoded with any combination of these flag values will be correctly decoded when the same flags are used \&\- in general, if you use different flag settings while encoding vs. when decoding you likely have a bug somewhere. .PP Below comes a verbose discussion of these flags. Note that a \*(L"codeset\*(R" is simply an abstract set of character-codepoint pairs, while an encoding takes those codepoint numbers and \fIencodes\fR them, in our case into octets. Unicode is (among other things) a codeset, \s-1UTF\-8\s0 is an encoding, and \s-1ISO\-8859\-1\s0 (= latin 1) and \s-1ASCII\s0 are both codesets \fIand\fR encodings at the same time, which can be confusing. .ie n .IP """utf8"" flag disabled" 4 .el .IP "\f(CWutf8\fR flag disabled" 4 .IX Item "utf8 flag disabled" When \f(CW\*(C`utf8\*(C'\fR is disabled (the default), then \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR generate and expect Unicode strings, that is, characters with high ordinal Unicode values (> 255) will be encoded as such characters, and likewise such characters are decoded as-is, no changes to them will be done, except \&\*(L"(re\-)interpreting\*(R" them as Unicode codepoints or Unicode characters, respectively (to Perl, these are the same thing in strings unless you do funny/weird/dumb stuff). .Sp This is useful when you want to do the encoding yourself (e.g. when you want to have \s-1UTF\-16\s0 encoded \s-1JSON\s0 texts) or when some other layer does the encoding for you (for example, when printing to a terminal using a filehandle that transparently encodes to \s-1UTF\-8\s0 you certainly do \s-1NOT\s0 want to \s-1UTF\-8\s0 encode your data first and have Perl encode it another time). .ie n .IP """utf8"" flag enabled" 4 .el .IP "\f(CWutf8\fR flag enabled" 4 .IX Item "utf8 flag enabled" If the \f(CW\*(C`utf8\*(C'\fR\-flag is enabled, \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR will encode all characters using the corresponding \s-1UTF\-8\s0 multi-byte sequence, and will expect your input strings to be encoded as \s-1UTF\-8,\s0 that is, no \*(L"character\*(R" of the input string must have any value > 255, as \s-1UTF\-8\s0 does not allow that. .Sp The \f(CW\*(C`utf8\*(C'\fR flag therefore switches between two modes: disabled means you will get a Unicode string in Perl, enabled means you get an \s-1UTF\-8\s0 encoded octet/binary string in Perl. .ie n .IP """latin1"" or ""ascii"" flags enabled" 4 .el .IP "\f(CWlatin1\fR or \f(CWascii\fR flags enabled" 4 .IX Item "latin1 or ascii flags enabled" With \f(CW\*(C`latin1\*(C'\fR (or \f(CW\*(C`ascii\*(C'\fR) enabled, \f(CW\*(C`encode\*(C'\fR will escape characters with ordinal values > 255 (> 127 with \f(CW\*(C`ascii\*(C'\fR) and encode the remaining characters as specified by the \f(CW\*(C`utf8\*(C'\fR flag. .Sp If \f(CW\*(C`utf8\*(C'\fR is disabled, then the result is also correctly encoded in those character sets (as both are proper subsets of Unicode, meaning that a Unicode string with all character values < 256 is the same thing as a \&\s-1ISO\-8859\-1\s0 string, and a Unicode string with all character values < 128 is the same thing as an \s-1ASCII\s0 string in Perl). .Sp If \f(CW\*(C`utf8\*(C'\fR is enabled, you still get a correct UTF\-8\-encoded string, regardless of these flags, just some more characters will be escaped using \&\f(CW\*(C`\euXXXX\*(C'\fR then before. .Sp Note that \s-1ISO\-8859\-1\-\s0\fIencoded\fR strings are not compatible with \s-1UTF\-8\s0 encoding, while ASCII-encoded strings are. That is because the \s-1ISO\-8859\-1\s0 encoding is \s-1NOT\s0 a subset of \s-1UTF\-8\s0 (despite the \s-1ISO\-8859\-1\s0 \fIcodeset\fR being a subset of Unicode), while \s-1ASCII\s0 is. .Sp Surprisingly, \f(CW\*(C`decode\*(C'\fR will ignore these flags and so treat all input values as governed by the \f(CW\*(C`utf8\*(C'\fR flag. If it is disabled, this allows you to decode \s-1ISO\-8859\-1\-\s0 and ASCII-encoded strings, as both strict subsets of Unicode. If it is enabled, you can correctly decode \s-1UTF\-8\s0 encoded strings. .Sp So neither \f(CW\*(C`latin1\*(C'\fR nor \f(CW\*(C`ascii\*(C'\fR are incompatible with the \f(CW\*(C`utf8\*(C'\fR flag \- they only govern when the \s-1JSON\s0 output engine escapes a character or not. .Sp The main use for \f(CW\*(C`latin1\*(C'\fR is to relatively efficiently store binary data as \s-1JSON,\s0 at the expense of breaking compatibility with most \s-1JSON\s0 decoders. .Sp The main use for \f(CW\*(C`ascii\*(C'\fR is to force the output to not contain characters with values > 127, which means you can interpret the resulting string as \s-1UTF\-8, ISO\-8859\-1, ASCII, KOI8\-R\s0 or most about any character set and 8\-bit\-encoding, and still get the same data structure back. This is useful when your channel for \s-1JSON\s0 transfer is not 8\-bit clean or the encoding might be mangled in between (e.g. in mail), and works because \s-1ASCII\s0 is a proper subset of most 8\-bit and multibyte encodings in use in the world. .SH "BUGS" .IX Header "BUGS" Please report bugs on a specific behavior of this module to \s-1RT\s0 or GitHub issues (preferred): .PP <https://github.com/makamaka/JSON\-PP/issues> .PP <https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON\-PP> .PP As for new features and requests to change common behaviors, please ask the author of \s-1JSON::XS\s0 (Marc Lehmann, <schmorp[at]schmorp.de>) first, by email (important!), to keep compatibility among \s-1JSON\s0.pm backends. .PP Generally speaking, if you need something special for you, you are advised to create a new module, maybe based on JSON::Tiny, which is smaller and written in a much cleaner way than this module. .SH "SEE ALSO" .IX Header "SEE ALSO" The \fIjson_pp\fR command line utility for quick experiments. .PP \&\s-1JSON::XS\s0, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives. \&\s-1JSON\s0 and JSON::MaybeXS for easy migration. .PP JSON::backportPP::Compat5005 and JSON::backportPP::Compat5006 for older perl users. .PP \&\s-1RFC4627\s0 (<http://www.ietf.org/rfc/rfc4627.txt>) .PP \&\s-1RFC7159\s0 (<http://www.ietf.org/rfc/rfc7159.txt>) .PP \&\s-1RFC8259\s0 (<http://www.ietf.org/rfc/rfc8259.txt>) .SH "AUTHOR" .IX Header "AUTHOR" Makamaka Hannyaharamitu, <makamaka[at]cpan.org> .SH "CURRENT MAINTAINER" .IX Header "CURRENT MAINTAINER" Kenichi Ishigaki, <ishigaki[at]cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2007\-2016 by Makamaka Hannyaharamitu .PP Most of the documentation is taken from \s-1JSON::XS\s0 by Marc Lehmann .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[� � � % man3/JSON::backportPP::Compat5006.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "JSON::backportPP::Compat5006 3" .TH JSON::backportPP::Compat5006 3 "2021-01-17" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::PP56 \- Helper module in using JSON::PP in Perl 5.6 .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1JSON::PP\s0 calls internally. .SH "AUTHOR" .IX Header "AUTHOR" Makamaka Hannyaharamitu, <makamaka[at]cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2007\-2012 by Makamaka Hannyaharamitu .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[�}ZT " man3/JSON::backportPP::Boolean.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "JSON::backportPP::Boolean 3" .TH JSON::backportPP::Boolean 3 "2022-10-08" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::PP::Boolean \- dummy module providing JSON::PP::Boolean .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # do not "use" yourself .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module exists only to provide overload resolution for Storable and similar modules. See \&\s-1JSON::PP\s0 for more info about this class. .SH "AUTHOR" .IX Header "AUTHOR" This idea is from JSON::XS::Boolean written by Marc Lehmann <schmorp[at]schmorp.de> .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[ arch/auto/JSON/.existsnu �[��� PK � �[+�d� � ! lib/JSON/backportPP/Compat5006.pmnu ��6�$ package # This is JSON::backportPP JSON::backportPP56; use 5.006; use strict; my @properties; $JSON::PP56::VERSION = '1.08'; BEGIN { sub utf8::is_utf8 { my $len = length $_[0]; # char length { use bytes; # byte length; return $len != length $_[0]; # if !=, UTF8-flagged on. } } sub utf8::upgrade { ; # noop; } sub utf8::downgrade ($;$) { return 1 unless ( utf8::is_utf8( $_[0] ) ); if ( _is_valid_utf8( $_[0] ) ) { my $downgrade; for my $c ( unpack( "U*", $_[0] ) ) { if ( $c < 256 ) { $downgrade .= pack("C", $c); } else { $downgrade .= pack("U", $c); } } $_[0] = $downgrade; return 1; } else { Carp::croak("Wide character in subroutine entry") unless ( $_[1] ); 0; } } sub utf8::encode ($) { # UTF8 flag off if ( utf8::is_utf8( $_[0] ) ) { $_[0] = pack( "C*", unpack( "C*", $_[0] ) ); } else { $_[0] = pack( "U*", unpack( "C*", $_[0] ) ); $_[0] = pack( "C*", unpack( "C*", $_[0] ) ); } } sub utf8::decode ($) { # UTF8 flag on if ( _is_valid_utf8( $_[0] ) ) { utf8::downgrade( $_[0] ); $_[0] = pack( "U*", unpack( "U*", $_[0] ) ); } } *JSON::PP::JSON_PP_encode_ascii = \&_encode_ascii; *JSON::PP::JSON_PP_encode_latin1 = \&_encode_latin1; *JSON::PP::JSON_PP_decode_surrogates = \&JSON::PP::_decode_surrogates; *JSON::PP::JSON_PP_decode_unicode = \&JSON::PP::_decode_unicode; unless ( defined &B::SVp_NOK ) { # missing in B module. eval q{ sub B::SVp_NOK () { 0x02000000; } }; } } sub _encode_ascii { join('', map { $_ <= 127 ? chr($_) : $_ <= 65535 ? sprintf('\u%04x', $_) : sprintf('\u%x\u%x', JSON::PP::_encode_surrogates($_)); } _unpack_emu($_[0]) ); } sub _encode_latin1 { join('', map { $_ <= 255 ? chr($_) : $_ <= 65535 ? sprintf('\u%04x', $_) : sprintf('\u%x\u%x', JSON::PP::_encode_surrogates($_)); } _unpack_emu($_[0]) ); } sub _unpack_emu { # for Perl 5.6 unpack warnings return !utf8::is_utf8($_[0]) ? unpack('C*', $_[0]) : _is_valid_utf8($_[0]) ? unpack('U*', $_[0]) : unpack('C*', $_[0]); } sub _is_valid_utf8 { my $str = $_[0]; my $is_utf8; while ($str =~ /(?: ( [\x00-\x7F] |[\xC2-\xDF][\x80-\xBF] |[\xE0][\xA0-\xBF][\x80-\xBF] |[\xE1-\xEC][\x80-\xBF][\x80-\xBF] |[\xED][\x80-\x9F][\x80-\xBF] |[\xEE-\xEF][\x80-\xBF][\x80-\xBF] |[\xF0][\x90-\xBF][\x80-\xBF][\x80-\xBF] |[\xF1-\xF3][\x80-\xBF][\x80-\xBF][\x80-\xBF] |[\xF4][\x80-\x8F][\x80-\xBF][\x80-\xBF] ) | (.) )/xg) { if (defined $1) { $is_utf8 = 1 if (!defined $is_utf8); } else { $is_utf8 = 0 if (!defined $is_utf8); if ($is_utf8) { # eventually, not utf8 return; } } } return $is_utf8; } 1; __END__ =pod =head1 NAME JSON::PP56 - Helper module in using JSON::PP in Perl 5.6 =head1 DESCRIPTION JSON::PP calls internally. =head1 AUTHOR Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt> =head1 COPYRIGHT AND LICENSE Copyright 2007-2012 by Makamaka Hannyaharamitu This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[{ ��� � lib/JSON/backportPP/Boolean.pmnu ��6�$ package # This is JSON::backportPP JSON::PP::Boolean; use strict; require overload; local $^W; overload::unimport('overload', qw(0+ ++ -- fallback)); overload::import('overload', "0+" => sub { ${$_[0]} }, "++" => sub { $_[0] = ${$_[0]} + 1 }, "--" => sub { $_[0] = ${$_[0]} - 1 }, fallback => 1, ); $JSON::backportPP::Boolean::VERSION = '4.12'; 1; __END__ =head1 NAME JSON::PP::Boolean - dummy module providing JSON::PP::Boolean =head1 SYNOPSIS # do not "use" yourself =head1 DESCRIPTION This module exists only to provide overload resolution for Storable and similar modules. See L<JSON::PP> for more info about this class. =head1 AUTHOR This idea is from L<JSON::XS::Boolean> written by Marc Lehmann <schmorp[at]schmorp.de> =head1 LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[6! �� � ! lib/JSON/backportPP/Compat5005.pmnu ��6�$ package # This is JSON::backportPP JSON::backportPP5005; use 5.005; use strict; my @properties; $JSON::PP5005::VERSION = '1.10'; BEGIN { sub utf8::is_utf8 { 0; # It is considered that UTF8 flag off for Perl 5.005. } sub utf8::upgrade { } sub utf8::downgrade { 1; # must always return true. } sub utf8::encode { } sub utf8::decode { } *JSON::PP::JSON_PP_encode_ascii = \&_encode_ascii; *JSON::PP::JSON_PP_encode_latin1 = \&_encode_latin1; *JSON::PP::JSON_PP_decode_surrogates = \&_decode_surrogates; *JSON::PP::JSON_PP_decode_unicode = \&_decode_unicode; # missing in B module. sub B::SVp_IOK () { 0x01000000; } sub B::SVp_NOK () { 0x02000000; } sub B::SVp_POK () { 0x04000000; } $INC{'bytes.pm'} = 1; # dummy } sub _encode_ascii { join('', map { $_ <= 127 ? chr($_) : sprintf('\u%04x', $_) } unpack('C*', $_[0]) ); } sub _encode_latin1 { join('', map { chr($_) } unpack('C*', $_[0]) ); } sub _decode_surrogates { # from http://homepage1.nifty.com/nomenclator/unicode/ucs_utf.htm my $uni = 0x10000 + (hex($_[0]) - 0xD800) * 0x400 + (hex($_[1]) - 0xDC00); # from perlunicode my $bit = unpack('B32', pack('N', $uni)); if ( $bit =~ /^00000000000(...)(......)(......)(......)$/ ) { my ($w, $x, $y, $z) = ($1, $2, $3, $4); return pack('B*', sprintf('11110%s10%s10%s10%s', $w, $x, $y, $z)); } else { Carp::croak("Invalid surrogate pair"); } } sub _decode_unicode { my ($u) = @_; my ($utf8bit); if ( $u =~ /^00([89a-f][0-9a-f])$/i ) { # 0x80-0xff return pack( 'H2', $1 ); } my $bit = unpack("B*", pack("H*", $u)); if ( $bit =~ /^00000(.....)(......)$/ ) { $utf8bit = sprintf('110%s10%s', $1, $2); } elsif ( $bit =~ /^(....)(......)(......)$/ ) { $utf8bit = sprintf('1110%s10%s10%s', $1, $2, $3); } else { Carp::croak("Invalid escaped unicode"); } return pack('B*', $utf8bit); } sub JSON::PP::incr_text { $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new; if ( $_[0]->{_incr_parser}->{incr_parsing} ) { Carp::croak("incr_text can not be called when the incremental parser already started parsing"); } $_[0]->{_incr_parser}->{incr_text} = $_[1] if ( @_ > 1 ); $_[0]->{_incr_parser}->{incr_text}; } 1; __END__ =pod =head1 NAME JSON::PP5005 - Helper module in using JSON::PP in Perl 5.005 =head1 DESCRIPTION JSON::PP calls internally. =head1 AUTHOR Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt> =head1 COPYRIGHT AND LICENSE Copyright 2007-2012 by Makamaka Hannyaharamitu This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[9� ��� �� lib/JSON/backportPP.pmnu ��6�$ package # This is JSON::backportPP JSON::PP; # JSON-2.0 use 5.005; use strict; use Exporter (); BEGIN { @JSON::backportPP::ISA = ('Exporter') } use overload (); use JSON::backportPP::Boolean; use Carp (); #use Devel::Peek; $JSON::backportPP::VERSION = '4.12'; @JSON::PP::EXPORT = qw(encode_json decode_json from_json to_json); # instead of hash-access, i tried index-access for speed. # but this method is not faster than what i expected. so it will be changed. use constant P_ASCII => 0; use constant P_LATIN1 => 1; use constant P_UTF8 => 2; use constant P_INDENT => 3; use constant P_CANONICAL => 4; use constant P_SPACE_BEFORE => 5; use constant P_SPACE_AFTER => 6; use constant P_ALLOW_NONREF => 7; use constant P_SHRINK => 8; use constant P_ALLOW_BLESSED => 9; use constant P_CONVERT_BLESSED => 10; use constant P_RELAXED => 11; use constant P_LOOSE => 12; use constant P_ALLOW_BIGNUM => 13; use constant P_ALLOW_BAREKEY => 14; use constant P_ALLOW_SINGLEQUOTE => 15; use constant P_ESCAPE_SLASH => 16; use constant P_AS_NONBLESSED => 17; use constant P_ALLOW_UNKNOWN => 18; use constant P_ALLOW_TAGS => 19; use constant OLD_PERL => $] < 5.008 ? 1 : 0; use constant USE_B => $ENV{PERL_JSON_PP_USE_B} || 0; use constant CORE_BOOL => defined &builtin::is_bool; my $invalid_char_re; BEGIN { $invalid_char_re = "["; for my $i (0 .. 0x01F, 0x22, 0x5c) { # '/' is ok $invalid_char_re .= quotemeta chr utf8::unicode_to_native($i); } $invalid_char_re = qr/$invalid_char_re]/; } BEGIN { if (USE_B) { require B; } } BEGIN { my @xs_compati_bit_properties = qw( latin1 ascii utf8 indent canonical space_before space_after allow_nonref shrink allow_blessed convert_blessed relaxed allow_unknown allow_tags ); my @pp_bit_properties = qw( allow_singlequote allow_bignum loose allow_barekey escape_slash as_nonblessed ); # Perl version check, Unicode handling is enabled? # Helper module sets @JSON::PP::_properties. if ( OLD_PERL ) { my $helper = $] >= 5.006 ? 'JSON::backportPP::Compat5006' : 'JSON::backportPP::Compat5005'; eval qq| require $helper |; if ($@) { Carp::croak $@; } } for my $name (@xs_compati_bit_properties, @pp_bit_properties) { my $property_id = 'P_' . uc($name); eval qq/ sub $name { my \$enable = defined \$_[1] ? \$_[1] : 1; if (\$enable) { \$_[0]->{PROPS}->[$property_id] = 1; } else { \$_[0]->{PROPS}->[$property_id] = 0; } \$_[0]; } sub get_$name { \$_[0]->{PROPS}->[$property_id] ? 1 : ''; } /; } } # Functions my $JSON; # cache sub encode_json ($) { # encode ($JSON ||= __PACKAGE__->new->utf8)->encode(@_); } sub decode_json { # decode ($JSON ||= __PACKAGE__->new->utf8)->decode(@_); } # Obsoleted sub to_json($) { Carp::croak ("JSON::PP::to_json has been renamed to encode_json."); } sub from_json($) { Carp::croak ("JSON::PP::from_json has been renamed to decode_json."); } # Methods sub new { my $class = shift; my $self = { max_depth => 512, max_size => 0, indent_length => 3, }; $self->{PROPS}[P_ALLOW_NONREF] = 1; bless $self, $class; } sub encode { return $_[0]->PP_encode_json($_[1]); } sub decode { return $_[0]->PP_decode_json($_[1], 0x00000000); } sub decode_prefix { return $_[0]->PP_decode_json($_[1], 0x00000001); } # accessor # pretty printing sub pretty { my ($self, $v) = @_; my $enable = defined $v ? $v : 1; if ($enable) { # indent_length(3) for JSON::XS compatibility $self->indent(1)->space_before(1)->space_after(1); } else { $self->indent(0)->space_before(0)->space_after(0); } $self; } # etc sub max_depth { my $max = defined $_[1] ? $_[1] : 0x80000000; $_[0]->{max_depth} = $max; $_[0]; } sub get_max_depth { $_[0]->{max_depth}; } sub max_size { my $max = defined $_[1] ? $_[1] : 0; $_[0]->{max_size} = $max; $_[0]; } sub get_max_size { $_[0]->{max_size}; } sub boolean_values { my $self = shift; if (@_) { my ($false, $true) = @_; $self->{false} = $false; $self->{true} = $true; if (CORE_BOOL) { BEGIN { CORE_BOOL and warnings->unimport(qw(experimental::builtin)) } if (builtin::is_bool($true) && builtin::is_bool($false) && $true && !$false) { $self->{core_bools} = !!1; } else { delete $self->{core_bools}; } } } else { delete $self->{false}; delete $self->{true}; delete $self->{core_bools}; } return $self; } sub core_bools { my $self = shift; my $core_bools = defined $_[0] ? $_[0] : 1; if ($core_bools) { $self->{true} = !!1; $self->{false} = !!0; $self->{core_bools} = !!1; } else { $self->{true} = $JSON::PP::true; $self->{false} = $JSON::PP::false; $self->{core_bools} = !!0; } return $self; } sub get_core_bools { my $self = shift; return !!$self->{core_bools}; } sub unblessed_bool { my $self = shift; return $self->core_bools(@_); } sub get_unblessed_bool { my $self = shift; return $self->get_core_bools(@_); } sub get_boolean_values { my $self = shift; if (exists $self->{true} and exists $self->{false}) { return @$self{qw/false true/}; } return; } sub filter_json_object { if (defined $_[1] and ref $_[1] eq 'CODE') { $_[0]->{cb_object} = $_[1]; } else { delete $_[0]->{cb_object}; } $_[0]->{F_HOOK} = ($_[0]->{cb_object} or $_[0]->{cb_sk_object}) ? 1 : 0; $_[0]; } sub filter_json_single_key_object { if (@_ == 1 or @_ > 3) { Carp::croak("Usage: JSON::PP::filter_json_single_key_object(self, key, callback = undef)"); } if (defined $_[2] and ref $_[2] eq 'CODE') { $_[0]->{cb_sk_object}->{$_[1]} = $_[2]; } else { delete $_[0]->{cb_sk_object}->{$_[1]}; delete $_[0]->{cb_sk_object} unless %{$_[0]->{cb_sk_object} || {}}; } $_[0]->{F_HOOK} = ($_[0]->{cb_object} or $_[0]->{cb_sk_object}) ? 1 : 0; $_[0]; } sub indent_length { if (!defined $_[1] or $_[1] > 15 or $_[1] < 0) { Carp::carp "The acceptable range of indent_length() is 0 to 15."; } else { $_[0]->{indent_length} = $_[1]; } $_[0]; } sub get_indent_length { $_[0]->{indent_length}; } sub sort_by { $_[0]->{sort_by} = defined $_[1] ? $_[1] : 1; $_[0]; } sub allow_bigint { Carp::carp("allow_bigint() is obsoleted. use allow_bignum() instead."); $_[0]->allow_bignum; } ############################### ### ### Perl => JSON ### { # Convert my $max_depth; my $indent; my $ascii; my $latin1; my $utf8; my $space_before; my $space_after; my $canonical; my $allow_blessed; my $convert_blessed; my $indent_length; my $escape_slash; my $bignum; my $as_nonblessed; my $allow_tags; my $depth; my $indent_count; my $keysort; sub PP_encode_json { my $self = shift; my $obj = shift; $indent_count = 0; $depth = 0; my $props = $self->{PROPS}; ($ascii, $latin1, $utf8, $indent, $canonical, $space_before, $space_after, $allow_blessed, $convert_blessed, $escape_slash, $bignum, $as_nonblessed, $allow_tags) = @{$props}[P_ASCII .. P_SPACE_AFTER, P_ALLOW_BLESSED, P_CONVERT_BLESSED, P_ESCAPE_SLASH, P_ALLOW_BIGNUM, P_AS_NONBLESSED, P_ALLOW_TAGS]; ($max_depth, $indent_length) = @{$self}{qw/max_depth indent_length/}; $keysort = $canonical ? sub { $a cmp $b } : undef; if ($self->{sort_by}) { $keysort = ref($self->{sort_by}) eq 'CODE' ? $self->{sort_by} : $self->{sort_by} =~ /\D+/ ? $self->{sort_by} : sub { $a cmp $b }; } encode_error("hash- or arrayref expected (not a simple scalar, use allow_nonref to allow this)") if(!ref $obj and !$props->[ P_ALLOW_NONREF ]); my $str = $self->object_to_json($obj); $str .= "\n" if ( $indent ); # JSON::XS 2.26 compatible return $str; } sub object_to_json { my ($self, $obj) = @_; my $type = ref($obj); if($type eq 'HASH'){ return $self->hash_to_json($obj); } elsif($type eq 'ARRAY'){ return $self->array_to_json($obj); } elsif ($type) { # blessed object? if (blessed($obj)) { return $self->value_to_json($obj) if ( $obj->isa('JSON::PP::Boolean') ); if ( $allow_tags and $obj->can('FREEZE') ) { my $obj_class = ref $obj || $obj; $obj = bless $obj, $obj_class; my @results = $obj->FREEZE('JSON'); if ( @results and ref $results[0] ) { if ( refaddr( $obj ) eq refaddr( $results[0] ) ) { encode_error( sprintf( "%s::FREEZE method returned same object as was passed instead of a new one", ref $obj ) ); } } return '("'.$obj_class.'")['.join(',', @results).']'; } if ( $convert_blessed and $obj->can('TO_JSON') ) { my $result = $obj->TO_JSON(); if ( defined $result and ref( $result ) ) { if ( refaddr( $obj ) eq refaddr( $result ) ) { encode_error( sprintf( "%s::TO_JSON method returned same object as was passed instead of a new one", ref $obj ) ); } } return $self->object_to_json( $result ); } return "$obj" if ( $bignum and _is_bignum($obj) ); if ($allow_blessed) { return $self->blessed_to_json($obj) if ($as_nonblessed); # will be removed. return 'null'; } encode_error( sprintf("encountered object '%s', but neither allow_blessed, convert_blessed nor allow_tags settings are enabled (or TO_JSON/FREEZE method missing)", $obj) ); } else { return $self->value_to_json($obj); } } else{ return $self->value_to_json($obj); } } sub hash_to_json { my ($self, $obj) = @_; my @res; encode_error("json text or perl structure exceeds maximum nesting level (max_depth set too low?)") if (++$depth > $max_depth); my ($pre, $post) = $indent ? $self->_up_indent() : ('', ''); my $del = ($space_before ? ' ' : '') . ':' . ($space_after ? ' ' : ''); for my $k ( _sort( $obj ) ) { if ( OLD_PERL ) { utf8::decode($k) } # key for Perl 5.6 / be optimized push @res, $self->string_to_json( $k ) . $del . ( ref $obj->{$k} ? $self->object_to_json( $obj->{$k} ) : $self->value_to_json( $obj->{$k} ) ); } --$depth; $self->_down_indent() if ($indent); return '{}' unless @res; return '{' . $pre . join( ",$pre", @res ) . $post . '}'; } sub array_to_json { my ($self, $obj) = @_; my @res; encode_error("json text or perl structure exceeds maximum nesting level (max_depth set too low?)") if (++$depth > $max_depth); my ($pre, $post) = $indent ? $self->_up_indent() : ('', ''); for my $v (@$obj){ push @res, ref($v) ? $self->object_to_json($v) : $self->value_to_json($v); } --$depth; $self->_down_indent() if ($indent); return '[]' unless @res; return '[' . $pre . join( ",$pre", @res ) . $post . ']'; } sub _looks_like_number { my $value = shift; if (USE_B) { my $b_obj = B::svref_2object(\$value); my $flags = $b_obj->FLAGS; return 1 if $flags & ( B::SVp_IOK() | B::SVp_NOK() ) and !( $flags & B::SVp_POK() ); return; } else { no warnings 'numeric'; # if the utf8 flag is on, it almost certainly started as a string return if utf8::is_utf8($value); # detect numbers # string & "" -> "" # number & "" -> 0 (with warning) # nan and inf can detect as numbers, so check with * 0 return unless length((my $dummy = "") & $value); return unless 0 + $value eq $value; return 1 if $value * 0 == 0; return -1; # inf/nan } } sub value_to_json { my ($self, $value) = @_; return 'null' if(!defined $value); my $type = ref($value); if (!$type) { BEGIN { CORE_BOOL and warnings->unimport('experimental::builtin') } if (CORE_BOOL && builtin::is_bool($value)) { return $value ? 'true' : 'false'; } elsif (_looks_like_number($value)) { return $value; } return $self->string_to_json($value); } elsif( blessed($value) and $value->isa('JSON::PP::Boolean') ){ return $$value == 1 ? 'true' : 'false'; } else { if ((overload::StrVal($value) =~ /=(\w+)/)[0]) { return $self->value_to_json("$value"); } if ($type eq 'SCALAR' and defined $$value) { return $$value eq '1' ? 'true' : $$value eq '0' ? 'false' : $self->{PROPS}->[ P_ALLOW_UNKNOWN ] ? 'null' : encode_error("cannot encode reference to scalar"); } if ( $self->{PROPS}->[ P_ALLOW_UNKNOWN ] ) { return 'null'; } else { if ( $type eq 'SCALAR' or $type eq 'REF' ) { encode_error("cannot encode reference to scalar"); } else { encode_error("encountered $value, but JSON can only represent references to arrays or hashes"); } } } } my %esc = ( "\n" => '\n', "\r" => '\r', "\t" => '\t', "\f" => '\f', "\b" => '\b', "\"" => '\"', "\\" => '\\\\', "\'" => '\\\'', ); sub string_to_json { my ($self, $arg) = @_; $arg =~ s/(["\\\n\r\t\f\b])/$esc{$1}/g; $arg =~ s/\//\\\//g if ($escape_slash); # On ASCII platforms, matches [\x00-\x08\x0b\x0e-\x1f] $arg =~ s/([^\n\t\c?[:^cntrl:][:^ascii:]])/'\\u00' . unpack('H2', $1)/eg; if ($ascii) { $arg = JSON_PP_encode_ascii($arg); } if ($latin1) { $arg = JSON_PP_encode_latin1($arg); } if ($utf8) { utf8::encode($arg); } return '"' . $arg . '"'; } sub blessed_to_json { my $reftype = reftype($_[1]) || ''; if ($reftype eq 'HASH') { return $_[0]->hash_to_json($_[1]); } elsif ($reftype eq 'ARRAY') { return $_[0]->array_to_json($_[1]); } else { return 'null'; } } sub encode_error { my $error = shift; Carp::croak "$error"; } sub _sort { defined $keysort ? (sort $keysort (keys %{$_[0]})) : keys %{$_[0]}; } sub _up_indent { my $self = shift; my $space = ' ' x $indent_length; my ($pre,$post) = ('',''); $post = "\n" . $space x $indent_count; $indent_count++; $pre = "\n" . $space x $indent_count; return ($pre,$post); } sub _down_indent { $indent_count--; } sub PP_encode_box { { depth => $depth, indent_count => $indent_count, }; } } # Convert sub _encode_ascii { join('', map { chr($_) =~ /[[:ascii:]]/ ? chr($_) : $_ <= 65535 ? sprintf('\u%04x', $_) : sprintf('\u%x\u%x', _encode_surrogates($_)); } unpack('U*', $_[0]) ); } sub _encode_latin1 { join('', map { $_ <= 255 ? chr($_) : $_ <= 65535 ? sprintf('\u%04x', $_) : sprintf('\u%x\u%x', _encode_surrogates($_)); } unpack('U*', $_[0]) ); } sub _encode_surrogates { # from perlunicode my $uni = $_[0] - 0x10000; return ($uni / 0x400 + 0xD800, $uni % 0x400 + 0xDC00); } sub _is_bignum { $_[0]->isa('Math::BigInt') or $_[0]->isa('Math::BigFloat'); } # # JSON => Perl # my $max_intsize; BEGIN { my $checkint = 1111; for my $d (5..64) { $checkint .= 1; my $int = eval qq| $checkint |; if ($int =~ /[eE]/) { $max_intsize = $d - 1; last; } } } { # PARSE my %escapes = ( # by Jeremy Muhlich <jmuhlich [at] bitflood.org> b => "\b", t => "\t", n => "\n", f => "\f", r => "\r", '\\' => '\\', '"' => '"', '/' => '/', ); my $text; # json data my $at; # offset my $ch; # first character my $len; # text length (changed according to UTF8 or NON UTF8) # INTERNAL my $depth; # nest counter my $encoding; # json text encoding my $is_valid_utf8; # temp variable my $utf8_len; # utf8 byte length # FLAGS my $utf8; # must be utf8 my $max_depth; # max nest number of objects and arrays my $max_size; my $relaxed; my $cb_object; my $cb_sk_object; my $F_HOOK; my $allow_bignum; # using Math::BigInt/BigFloat my $singlequote; # loosely quoting my $loose; # my $allow_barekey; # bareKey my $allow_tags; my $alt_true; my $alt_false; sub _detect_utf_encoding { my $text = shift; my @octets = unpack('C4', $text); return 'unknown' unless defined $octets[3]; return ( $octets[0] and $octets[1]) ? 'UTF-8' : (!$octets[0] and $octets[1]) ? 'UTF-16BE' : (!$octets[0] and !$octets[1]) ? 'UTF-32BE' : ( $octets[2] ) ? 'UTF-16LE' : (!$octets[2] ) ? 'UTF-32LE' : 'unknown'; } sub PP_decode_json { my ($self, $want_offset); ($self, $text, $want_offset) = @_; ($at, $ch, $depth) = (0, '', 0); if ( !defined $text or ref $text ) { decode_error("malformed JSON string, neither array, object, number, string or atom"); } my $props = $self->{PROPS}; ($utf8, $relaxed, $loose, $allow_bignum, $allow_barekey, $singlequote, $allow_tags) = @{$props}[P_UTF8, P_RELAXED, P_LOOSE .. P_ALLOW_SINGLEQUOTE, P_ALLOW_TAGS]; ($alt_true, $alt_false) = @$self{qw/true false/}; if ( $utf8 ) { $encoding = _detect_utf_encoding($text); if ($encoding ne 'UTF-8' and $encoding ne 'unknown') { require Encode; Encode::from_to($text, $encoding, 'utf-8'); } else { utf8::downgrade( $text, 1 ) or Carp::croak("Wide character in subroutine entry"); } } else { utf8::encode( $text ); } $len = length $text; ($max_depth, $max_size, $cb_object, $cb_sk_object, $F_HOOK) = @{$self}{qw/max_depth max_size cb_object cb_sk_object F_HOOK/}; if ($max_size > 1) { use bytes; my $bytes = length $text; decode_error( sprintf("attempted decode of JSON text of %s bytes size, but max_size is set to %s" , $bytes, $max_size), 1 ) if ($bytes > $max_size); } white(); # remove head white space decode_error("malformed JSON string, neither array, object, number, string or atom") unless defined $ch; # Is there a first character for JSON structure? my $result = value(); if ( !$props->[ P_ALLOW_NONREF ] and !ref $result ) { decode_error( 'JSON text must be an object or array (but found number, string, true, false or null,' . ' use allow_nonref to allow this)', 1); } Carp::croak('something wrong.') if $len < $at; # we won't arrive here. my $consumed = defined $ch ? $at - 1 : $at; # consumed JSON text length white(); # remove tail white space return ( $result, $consumed ) if $want_offset; # all right if decode_prefix decode_error("garbage after JSON object") if defined $ch; $result; } sub next_chr { return $ch = undef if($at >= $len); $ch = substr($text, $at++, 1); } sub value { white(); return if(!defined $ch); return object() if($ch eq '{'); return array() if($ch eq '['); return tag() if($ch eq '('); return string() if($ch eq '"' or ($singlequote and $ch eq "'")); return number() if($ch =~ /[0-9]/ or $ch eq '-'); return word(); } sub string { my $utf16; my $is_utf8; ($is_valid_utf8, $utf8_len) = ('', 0); my $s = ''; # basically UTF8 flag on if($ch eq '"' or ($singlequote and $ch eq "'")){ my $boundChar = $ch; OUTER: while( defined(next_chr()) ){ if($ch eq $boundChar){ next_chr(); if ($utf16) { decode_error("missing low surrogate character in surrogate pair"); } utf8::decode($s) if($is_utf8); return $s; } elsif($ch eq '\\'){ next_chr(); if(exists $escapes{$ch}){ $s .= $escapes{$ch}; } elsif($ch eq 'u'){ # UNICODE handling my $u = ''; for(1..4){ $ch = next_chr(); last OUTER if($ch !~ /[0-9a-fA-F]/); $u .= $ch; } # U+D800 - U+DBFF if ($u =~ /^[dD][89abAB][0-9a-fA-F]{2}/) { # UTF-16 high surrogate? $utf16 = $u; } # U+DC00 - U+DFFF elsif ($u =~ /^[dD][c-fC-F][0-9a-fA-F]{2}/) { # UTF-16 low surrogate? unless (defined $utf16) { decode_error("missing high surrogate character in surrogate pair"); } $is_utf8 = 1; $s .= JSON_PP_decode_surrogates($utf16, $u) || next; $utf16 = undef; } else { if (defined $utf16) { decode_error("surrogate pair expected"); } my $hex = hex( $u ); if ( chr $u =~ /[[:^ascii:]]/ ) { $is_utf8 = 1; $s .= JSON_PP_decode_unicode($u) || next; } else { $s .= chr $hex; } } } else{ unless ($loose) { $at -= 2; decode_error('illegal backslash escape sequence in string'); } $s .= $ch; } } else{ if ( $ch =~ /[[:^ascii:]]/ ) { unless( $ch = is_valid_utf8($ch) ) { $at -= 1; decode_error("malformed UTF-8 character in JSON string"); } else { $at += $utf8_len - 1; } $is_utf8 = 1; } if (!$loose) { if ($ch =~ $invalid_char_re) { # '/' ok if (!$relaxed or $ch ne "\t") { $at--; decode_error(sprintf "invalid character 0x%X" . " encountered while parsing JSON string", ord $ch); } } } $s .= $ch; } } } decode_error("unexpected end of string while parsing JSON string"); } sub white { while( defined $ch ){ if($ch eq '' or $ch =~ /\A[ \t\r\n]\z/){ next_chr(); } elsif($relaxed and $ch eq '/'){ next_chr(); if(defined $ch and $ch eq '/'){ 1 while(defined(next_chr()) and $ch ne "\n" and $ch ne "\r"); } elsif(defined $ch and $ch eq '*'){ next_chr(); while(1){ if(defined $ch){ if($ch eq '*'){ if(defined(next_chr()) and $ch eq '/'){ next_chr(); last; } } else{ next_chr(); } } else{ decode_error("Unterminated comment"); } } next; } else{ $at--; decode_error("malformed JSON string, neither array, object, number, string or atom"); } } else{ if ($relaxed and $ch eq '#') { # correctly? pos($text) = $at; $text =~ /\G([^\n]*(?:\r\n|\r|\n|$))/g; $at = pos($text); next_chr; next; } last; } } } sub array { my $a = $_[0] || []; # you can use this code to use another array ref object. decode_error('json text or perl structure exceeds maximum nesting level (max_depth set too low?)') if (++$depth > $max_depth); next_chr(); white(); if(defined $ch and $ch eq ']'){ --$depth; next_chr(); return $a; } else { while(defined($ch)){ push @$a, value(); white(); if (!defined $ch) { last; } if($ch eq ']'){ --$depth; next_chr(); return $a; } if($ch ne ','){ last; } next_chr(); white(); if ($relaxed and $ch eq ']') { --$depth; next_chr(); return $a; } } } $at-- if defined $ch and $ch ne ''; decode_error(", or ] expected while parsing array"); } sub tag { decode_error('malformed JSON string, neither array, object, number, string or atom') unless $allow_tags; next_chr(); white(); my $tag = value(); return unless defined $tag; decode_error('malformed JSON string, (tag) must be a string') if ref $tag; white(); if (!defined $ch or $ch ne ')') { decode_error(') expected after tag'); } next_chr(); white(); my $val = value(); return unless defined $val; decode_error('malformed JSON string, tag value must be an array') unless ref $val eq 'ARRAY'; if (!eval { $tag->can('THAW') }) { decode_error('cannot decode perl-object (package does not exist)') if $@; decode_error('cannot decode perl-object (package does not have a THAW method)'); } $tag->THAW('JSON', @$val); } sub object { my $o = $_[0] || {}; # you can use this code to use another hash ref object. my $k; decode_error('json text or perl structure exceeds maximum nesting level (max_depth set too low?)') if (++$depth > $max_depth); next_chr(); white(); if(defined $ch and $ch eq '}'){ --$depth; next_chr(); if ($F_HOOK) { return _json_object_hook($o); } return $o; } else { while (defined $ch) { $k = ($allow_barekey and $ch ne '"' and $ch ne "'") ? bareKey() : string(); white(); if(!defined $ch or $ch ne ':'){ $at--; decode_error("':' expected"); } next_chr(); $o->{$k} = value(); white(); last if (!defined $ch); if($ch eq '}'){ --$depth; next_chr(); if ($F_HOOK) { return _json_object_hook($o); } return $o; } if($ch ne ','){ last; } next_chr(); white(); if ($relaxed and $ch eq '}') { --$depth; next_chr(); if ($F_HOOK) { return _json_object_hook($o); } return $o; } } } $at-- if defined $ch and $ch ne ''; decode_error(", or } expected while parsing object/hash"); } sub bareKey { # doesn't strictly follow Standard ECMA-262 3rd Edition my $key; while($ch =~ /[\$\w[:^ascii:]]/){ $key .= $ch; next_chr(); } return $key; } sub word { my $word = substr($text,$at-1,4); if($word eq 'true'){ $at += 3; next_chr; return defined $alt_true ? $alt_true : $JSON::PP::true; } elsif($word eq 'null'){ $at += 3; next_chr; return undef; } elsif($word eq 'fals'){ $at += 3; if(substr($text,$at,1) eq 'e'){ $at++; next_chr; return defined $alt_false ? $alt_false : $JSON::PP::false; } } $at--; # for decode_error report decode_error("'null' expected") if ($word =~ /^n/); decode_error("'true' expected") if ($word =~ /^t/); decode_error("'false' expected") if ($word =~ /^f/); decode_error("malformed JSON string, neither array, object, number, string or atom"); } sub number { my $n = ''; my $v; my $is_dec; my $is_exp; if($ch eq '-'){ $n = '-'; next_chr; if (!defined $ch or $ch !~ /\d/) { decode_error("malformed number (no digits after initial minus)"); } } # According to RFC4627, hex or oct digits are invalid. if($ch eq '0'){ my $peek = substr($text,$at,1); if($peek =~ /^[0-9a-dfA-DF]/){ # e may be valid (exponential) decode_error("malformed number (leading zero must not be followed by another digit)"); } $n .= $ch; next_chr; } while(defined $ch and $ch =~ /\d/){ $n .= $ch; next_chr; } if(defined $ch and $ch eq '.'){ $n .= '.'; $is_dec = 1; next_chr; if (!defined $ch or $ch !~ /\d/) { decode_error("malformed number (no digits after decimal point)"); } else { $n .= $ch; } while(defined(next_chr) and $ch =~ /\d/){ $n .= $ch; } } if(defined $ch and ($ch eq 'e' or $ch eq 'E')){ $n .= $ch; $is_exp = 1; next_chr; if(defined($ch) and ($ch eq '+' or $ch eq '-')){ $n .= $ch; next_chr; if (!defined $ch or $ch =~ /\D/) { decode_error("malformed number (no digits after exp sign)"); } $n .= $ch; } elsif(defined($ch) and $ch =~ /\d/){ $n .= $ch; } else { decode_error("malformed number (no digits after exp sign)"); } while(defined(next_chr) and $ch =~ /\d/){ $n .= $ch; } } $v .= $n; if ($is_dec or $is_exp) { if ($allow_bignum) { require Math::BigFloat; return Math::BigFloat->new($v); } } else { if (length $v > $max_intsize) { if ($allow_bignum) { # from Adam Sussman require Math::BigInt; return Math::BigInt->new($v); } else { return "$v"; } } } return $is_dec ? $v/1.0 : 0+$v; } # Compute how many bytes are in the longest legal official Unicode # character my $max_unicode_length = do { BEGIN { $] >= 5.006 and require warnings and warnings->unimport('utf8') } chr 0x10FFFF; }; utf8::encode($max_unicode_length); $max_unicode_length = length $max_unicode_length; sub is_valid_utf8 { # Returns undef (setting $utf8_len to 0) unless the next bytes in $text # comprise a well-formed UTF-8 encoded character, in which case, # return those bytes, setting $utf8_len to their count. my $start_point = substr($text, $at - 1); # Look no further than the maximum number of bytes in a single # character my $limit = $max_unicode_length; $limit = length($start_point) if $limit > length($start_point); # Find the number of bytes comprising the first character in $text # (without having to know the details of its internal representation). # This loop will iterate just once on well-formed input. while ($limit > 0) { # Until we succeed or exhaust the input my $copy = substr($start_point, 0, $limit); # decode() will return true if all bytes are valid; false # if any aren't. if (utf8::decode($copy)) { # Is valid: get the first character, convert back to bytes, # and return those bytes. $copy = substr($copy, 0, 1); utf8::encode($copy); $utf8_len = length $copy; return substr($start_point, 0, $utf8_len); } # If it didn't work, it could be that there is a full legal character # followed by a partial or malformed one. Narrow the window and # try again. $limit--; } # Failed to find a legal UTF-8 character. $utf8_len = 0; return; } sub decode_error { my $error = shift; my $no_rep = shift; my $str = defined $text ? substr($text, $at) : ''; my $mess = ''; my $type = 'U*'; if ( OLD_PERL ) { my $type = $] < 5.006 ? 'C*' : utf8::is_utf8( $str ) ? 'U*' # 5.6 : 'C*' ; } for my $c ( unpack( $type, $str ) ) { # emulate pv_uni_display() ? my $chr_c = chr($c); $mess .= $chr_c eq '\\' ? '\\\\' : $chr_c =~ /[[:print:]]/ ? $chr_c : $chr_c eq '\a' ? '\a' : $chr_c eq '\t' ? '\t' : $chr_c eq '\n' ? '\n' : $chr_c eq '\r' ? '\r' : $chr_c eq '\f' ? '\f' : sprintf('\x{%x}', $c) ; if ( length $mess >= 20 ) { $mess .= '...'; last; } } unless ( length $mess ) { $mess = '(end of string)'; } Carp::croak ( $no_rep ? "$error" : "$error, at character offset $at (before \"$mess\")" ); } sub _json_object_hook { my $o = $_[0]; my @ks = keys %{$o}; if ( $cb_sk_object and @ks == 1 and exists $cb_sk_object->{ $ks[0] } and ref $cb_sk_object->{ $ks[0] } ) { my @val = $cb_sk_object->{ $ks[0] }->( $o->{$ks[0]} ); if (@val == 0) { return $o; } elsif (@val == 1) { return $val[0]; } else { Carp::croak("filter_json_single_key_object callbacks must not return more than one scalar"); } } my @val = $cb_object->($o) if ($cb_object); if (@val == 0) { return $o; } elsif (@val == 1) { return $val[0]; } else { Carp::croak("filter_json_object callbacks must not return more than one scalar"); } } sub PP_decode_box { { text => $text, at => $at, ch => $ch, len => $len, depth => $depth, encoding => $encoding, is_valid_utf8 => $is_valid_utf8, }; } } # PARSE sub _decode_surrogates { # from perlunicode my $uni = 0x10000 + (hex($_[0]) - 0xD800) * 0x400 + (hex($_[1]) - 0xDC00); my $un = pack('U*', $uni); utf8::encode( $un ); return $un; } sub _decode_unicode { my $un = pack('U', hex shift); utf8::encode( $un ); return $un; } # # Setup for various Perl versions (the code from JSON::PP58) # BEGIN { unless ( defined &utf8::is_utf8 ) { require Encode; *utf8::is_utf8 = *Encode::is_utf8; } if ( !OLD_PERL ) { *JSON::PP::JSON_PP_encode_ascii = \&_encode_ascii; *JSON::PP::JSON_PP_encode_latin1 = \&_encode_latin1; *JSON::PP::JSON_PP_decode_surrogates = \&_decode_surrogates; *JSON::PP::JSON_PP_decode_unicode = \&_decode_unicode; if ($] < 5.008003) { # join() in 5.8.0 - 5.8.2 is broken. package # hide from PAUSE JSON::PP; require subs; subs->import('join'); eval q| sub join { return '' if (@_ < 2); my $j = shift; my $str = shift; for (@_) { $str .= $j . $_; } return $str; } |; } } sub JSON::PP::incr_parse { local $Carp::CarpLevel = 1; ( $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new )->incr_parse( @_ ); } sub JSON::PP::incr_skip { ( $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new )->incr_skip; } sub JSON::PP::incr_reset { ( $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new )->incr_reset; } eval q{ sub JSON::PP::incr_text : lvalue { $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new; if ( $_[0]->{_incr_parser}->{incr_pos} ) { Carp::croak("incr_text cannot be called when the incremental parser already started parsing"); } $_[0]->{_incr_parser}->{incr_text}; } } if ( $] >= 5.006 ); } # Setup for various Perl versions (the code from JSON::PP58) ############################### # Utilities # BEGIN { eval 'require Scalar::Util'; unless($@){ *JSON::PP::blessed = \&Scalar::Util::blessed; *JSON::PP::reftype = \&Scalar::Util::reftype; *JSON::PP::refaddr = \&Scalar::Util::refaddr; } else{ # This code is from Scalar::Util. # warn $@; eval 'sub UNIVERSAL::a_sub_not_likely_to_be_here { ref($_[0]) }'; *JSON::PP::blessed = sub { local($@, $SIG{__DIE__}, $SIG{__WARN__}); ref($_[0]) ? eval { $_[0]->a_sub_not_likely_to_be_here } : undef; }; require B; my %tmap = qw( B::NULL SCALAR B::HV HASH B::AV ARRAY B::CV CODE B::IO IO B::GV GLOB B::REGEXP REGEXP ); *JSON::PP::reftype = sub { my $r = shift; return undef unless length(ref($r)); my $t = ref(B::svref_2object($r)); return exists $tmap{$t} ? $tmap{$t} : length(ref($$r)) ? 'REF' : 'SCALAR'; }; *JSON::PP::refaddr = sub { return undef unless length(ref($_[0])); my $addr; if(defined(my $pkg = blessed($_[0]))) { $addr .= bless $_[0], 'Scalar::Util::Fake'; bless $_[0], $pkg; } else { $addr .= $_[0] } $addr =~ /0x(\w+)/; local $^W; #no warnings 'portable'; hex($1); } } } # shamelessly copied and modified from JSON::XS code. $JSON::PP::true = do { bless \(my $dummy = 1), "JSON::PP::Boolean" }; $JSON::PP::false = do { bless \(my $dummy = 0), "JSON::PP::Boolean" }; sub is_bool { if (blessed $_[0]) { return ( $_[0]->isa("JSON::PP::Boolean") or $_[0]->isa("Types::Serialiser::BooleanBase") or $_[0]->isa("JSON::XS::Boolean") ); } elsif (CORE_BOOL) { BEGIN { CORE_BOOL and warnings->unimport('experimental::builtin') } return builtin::is_bool($_[0]); } return !!0; } sub true { $JSON::PP::true } sub false { $JSON::PP::false } sub null { undef; } ############################### package # hide from PAUSE JSON::PP::IncrParser; use strict; use constant INCR_M_WS => 0; # initial whitespace skipping use constant INCR_M_STR => 1; # inside string use constant INCR_M_BS => 2; # inside backslash use constant INCR_M_JSON => 3; # outside anything, count nesting use constant INCR_M_C0 => 4; use constant INCR_M_C1 => 5; use constant INCR_M_TFN => 6; use constant INCR_M_NUM => 7; $JSON::backportPP::IncrParser::VERSION = '1.01'; sub new { my ( $class ) = @_; bless { incr_nest => 0, incr_text => undef, incr_pos => 0, incr_mode => 0, }, $class; } sub incr_parse { my ( $self, $coder, $text ) = @_; $self->{incr_text} = '' unless ( defined $self->{incr_text} ); if ( defined $text ) { $self->{incr_text} .= $text; } if ( defined wantarray ) { my $max_size = $coder->get_max_size; my $p = $self->{incr_pos}; my @ret; { do { unless ( $self->{incr_nest} <= 0 and $self->{incr_mode} == INCR_M_JSON ) { $self->_incr_parse( $coder ); if ( $max_size and $self->{incr_pos} > $max_size ) { Carp::croak("attempted decode of JSON text of $self->{incr_pos} bytes size, but max_size is set to $max_size"); } unless ( $self->{incr_nest} <= 0 and $self->{incr_mode} == INCR_M_JSON ) { # as an optimisation, do not accumulate white space in the incr buffer if ( $self->{incr_mode} == INCR_M_WS and $self->{incr_pos} ) { $self->{incr_pos} = 0; $self->{incr_text} = ''; } last; } } unless ( $coder->get_utf8 ) { utf8::decode( $self->{incr_text} ); } my ($obj, $offset) = $coder->PP_decode_json( $self->{incr_text}, 0x00000001 ); push @ret, $obj; use bytes; $self->{incr_text} = substr( $self->{incr_text}, $offset || 0 ); $self->{incr_pos} = 0; $self->{incr_nest} = 0; $self->{incr_mode} = 0; last unless wantarray; } while ( wantarray ); } if ( wantarray ) { return @ret; } else { # in scalar context return defined $ret[0] ? $ret[0] : undef; } } } sub _incr_parse { my ($self, $coder) = @_; my $text = $self->{incr_text}; my $len = length $text; my $p = $self->{incr_pos}; INCR_PARSE: while ( $len > $p ) { my $s = substr( $text, $p, 1 ); last INCR_PARSE unless defined $s; my $mode = $self->{incr_mode}; if ( $mode == INCR_M_WS ) { while ( $len > $p ) { $s = substr( $text, $p, 1 ); last INCR_PARSE unless defined $s; if ( ord($s) > ord " " ) { if ( $s eq '#' ) { $self->{incr_mode} = INCR_M_C0; redo INCR_PARSE; } else { $self->{incr_mode} = INCR_M_JSON; redo INCR_PARSE; } } $p++; } } elsif ( $mode == INCR_M_BS ) { $p++; $self->{incr_mode} = INCR_M_STR; redo INCR_PARSE; } elsif ( $mode == INCR_M_C0 or $mode == INCR_M_C1 ) { while ( $len > $p ) { $s = substr( $text, $p, 1 ); last INCR_PARSE unless defined $s; if ( $s eq "\n" ) { $self->{incr_mode} = $self->{incr_mode} == INCR_M_C0 ? INCR_M_WS : INCR_M_JSON; last; } $p++; } next; } elsif ( $mode == INCR_M_TFN ) { last INCR_PARSE if $p >= $len && $self->{incr_nest}; while ( $len > $p ) { $s = substr( $text, $p++, 1 ); next if defined $s and $s =~ /[rueals]/; last; } $p--; $self->{incr_mode} = INCR_M_JSON; last INCR_PARSE unless $self->{incr_nest}; redo INCR_PARSE; } elsif ( $mode == INCR_M_NUM ) { last INCR_PARSE if $p >= $len && $self->{incr_nest}; while ( $len > $p ) { $s = substr( $text, $p++, 1 ); next if defined $s and $s =~ /[0-9eE.+\-]/; last; } $p--; $self->{incr_mode} = INCR_M_JSON; last INCR_PARSE unless $self->{incr_nest}; redo INCR_PARSE; } elsif ( $mode == INCR_M_STR ) { while ( $len > $p ) { $s = substr( $text, $p, 1 ); last INCR_PARSE unless defined $s; if ( $s eq '"' ) { $p++; $self->{incr_mode} = INCR_M_JSON; last INCR_PARSE unless $self->{incr_nest}; redo INCR_PARSE; } elsif ( $s eq '\\' ) { $p++; if ( !defined substr($text, $p, 1) ) { $self->{incr_mode} = INCR_M_BS; last INCR_PARSE; } } $p++; } } elsif ( $mode == INCR_M_JSON ) { while ( $len > $p ) { $s = substr( $text, $p++, 1 ); if ( $s eq "\x00" ) { $p--; last INCR_PARSE; } elsif ( $s =~ /^[\t\n\r ]$/) { if ( !$self->{incr_nest} ) { $p--; # do not eat the whitespace, let the next round do it last INCR_PARSE; } next; } elsif ( $s eq 't' or $s eq 'f' or $s eq 'n' ) { $self->{incr_mode} = INCR_M_TFN; redo INCR_PARSE; } elsif ( $s =~ /^[0-9\-]$/ ) { $self->{incr_mode} = INCR_M_NUM; redo INCR_PARSE; } elsif ( $s eq '"' ) { $self->{incr_mode} = INCR_M_STR; redo INCR_PARSE; } elsif ( $s eq '[' or $s eq '{' ) { if ( ++$self->{incr_nest} > $coder->get_max_depth ) { Carp::croak('json text or perl structure exceeds maximum nesting level (max_depth set too low?)'); } next; } elsif ( $s eq ']' or $s eq '}' ) { if ( --$self->{incr_nest} <= 0 ) { last INCR_PARSE; } } elsif ( $s eq '#' ) { $self->{incr_mode} = INCR_M_C1; redo INCR_PARSE; } } } } $self->{incr_pos} = $p; $self->{incr_parsing} = $p ? 1 : 0; # for backward compatibility } sub incr_text { if ( $_[0]->{incr_pos} ) { Carp::croak("incr_text cannot be called when the incremental parser already started parsing"); } $_[0]->{incr_text}; } sub incr_skip { my $self = shift; $self->{incr_text} = substr( $self->{incr_text}, $self->{incr_pos} ); $self->{incr_pos} = 0; $self->{incr_mode} = 0; $self->{incr_nest} = 0; } sub incr_reset { my $self = shift; $self->{incr_text} = undef; $self->{incr_pos} = 0; $self->{incr_mode} = 0; $self->{incr_nest} = 0; } ############################### 1; __END__ =pod =head1 NAME JSON::PP - JSON::XS compatible pure-Perl module. =head1 SYNOPSIS use JSON::PP; # exported functions, they croak on error # and expect/generate UTF-8 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; # OO-interface $json = JSON::PP->new->ascii->pretty->allow_nonref; $pretty_printed_json_text = $json->encode( $perl_scalar ); $perl_scalar = $json->decode( $json_text ); # Note that JSON version 2.0 and above will automatically use # JSON::XS or JSON::PP, so you should be able to just: use JSON; =head1 DESCRIPTION JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to much faster L<JSON::XS> written by Marc Lehmann in C. JSON::PP works as a fallback module when you use L<JSON> module without having installed JSON::XS. Because of this fallback feature of JSON.pm, JSON::PP tries not to be more JavaScript-friendly than JSON::XS (i.e. not to escape extra characters such as U+2028 and U+2029, etc), in order for you not to lose such JavaScript-friendliness silently when you use JSON.pm and install JSON::XS for speed or by accident. If you need JavaScript-friendly RFC7159-compliant pure perl module, try L<JSON::Tiny>, which is derived from L<Mojolicious> web framework and is also smaller and faster than JSON::PP. JSON::PP has been in the Perl core since Perl 5.14, mainly for CPAN toolchain modules to parse META.json. =head1 FUNCTIONAL INTERFACE This section is taken from JSON::XS almost verbatim. C<encode_json> and C<decode_json> are exported by default. =head2 encode_json $json_text = encode_json $perl_scalar Converts the given Perl data structure to a UTF-8 encoded, binary string (that is, the string contains octets only). Croaks on error. This function call is functionally identical to: $json_text = JSON::PP->new->utf8->encode($perl_scalar) Except being faster. =head2 decode_json $perl_scalar = decode_json $json_text The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries to parse that as an UTF-8 encoded JSON text, returning the resulting reference. Croaks on error. This function call is functionally identical to: $perl_scalar = JSON::PP->new->utf8->decode($json_text) Except being faster. =head2 JSON::PP::is_bool $is_boolean = JSON::PP::is_bool($scalar) Returns true if the passed scalar represents either JSON::PP::true or JSON::PP::false, two constants that act like C<1> and C<0> respectively and are also used to represent JSON C<true> and C<false> in Perl strings. On perl 5.36 and above, will also return true when given one of perl's standard boolean values, such as the result of a comparison. See L<MAPPING>, below, for more information on how JSON values are mapped to Perl. =head1 OBJECT-ORIENTED INTERFACE This section is also taken from JSON::XS. The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. =head2 new $json = JSON::PP->new Creates a new JSON::PP object that can be used to de/encode JSON strings. All boolean flags described below are by default I<disabled> (with the exception of C<allow_nonref>, which defaults to I<enabled> since version C<4.0>). The mutators for flags all return the JSON::PP object again and thus calls can be chained: my $json = JSON::PP->new->utf8->space_after->encode({a => [1,2]}) => {"a": [1, 2]} =head2 ascii $json = $json->ascii([$enable]) $enabled = $json->get_ascii If C<$enable> is true (or missing), then the C<encode> method will not generate characters outside the code range C<0..127> (which is ASCII). Any Unicode characters outside that range will be escaped using either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. The resulting encoded JSON text can be treated as a native Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, or any other superset of ASCII. If C<$enable> is false, then the C<encode> method will not escape Unicode characters unless required by the JSON syntax or other flags. This results in a faster and more compact format. See also the section I<ENCODING/CODESET FLAG NOTES> later in this document. The main use for this flag is to produce JSON texts that can be transmitted over a 7-bit channel, as the encoded JSON texts will not contain any 8 bit characters. JSON::PP->new->ascii(1)->encode([chr 0x10401]) => ["\ud801\udc01"] =head2 latin1 $json = $json->latin1([$enable]) $enabled = $json->get_latin1 If C<$enable> is true (or missing), then the C<encode> method will encode the resulting JSON text as latin1 (or iso-8859-1), escaping any characters outside the code range C<0..255>. The resulting string can be treated as a latin1-encoded JSON text or a native Unicode string. The C<decode> method will not be affected in any way by this flag, as C<decode> by default expects Unicode, which is a strict superset of latin1. If C<$enable> is false, then the C<encode> method will not escape Unicode characters unless required by the JSON syntax or other flags. See also the section I<ENCODING/CODESET FLAG NOTES> later in this document. The main use for this flag is efficiently encoding binary data as JSON text, as most octets will not be escaped, resulting in a smaller encoded size. The disadvantage is that the resulting JSON text is encoded in latin1 (and must correctly be treated as such when storing and transferring), a rare encoding for JSON. It is therefore most useful when you want to store data structures known to contain binary data efficiently in files or databases, not when talking to other JSON encoders/decoders. JSON::PP->new->latin1->encode (["\x{89}\x{abc}"] => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) =head2 utf8 $json = $json->utf8([$enable]) $enabled = $json->get_utf8 If C<$enable> is true (or missing), then the C<encode> method will encode the JSON result into UTF-8, as required by many protocols, while the C<decode> method expects to be handled an UTF-8-encoded string. Please note that UTF-8-encoded strings do not contain any characters outside the range C<0..255>, they are thus useful for bytewise/binary I/O. In future versions, enabling this option might enable autodetection of the UTF-16 and UTF-32 encoding families, as described in RFC4627. If C<$enable> is false, then the C<encode> method will return the JSON string as a (non-encoded) Unicode string, while C<decode> expects thus a Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs to be done yourself, e.g. using the Encode module. See also the section I<ENCODING/CODESET FLAG NOTES> later in this document. Example, output UTF-16BE-encoded JSON: use Encode; $jsontext = encode "UTF-16BE", JSON::PP->new->encode ($object); Example, decode UTF-32LE-encoded JSON: use Encode; $object = JSON::PP->new->decode (decode "UTF-32LE", $jsontext); =head2 pretty $json = $json->pretty([$enable]) This enables (or disables) all of the C<indent>, C<space_before> and C<space_after> (and in the future possibly more) flags in one call to generate the most readable (or most compact) form possible. =head2 indent $json = $json->indent([$enable]) $enabled = $json->get_indent If C<$enable> is true (or missing), then the C<encode> method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, indenting them properly. If C<$enable> is false, no newlines or indenting will be produced, and the resulting JSON text is guaranteed not to contain any C<newlines>. This setting has no effect when decoding JSON texts. The default indent space length is three. You can use C<indent_length> to change the length. =head2 space_before $json = $json->space_before([$enable]) $enabled = $json->get_space_before If C<$enable> is true (or missing), then the C<encode> method will add an extra optional space before the C<:> separating keys from values in JSON objects. If C<$enable> is false, then the C<encode> method will not add any extra space at those places. This setting has no effect when decoding JSON texts. You will also most likely combine this setting with C<space_after>. Example, space_before enabled, space_after and indent disabled: {"key" :"value"} =head2 space_after $json = $json->space_after([$enable]) $enabled = $json->get_space_after If C<$enable> is true (or missing), then the C<encode> method will add an extra optional space after the C<:> separating keys from values in JSON objects and extra whitespace after the C<,> separating key-value pairs and array members. If C<$enable> is false, then the C<encode> method will not add any extra space at those places. This setting has no effect when decoding JSON texts. Example, space_before and indent disabled, space_after enabled: {"key": "value"} =head2 relaxed $json = $json->relaxed([$enable]) $enabled = $json->get_relaxed If C<$enable> is true (or missing), then C<decode> will accept some extensions to normal JSON syntax (see below). C<encode> will not be affected in anyway. I<Be aware that this option makes you accept invalid JSON texts as if they were valid!>. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) If C<$enable> is false (the default), then C<decode> will only accept valid JSON texts. Currently accepted extensions are: =over 4 =item * list items can have an end-comma JSON I<separates> array elements and key-value pairs with commas. This can be annoying if you write JSON texts manually and want to be able to quickly append elements, so this extension accepts comma at the end of such items not just between them: [ 1, 2, <- this comma not normally allowed ] { "k1": "v1", "k2": "v2", <- this comma not normally allowed } =item * shell-style '#'-comments Whenever JSON allows whitespace, shell-style comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. [ 1, # this comment not allowed in JSON # neither this one... ] =item * C-style multiple-line '/* */'-comments (JSON::PP only) Whenever JSON allows whitespace, C-style multiple-line comments are additionally allowed. Everything between C</*> and C<*/> is a comment, after which more white-space and comments are allowed. [ 1, /* this comment not allowed in JSON */ /* neither this one... */ ] =item * C++-style one-line '//'-comments (JSON::PP only) Whenever JSON allows whitespace, C++-style one-line comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. [ 1, // this comment not allowed in JSON // neither this one... ] =item * literal ASCII TAB characters in strings Literal ASCII TAB characters are now allowed in strings (and treated as C<\t>). [ "Hello\tWorld", "Hello<TAB>World", # literal <TAB> would not normally be allowed ] =back =head2 canonical $json = $json->canonical([$enable]) $enabled = $json->get_canonical If C<$enable> is true (or missing), then the C<encode> method will output JSON objects by sorting their keys. This is adding a comparatively high overhead. If C<$enable> is false, then the C<encode> method will output key-value pairs in the order Perl stores them (which will likely change between runs of the same script, and can change even within the same run from 5.18 onwards). This option is useful if you want the same data structure to be encoded as the same JSON text (given the same overall settings). If it is disabled, the same hash might be encoded differently even if contains the same data, as key-value pairs have no inherent ordering in Perl. This setting has no effect when decoding JSON texts. This setting has currently no effect on tied hashes. =head2 allow_nonref $json = $json->allow_nonref([$enable]) $enabled = $json->get_allow_nonref Unlike other boolean options, this opotion is enabled by default beginning with version C<4.0>. If C<$enable> is true (or missing), then the C<encode> method can convert a non-reference into its corresponding string, number or null JSON value, which is an extension to RFC4627. Likewise, C<decode> will accept those JSON values instead of croaking. If C<$enable> is false, then the C<encode> method will croak if it isn't passed an arrayref or hashref, as JSON texts must either be an object or array. Likewise, C<decode> will croak if given something that is not a JSON object or array. Example, encode a Perl scalar as JSON value without enabled C<allow_nonref>, resulting in an error: JSON::PP->new->allow_nonref(0)->encode ("Hello, World!") => hash- or arrayref expected... =head2 allow_unknown $json = $json->allow_unknown([$enable]) $enabled = $json->get_allow_unknown If C<$enable> is true (or missing), then C<encode> will I<not> throw an exception when it encounters values it cannot represent in JSON (for example, filehandles) but instead will encode a JSON C<null> value. Note that blessed objects are not included here and are handled separately by c<allow_blessed>. If C<$enable> is false (the default), then C<encode> will throw an exception when it encounters anything it cannot encode as JSON. This option does not affect C<decode> in any way, and it is recommended to leave it off unless you know your communications partner. =head2 allow_blessed $json = $json->allow_blessed([$enable]) $enabled = $json->get_allow_blessed See L<OBJECT SERIALISATION> for details. If C<$enable> is true (or missing), then the C<encode> method will not barf when it encounters a blessed reference that it cannot convert otherwise. Instead, a JSON C<null> value is encoded instead of the object. If C<$enable> is false (the default), then C<encode> will throw an exception when it encounters a blessed object that it cannot convert otherwise. This setting has no effect on C<decode>. =head2 convert_blessed $json = $json->convert_blessed([$enable]) $enabled = $json->get_convert_blessed See L<OBJECT SERIALISATION> for details. If C<$enable> is true (or missing), then C<encode>, upon encountering a blessed object, will check for the availability of the C<TO_JSON> method on the object's class. If found, it will be called in scalar context and the resulting scalar will be encoded instead of the object. The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> returns other blessed objects, those will be handled in the same way. C<TO_JSON> must take care of not causing an endless recursion cycle (== crash) in this case. The name of C<TO_JSON> was chosen because other methods called by the Perl core (== not by the user of the object) are usually in upper case letters and to avoid collisions with any C<to_json> function or method. If C<$enable> is false (the default), then C<encode> will not consider this type of conversion. This setting has no effect on C<decode>. =head2 allow_tags $json = $json->allow_tags([$enable]) $enabled = $json->get_allow_tags See L<OBJECT SERIALISATION> for details. If C<$enable> is true (or missing), then C<encode>, upon encountering a blessed object, will check for the availability of the C<FREEZE> method on the object's class. If found, it will be used to serialise the object into a nonstandard tagged JSON value (that JSON decoders cannot decode). It also causes C<decode> to parse such tagged JSON values and deserialise them via a call to the C<THAW> method. If C<$enable> is false (the default), then C<encode> will not consider this type of conversion, and tagged JSON values will cause a parse error in C<decode>, as if tags were not part of the grammar. =head2 boolean_values $json->boolean_values([$false, $true]) ($false, $true) = $json->get_boolean_values By default, JSON booleans will be decoded as overloaded C<$JSON::PP::false> and C<$JSON::PP::true> objects. With this method you can specify your own boolean values for decoding - on decode, JSON C<false> will be decoded as a copy of C<$false>, and JSON C<true> will be decoded as C<$true> ("copy" here is the same thing as assigning a value to another variable, i.e. C<$copy = $false>). This is useful when you want to pass a decoded data structure directly to other serialisers like YAML, Data::MessagePack and so on. Note that this works only when you C<decode>. You can set incompatible boolean objects (like L<boolean>), but when you C<encode> a data structure with such boolean objects, you still need to enable C<convert_blessed> (and add a C<TO_JSON> method if necessary). Calling this method without any arguments will reset the booleans to their default values. C<get_boolean_values> will return both C<$false> and C<$true> values, or the empty list when they are set to the default. =head2 core_bools $json->core_bools([$enable]); If C<$enable> is true (or missing), then C<decode>, will produce standard perl boolean values. Equivalent to calling: $json->boolean_values(!!1, !!0) C<get_core_bools> will return true if this has been set. On perl 5.36, it will also return true if the boolean values have been set to perl's core booleans using the C<boolean_values> method. The methods C<unblessed_bool> and C<get_unblessed_bool> are provided as aliases for compatibility with L<Cpanel::JSON::XS>. =head2 filter_json_object $json = $json->filter_json_object([$coderef]) When C<$coderef> is specified, it will be called from C<decode> each time it decodes a JSON object. The only argument is a reference to the newly-created hash. If the code references returns a single scalar (which need not be a reference), this value (or rather a copy of it) is inserted into the deserialised data structure. If it returns an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the original deserialised hash will be inserted. This setting can slow down decoding considerably. When C<$coderef> is omitted or undefined, any existing callback will be removed and C<decode> will not change the deserialised hash in any way. Example, convert all JSON objects into the integer 5: my $js = JSON::PP->new->filter_json_object(sub { 5 }); # returns [5] $js->decode('[{}]'); # returns 5 $js->decode('{"a":1, "b":2}'); =head2 filter_json_single_key_object $json = $json->filter_json_single_key_object($key [=> $coderef]) Works remotely similar to C<filter_json_object>, but is only called for JSON objects having a single key named C<$key>. This C<$coderef> is called before the one specified via C<filter_json_object>, if any. It gets passed the single value in the JSON object. If it returns a single value, it will be inserted into the data structure. If it returns nothing (not even C<undef> but the empty list), the callback from C<filter_json_object> will be called next, as if no single-key callback were specified. If C<$coderef> is omitted or undefined, the corresponding callback will be disabled. There can only ever be one callback for a given key. As this callback gets called less often then the C<filter_json_object> one, decoding speed will not usually suffer as much. Therefore, single-key objects make excellent targets to serialise Perl objects into, especially as single-key JSON objects are as close to the type-tagged value concept as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not support this in any way, so you need to make sure your data never looks like a serialised Perl hash. Typical names for the single object key are C<__class_whatever__>, or C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even things like C<__class_md5sum(classname)__>, to reduce the risk of clashing with real hashes. Example, decode JSON objects of the form C<< { "__widget__" => <id> } >> into the corresponding C<< $WIDGET{<id>} >> object: # return whatever is in $WIDGET{5}: JSON::PP ->new ->filter_json_single_key_object (__widget__ => sub { $WIDGET{ $_[0] } }) ->decode ('{"__widget__": 5') # this can be used with a TO_JSON method in some "widget" class # for serialisation to json: sub WidgetBase::TO_JSON { my ($self) = @_; unless ($self->{id}) { $self->{id} = ..get..some..id..; $WIDGET{$self->{id}} = $self; } { __widget__ => $self->{id} } } =head2 shrink $json = $json->shrink([$enable]) $enabled = $json->get_shrink If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk (i.e. downgraded if possible). The actual definition of what shrink does might change in future versions, but it will always try to save space at the expense of time. If C<$enable> is false, then JSON::PP does nothing. =head2 max_depth $json = $json->max_depth([$maximum_nesting_depth]) $max_depth = $json->get_max_depth Sets the maximum nesting level (default C<512>) accepted while encoding or decoding. If a higher nesting level is detected in JSON text or a Perl data structure, then the encoder and decoder will stop and croak at that point. Nesting level is defined by number of hash- or arrayrefs that the encoder needs to traverse to reach a given point or the number of C<{> or C<[> characters without their matching closing parenthesis crossed to reach a given character in a string. Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. If no argument is given, the highest possible setting will be used, which is rarely useful. See L<JSON::XS/SECURITY CONSIDERATIONS> for more info on why this is useful. =head2 max_size $json = $json->max_size([$maximum_string_size]) $max_size = $json->get_max_size Set the maximum length a JSON text may have (in bytes) where decoding is being attempted. The default is C<0>, meaning no limit. When C<decode> is called on a string that is longer then this many bytes, it will not attempt to decode the string but throw an exception. This setting has no effect on C<encode> (yet). If no argument is given, the limit check will be deactivated (same as when C<0> is specified). See L<JSON::XS/SECURITY CONSIDERATIONS> for more info on why this is useful. =head2 encode $json_text = $json->encode($perl_scalar) Converts the given Perl value or data structure to its JSON representation. Croaks on error. =head2 decode $perl_scalar = $json->decode($json_text) The opposite of C<encode>: expects a JSON text and tries to parse it, returning the resulting simple scalar or reference. Croaks on error. =head2 decode_prefix ($perl_scalar, $characters) = $json->decode_prefix($json_text) This works like the C<decode> method, but instead of raising an exception when there is trailing garbage after the first JSON object, it will silently stop parsing there and return the number of characters consumed so far. This is useful if your JSON texts are not delimited by an outer protocol and you need to know where the JSON text ends. JSON::PP->new->decode_prefix ("[1] the tail") => ([1], 3) =head1 FLAGS FOR JSON::PP ONLY The following flags and properties are for JSON::PP only. If you use any of these, you can't make your application run faster by replacing JSON::PP with JSON::XS. If you need these and also speed boost, you might want to try L<Cpanel::JSON::XS>, a fork of JSON::XS by Reini Urban, which supports some of these (with a different set of incompatibilities). Most of these historical flags are only kept for backward compatibility, and should not be used in a new application. =head2 allow_singlequote $json = $json->allow_singlequote([$enable]) $enabled = $json->get_allow_singlequote If C<$enable> is true (or missing), then C<decode> will accept invalid JSON texts that contain strings that begin and end with single quotation marks. C<encode> will not be affected in any way. I<Be aware that this option makes you accept invalid JSON texts as if they were valid!>. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) If C<$enable> is false (the default), then C<decode> will only accept valid JSON texts. $json->allow_singlequote->decode(qq|{"foo":'bar'}|); $json->allow_singlequote->decode(qq|{'foo':"bar"}|); $json->allow_singlequote->decode(qq|{'foo':'bar'}|); =head2 allow_barekey $json = $json->allow_barekey([$enable]) $enabled = $json->get_allow_barekey If C<$enable> is true (or missing), then C<decode> will accept invalid JSON texts that contain JSON objects whose names don't begin and end with quotation marks. C<encode> will not be affected in any way. I<Be aware that this option makes you accept invalid JSON texts as if they were valid!>. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) If C<$enable> is false (the default), then C<decode> will only accept valid JSON texts. $json->allow_barekey->decode(qq|{foo:"bar"}|); =head2 allow_bignum $json = $json->allow_bignum([$enable]) $enabled = $json->get_allow_bignum If C<$enable> is true (or missing), then C<decode> will convert big integers Perl cannot handle as integer into L<Math::BigInt> objects and convert floating numbers into L<Math::BigFloat> objects. C<encode> will convert C<Math::BigInt> and C<Math::BigFloat> objects into JSON numbers. $json->allow_nonref->allow_bignum; $bigfloat = $json->decode('2.000000000000000000000000001'); print $json->encode($bigfloat); # => 2.000000000000000000000000001 See also L<MAPPING>. =head2 loose $json = $json->loose([$enable]) $enabled = $json->get_loose If C<$enable> is true (or missing), then C<decode> will accept invalid JSON texts that contain unescaped [\x00-\x1f\x22\x5c] characters. C<encode> will not be affected in any way. I<Be aware that this option makes you accept invalid JSON texts as if they were valid!>. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) If C<$enable> is false (the default), then C<decode> will only accept valid JSON texts. $json->loose->decode(qq|["abc def"]|); =head2 escape_slash $json = $json->escape_slash([$enable]) $enabled = $json->get_escape_slash If C<$enable> is true (or missing), then C<encode> will explicitly escape I<slash> (solidus; C<U+002F>) characters to reduce the risk of XSS (cross site scripting) that may be caused by C<< </script> >> in a JSON text, with the cost of bloating the size of JSON texts. This option may be useful when you embed JSON in HTML, but embedding arbitrary JSON in HTML (by some HTML template toolkit or by string interpolation) is risky in general. You must escape necessary characters in correct order, depending on the context. C<decode> will not be affected in any way. =head2 indent_length $json = $json->indent_length($number_of_spaces) $length = $json->get_indent_length This option is only useful when you also enable C<indent> or C<pretty>. JSON::XS indents with three spaces when you C<encode> (if requested by C<indent> or C<pretty>), and the number cannot be changed. JSON::PP allows you to change/get the number of indent spaces with these mutator/accessor. The default number of spaces is three (the same as JSON::XS), and the acceptable range is from C<0> (no indentation; it'd be better to disable indentation by C<indent(0)>) to C<15>. =head2 sort_by $json = $json->sort_by($code_ref) $json = $json->sort_by($subroutine_name) If you just want to sort keys (names) in JSON objects when you C<encode>, enable C<canonical> option (see above) that allows you to sort object keys alphabetically. If you do need to sort non-alphabetically for whatever reasons, you can give a code reference (or a subroutine name) to C<sort_by>, then the argument will be passed to Perl's C<sort> built-in function. As the sorting is done in the JSON::PP scope, you usually need to prepend C<JSON::PP::> to the subroutine name, and the special variables C<$a> and C<$b> used in the subrontine used by C<sort> function. Example: my %ORDER = (id => 1, class => 2, name => 3); $json->sort_by(sub { ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999) or $JSON::PP::a cmp $JSON::PP::b }); print $json->encode([ {name => 'CPAN', id => 1, href => 'http://cpan.org'} ]); # [{"id":1,"name":"CPAN","href":"http://cpan.org"}] Note that C<sort_by> affects all the plain hashes in the data structure. If you need finer control, C<tie> necessary hashes with a module that implements ordered hash (such as L<Hash::Ordered> and L<Tie::IxHash>). C<canonical> and C<sort_by> don't affect the key order in C<tie>d hashes. use Hash::Ordered; tie my %hash, 'Hash::Ordered', (name => 'CPAN', id => 1, href => 'http://cpan.org'); print $json->encode([\%hash]); # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept =head1 INCREMENTAL PARSING This section is also taken from JSON::XS. In some cases, there is the need for incremental parsing of JSON texts. While this module always has to keep both JSON text and resulting Perl data structure in memory at one time, it does allow you to parse a JSON stream incrementally. It does so by accumulating text until it has a full JSON object, which it then can decode. This process is similar to using C<decode_prefix> to see if a full JSON object is available, but is much more efficient (and can be implemented with a minimum of method calls). JSON::PP will only attempt to parse the JSON text once it is sure it has enough text to get a decisive result, using a very simple but truly incremental parser. This means that it sometimes won't stop as early as the full parser, for example, it doesn't detect mismatched parentheses. The only thing it guarantees is that it starts decoding as soon as a syntactically valid JSON text has been seen. This means you need to set resource limits (e.g. C<max_size>) to ensure the parser will stop parsing in the presence if syntax errors. The following methods implement this incremental parser. =head2 incr_parse $json->incr_parse( [$string] ) # void context $obj_or_undef = $json->incr_parse( [$string] ) # scalar context @obj_or_empty = $json->incr_parse( [$string] ) # list context This is the central parsing function. It can both append new text and extract objects from the stream accumulated so far (both of these functions are optional). If C<$string> is given, then this string is appended to the already existing JSON fragment stored in the C<$json> object. After that, if the function is called in void context, it will simply return without doing anything further. This can be used to add more text in as many chunks as you want. If the method is called in scalar context, then it will try to extract exactly I<one> JSON object. If that is successful, it will return this object, otherwise it will return C<undef>. If there is a parse error, this method will croak just as C<decode> would do (one can then use C<incr_skip> to skip the erroneous part). This is the most common way of using the method. And finally, in list context, it will try to extract as many objects from the stream as it can find and return them, or the empty list otherwise. For this to work, there must be no separators (other than whitespace) between the JSON objects or arrays, instead they must be concatenated back-to-back. If an error occurs, an exception will be raised as in the scalar context case. Note that in this case, any previously-parsed JSON texts will be lost. Example: Parse some JSON arrays/objects in a given string and return them. my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]"); =head2 incr_text $lvalue_string = $json->incr_text This method returns the currently stored JSON fragment as an lvalue, that is, you can manipulate it. This I<only> works when a preceding call to C<incr_parse> in I<scalar context> successfully returned an object. Under all other circumstances you must not call this function (I mean it. although in simple tests it might actually work, it I<will> fail under real world conditions). As a special exception, you can also call this method before having parsed anything. That means you can only use this function to look at or manipulate text before or after complete JSON objects, not while the parser is in the middle of parsing a JSON object. This function is useful in two cases: a) finding the trailing text after a JSON object or b) parsing multiple JSON objects separated by non-JSON text (such as commas). =head2 incr_skip $json->incr_skip This will reset the state of the incremental parser and will remove the parsed text from the input buffer so far. This is useful after C<incr_parse> died, in which case the input buffer and incremental parser state is left unchanged, to skip the text parsed so far and to reset the parse state. The difference to C<incr_reset> is that only text until the parse error occurred is removed. =head2 incr_reset $json->incr_reset This completely resets the incremental parser, that is, after this call, it will be as if the parser had never parsed anything. This is useful if you want to repeatedly parse JSON objects and want to ignore any trailing data, which means you have to reset the parser after each successful decode. =head1 MAPPING Most of this section is also taken from JSON::XS. This section describes how JSON::PP maps Perl values to JSON values and vice versa. These mappings are designed to "do the right thing" in most circumstances automatically, preserving round-tripping characteristics (what you put in comes out as something equivalent). For the more enlightened: note that in the following descriptions, lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl> refers to the abstract Perl language itself. =head2 JSON -> PERL =over 4 =item object A JSON object becomes a reference to a hash in Perl. No ordering of object keys is preserved (JSON does not preserve object key ordering itself). =item array A JSON array becomes a reference to an array in Perl. =item string A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON are represented by the same codepoints in the Perl string, so no manual decoding is necessary. =item number A JSON number becomes either an integer, numeric (floating point) or string scalar in perl, depending on its range and any fractional parts. On the Perl level, there is no difference between those as Perl handles all the conversion details, but an integer may take slightly less memory and might represent more values exactly than floating point numbers. If the number consists of digits only, JSON::PP will try to represent it as an integer value. If that fails, it will try to represent it as a numeric (floating point) value if that is possible without loss of precision. Otherwise it will preserve the number as a string value (in which case you lose roundtripping ability, as the JSON number will be re-encoded to a JSON string). Numbers containing a fractional or exponential part will always be represented as numeric (floating point) values, possibly at a loss of precision (in which case you might lose perfect roundtripping ability, but the JSON number will still be re-encoded as a JSON number). Note that precision is not accuracy - binary floating point values cannot represent most decimal fractions exactly, and when converting from and to floating point, JSON::PP only guarantees precision up to but not including the least significant bit. When C<allow_bignum> is enabled, big integer values and any numeric values will be converted into L<Math::BigInt> and L<Math::BigFloat> objects respectively, without becoming string scalars or losing precision. =item true, false These JSON atoms become C<JSON::PP::true> and C<JSON::PP::false>, respectively. They are overloaded to act almost exactly like the numbers C<1> and C<0>. You can check whether a scalar is a JSON boolean by using the C<JSON::PP::is_bool> function. =item null A JSON null atom becomes C<undef> in Perl. =item shell-style comments (C<< # I<text> >>) As a nonstandard extension to the JSON syntax that is enabled by the C<relaxed> setting, shell-style comments are allowed. They can start anywhere outside strings and go till the end of the line. =item tagged values (C<< (I<tag>)I<value> >>). Another nonstandard extension to the JSON syntax, enabled with the C<allow_tags> setting, are tagged values. In this implementation, the I<tag> must be a perl package/class name encoded as a JSON string, and the I<value> must be a JSON array encoding optional constructor arguments. See L<OBJECT SERIALISATION>, below, for details. =back =head2 PERL -> JSON The mapping from Perl to JSON is slightly more difficult, as Perl is a truly typeless language, so we can only guess which JSON type is meant by a Perl value. =over 4 =item hash references Perl hash references become JSON objects. As there is no inherent ordering in hash keys (or JSON objects), they will usually be encoded in a pseudo-random order. JSON::PP can optionally sort the hash keys (determined by the I<canonical> flag and/or I<sort_by> property), so the same data structure will serialise to the same JSON text (given same settings and version of JSON::PP), but this incurs a runtime overhead and is only rarely useful, e.g. when you want to compare some JSON text against another for equality. =item array references Perl array references become JSON arrays. =item other references Other unblessed references are generally not allowed and will cause an exception to be thrown, except for references to the integers C<0> and C<1>, which get turned into C<false> and C<true> atoms in JSON. You can also use C<JSON::PP::false> and C<JSON::PP::true> to improve readability. to_json [\0, JSON::PP::true] # yields [false,true] =item JSON::PP::true, JSON::PP::false These special values become JSON true and JSON false values, respectively. You can also use C<\1> and C<\0> directly if you want. =item JSON::PP::null This special value becomes JSON null. =item blessed objects Blessed objects are not directly representable in JSON, but C<JSON::PP> allows various ways of handling objects. See L<OBJECT SERIALISATION>, below, for details. =item simple scalars Simple Perl scalars (any scalar that is not a reference) are the most difficult objects to encode: JSON::PP will encode undefined scalars as JSON C<null> values, scalars that have last been used in a string context before encoding as JSON strings, and anything else as number value: # dump as number encode_json [2] # yields [2] encode_json [-3.0e17] # yields [-3e+17] my $value = 5; encode_json [$value] # yields [5] # used as string, so dump as string print $value; encode_json [$value] # yields ["5"] # undef becomes null encode_json [undef] # yields [null] You can force the type to be a JSON string by stringifying it: my $x = 3.1; # some variable containing a number "$x"; # stringified $x .= ""; # another, more awkward way to stringify print $x; # perl does it for you, too, quite often # (but for older perls) You can force the type to be a JSON number by numifying it: my $x = "3"; # some variable containing a string $x += 0; # numify it, ensuring it will be dumped as a number $x *= 1; # same thing, the choice is yours. You can not currently force the type in other, less obscure, ways. Since version 2.91_01, JSON::PP uses a different number detection logic that converts a scalar that is possible to turn into a number safely. The new logic is slightly faster, and tends to help people who use older perl or who want to encode complicated data structure. However, this may results in a different JSON text from the one JSON::XS encodes (and thus may break tests that compare entire JSON texts). If you do need the previous behavior for compatibility or for finer control, set PERL_JSON_PP_USE_B environmental variable to true before you C<use> JSON::PP (or JSON.pm). Note that numerical precision has the same meaning as under Perl (so binary to decimal conversion follows the same rules as in Perl, which can differ to other languages). Also, your perl interpreter might expose extensions to the floating point numbers of your platform, such as infinities or NaN's - these cannot be represented in JSON, and it is an error to pass those in. JSON::PP (and JSON::XS) trusts what you pass to C<encode> method (or C<encode_json> function) is a clean, validated data structure with values that can be represented as valid JSON values only, because it's not from an external data source (as opposed to JSON texts you pass to C<decode> or C<decode_json>, which JSON::PP considers tainted and doesn't trust). As JSON::PP doesn't know exactly what you and consumers of your JSON texts want the unexpected values to be (you may want to convert them into null, or to stringify them with or without normalisation (string representation of infinities/NaN may vary depending on platforms), or to croak without conversion), you're advised to do what you and your consumers need before you encode, and also not to numify values that may start with values that look like a number (including infinities/NaN), without validating. =back =head2 OBJECT SERIALISATION As JSON cannot directly represent Perl objects, you have to choose between a pure JSON representation (without the ability to deserialise the object automatically again), and a nonstandard extension to the JSON syntax, tagged values. =head3 SERIALISATION What happens when C<JSON::PP> encounters a Perl object depends on the C<allow_blessed>, C<convert_blessed>, C<allow_tags> and C<allow_bignum> settings, which are used in this order: =over 4 =item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method. In this case, C<JSON::PP> creates a tagged JSON value, using a nonstandard extension to the JSON syntax. This works by invoking the C<FREEZE> method on the object, with the first argument being the object to serialise, and the second argument being the constant string C<JSON> to distinguish it from other serialisers. The C<FREEZE> method can return any number of values (i.e. zero or more). These values and the paclkage/classname of the object will then be encoded as a tagged JSON value in the following format: ("classname")[FREEZE return values...] e.g.: ("URI")["http://www.google.com/"] ("MyDate")[2013,10,29] ("ImageData::JPEG")["Z3...VlCg=="] For example, the hypothetical C<My::Object> C<FREEZE> method might use the objects C<type> and C<id> members to encode the object: sub My::Object::FREEZE { my ($self, $serialiser) = @_; ($self->{type}, $self->{id}) } =item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method. In this case, the C<TO_JSON> method of the object is invoked in scalar context. It must return a single scalar that can be directly encoded into JSON. This scalar replaces the object in the JSON text. For example, the following C<TO_JSON> method will convert all L<URI> objects to JSON strings when serialised. The fact that these values originally were L<URI> objects is lost. sub URI::TO_JSON { my ($uri) = @_; $uri->as_string } =item 3. C<allow_bignum> is enabled and the object is a C<Math::BigInt> or C<Math::BigFloat>. The object will be serialised as a JSON number value. =item 4. C<allow_blessed> is enabled. The object will be serialised as a JSON null value. =item 5. none of the above If none of the settings are enabled or the respective methods are missing, C<JSON::PP> throws an exception. =back =head3 DESERIALISATION For deserialisation there are only two cases to consider: either nonstandard tagging was used, in which case C<allow_tags> decides, or objects cannot be automatically be deserialised, in which case you can use postprocessing or the C<filter_json_object> or C<filter_json_single_key_object> callbacks to get some real objects our of your JSON. This section only considers the tagged value case: a tagged JSON object is encountered during decoding and C<allow_tags> is disabled, a parse error will result (as if tagged values were not part of the grammar). If C<allow_tags> is enabled, C<JSON::PP> will look up the C<THAW> method of the package/classname used during serialisation (it will not attempt to load the package as a Perl module). If there is no such method, the decoding will fail with an error. Otherwise, the C<THAW> method is invoked with the classname as first argument, the constant string C<JSON> as second argument, and all the values from the JSON array (the values originally returned by the C<FREEZE> method) as remaining arguments. The method must then return the object. While technically you can return any Perl scalar, you might have to enable the C<allow_nonref> setting to make that work in all cases, so better return an actual blessed reference. As an example, let's implement a C<THAW> function that regenerates the C<My::Object> from the C<FREEZE> example earlier: sub My::Object::THAW { my ($class, $serialiser, $type, $id) = @_; $class->new (type => $type, id => $id) } =head1 ENCODING/CODESET FLAG NOTES This section is taken from JSON::XS. The interested reader might have seen a number of flags that signify encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be some confusion on what these do, so here is a short comparison: C<utf8> controls whether the JSON text created by C<encode> (and expected by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only control whether C<encode> escapes character values outside their respective codeset range. Neither of these flags conflict with each other, although some combinations make less sense than others. Care has been taken to make all flags symmetrical with respect to C<encode> and C<decode>, that is, texts encoded with any combination of these flag values will be correctly decoded when the same flags are used - in general, if you use different flag settings while encoding vs. when decoding you likely have a bug somewhere. Below comes a verbose discussion of these flags. Note that a "codeset" is simply an abstract set of character-codepoint pairs, while an encoding takes those codepoint numbers and I<encodes> them, in our case into octets. Unicode is (among other things) a codeset, UTF-8 is an encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at the same time, which can be confusing. =over 4 =item C<utf8> flag disabled When C<utf8> is disabled (the default), then C<encode>/C<decode> generate and expect Unicode strings, that is, characters with high ordinal Unicode values (> 255) will be encoded as such characters, and likewise such characters are decoded as-is, no changes to them will be done, except "(re-)interpreting" them as Unicode codepoints or Unicode characters, respectively (to Perl, these are the same thing in strings unless you do funny/weird/dumb stuff). This is useful when you want to do the encoding yourself (e.g. when you want to have UTF-16 encoded JSON texts) or when some other layer does the encoding for you (for example, when printing to a terminal using a filehandle that transparently encodes to UTF-8 you certainly do NOT want to UTF-8 encode your data first and have Perl encode it another time). =item C<utf8> flag enabled If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all characters using the corresponding UTF-8 multi-byte sequence, and will expect your input strings to be encoded as UTF-8, that is, no "character" of the input string must have any value > 255, as UTF-8 does not allow that. The C<utf8> flag therefore switches between two modes: disabled means you will get a Unicode string in Perl, enabled means you get an UTF-8 encoded octet/binary string in Perl. =item C<latin1> or C<ascii> flags enabled With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining characters as specified by the C<utf8> flag. If C<utf8> is disabled, then the result is also correctly encoded in those character sets (as both are proper subsets of Unicode, meaning that a Unicode string with all character values < 256 is the same thing as a ISO-8859-1 string, and a Unicode string with all character values < 128 is the same thing as an ASCII string in Perl). If C<utf8> is enabled, you still get a correct UTF-8-encoded string, regardless of these flags, just some more characters will be escaped using C<\uXXXX> then before. Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8 encoding, while ASCII-encoded strings are. That is because the ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being a subset of Unicode), while ASCII is. Surprisingly, C<decode> will ignore these flags and so treat all input values as governed by the C<utf8> flag. If it is disabled, this allows you to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings. So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag - they only govern when the JSON output engine escapes a character or not. The main use for C<latin1> is to relatively efficiently store binary data as JSON, at the expense of breaking compatibility with most JSON decoders. The main use for C<ascii> is to force the output to not contain characters with values > 127, which means you can interpret the resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and 8-bit-encoding, and still get the same data structure back. This is useful when your channel for JSON transfer is not 8-bit clean or the encoding might be mangled in between (e.g. in mail), and works because ASCII is a proper subset of most 8-bit and multibyte encodings in use in the world. =back =head1 BUGS Please report bugs on a specific behavior of this module to RT or GitHub issues (preferred): L<https://github.com/makamaka/JSON-PP/issues> L<https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON-PP> As for new features and requests to change common behaviors, please ask the author of JSON::XS (Marc Lehmann, E<lt>schmorp[at]schmorp.deE<gt>) first, by email (important!), to keep compatibility among JSON.pm backends. Generally speaking, if you need something special for you, you are advised to create a new module, maybe based on L<JSON::Tiny>, which is smaller and written in a much cleaner way than this module. =head1 SEE ALSO The F<json_pp> command line utility for quick experiments. L<JSON::XS>, L<Cpanel::JSON::XS>, and L<JSON::Tiny> for faster alternatives. L<JSON> and L<JSON::MaybeXS> for easy migration. L<JSON::backportPP::Compat5005> and L<JSON::backportPP::Compat5006> for older perl users. RFC4627 (L<http://www.ietf.org/rfc/rfc4627.txt>) RFC7159 (L<http://www.ietf.org/rfc/rfc7159.txt>) RFC8259 (L<http://www.ietf.org/rfc/rfc8259.txt>) =head1 AUTHOR Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt> =head1 CURRENT MAINTAINER Kenichi Ishigaki, E<lt>ishigaki[at]cpan.orgE<gt> =head1 COPYRIGHT AND LICENSE Copyright 2007-2016 by Makamaka Hannyaharamitu Most of the documentation is taken from JSON::XS by Marc Lehmann This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[ lib/auto/JSON/.existsnu �[��� PK � �[A��B6� 6� lib/JSON.pmnu ��6�$ package JSON; use strict; use Carp (); use Exporter; BEGIN { @JSON::ISA = 'Exporter' } @JSON::EXPORT = qw(from_json to_json jsonToObj objToJson encode_json decode_json); BEGIN { $JSON::VERSION = '4.10'; $JSON::DEBUG = 0 unless (defined $JSON::DEBUG); $JSON::DEBUG = $ENV{ PERL_JSON_DEBUG } if exists $ENV{ PERL_JSON_DEBUG }; } my %RequiredVersion = ( 'JSON::PP' => '2.27203', 'JSON::XS' => '2.34', ); # XS and PP common methods my @PublicMethods = qw/ ascii latin1 utf8 pretty indent space_before space_after relaxed canonical allow_nonref allow_blessed convert_blessed filter_json_object filter_json_single_key_object shrink max_depth max_size encode decode decode_prefix allow_unknown /; my @Properties = qw/ ascii latin1 utf8 indent space_before space_after relaxed canonical allow_nonref allow_blessed convert_blessed shrink max_depth max_size allow_unknown /; my @XSOnlyMethods = qw//; # Currently nothing my @PublicMethodsSince4_0 = qw/allow_tags/; my @PropertiesSince4_0 = qw/allow_tags/; my @PPOnlyMethods = qw/ indent_length sort_by allow_singlequote allow_bignum loose allow_barekey escape_slash as_nonblessed /; # JSON::PP specific # used in _load_xs and _load_pp ($INSTALL_ONLY is not used currently) my $_INSTALL_DONT_DIE = 1; # When _load_xs fails to load XS, don't die. my $_ALLOW_UNSUPPORTED = 0; my $_UNIV_CONV_BLESSED = 0; # Check the environment variable to decide worker module. unless ($JSON::Backend) { $JSON::DEBUG and Carp::carp("Check used worker module..."); my $backend = exists $ENV{PERL_JSON_BACKEND} ? $ENV{PERL_JSON_BACKEND} : 1; if ($backend eq '1') { $backend = 'JSON::XS,JSON::PP'; } elsif ($backend eq '0') { $backend = 'JSON::PP'; } elsif ($backend eq '2') { $backend = 'JSON::XS'; } $backend =~ s/\s+//g; my @backend_modules = split /,/, $backend; while(my $module = shift @backend_modules) { if ($module =~ /JSON::XS/) { _load_xs($module, @backend_modules ? $_INSTALL_DONT_DIE : 0); } elsif ($module =~ /JSON::PP/) { _load_pp($module); } elsif ($module =~ /JSON::backportPP/) { _load_pp($module); } else { Carp::croak "The value of environmental variable 'PERL_JSON_BACKEND' is invalid."; } last if $JSON::Backend; } } sub import { my $pkg = shift; my @what_to_export; my $no_export; for my $tag (@_) { if ($tag eq '-support_by_pp') { if (!$_ALLOW_UNSUPPORTED++) { JSON::Backend::XS ->support_by_pp(@PPOnlyMethods) if ($JSON::Backend->is_xs); } next; } elsif ($tag eq '-no_export') { $no_export++, next; } elsif ( $tag eq '-convert_blessed_universally' ) { my $org_encode = $JSON::Backend->can('encode'); eval q| require B; local $^W; no strict 'refs'; *{"${JSON::Backend}\::encode"} = sub { # only works with Perl 5.18+ local *UNIVERSAL::TO_JSON = sub { my $b_obj = B::svref_2object( $_[0] ); return $b_obj->isa('B::HV') ? { %{ $_[0] } } : $b_obj->isa('B::AV') ? [ @{ $_[0] } ] : undef ; }; $org_encode->(@_); }; | if ( !$_UNIV_CONV_BLESSED++ ); next; } push @what_to_export, $tag; } return if ($no_export); __PACKAGE__->export_to_level(1, $pkg, @what_to_export); } # OBSOLETED sub jsonToObj { my $alternative = 'from_json'; if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) { shift @_; $alternative = 'decode'; } Carp::carp "'jsonToObj' will be obsoleted. Please use '$alternative' instead."; return JSON::from_json(@_); }; sub objToJson { my $alternative = 'to_json'; if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) { shift @_; $alternative = 'encode'; } Carp::carp "'objToJson' will be obsoleted. Please use '$alternative' instead."; JSON::to_json(@_); }; # INTERFACES sub to_json ($@) { if ( ref($_[0]) eq 'JSON' or (@_ > 2 and $_[0] eq 'JSON') ) { Carp::croak "to_json should not be called as a method."; } my $json = JSON->new; if (@_ == 2 and ref $_[1] eq 'HASH') { my $opt = $_[1]; for my $method (keys %$opt) { $json->$method( $opt->{$method} ); } } $json->encode($_[0]); } sub from_json ($@) { if ( ref($_[0]) eq 'JSON' or $_[0] eq 'JSON' ) { Carp::croak "from_json should not be called as a method."; } my $json = JSON->new; if (@_ == 2 and ref $_[1] eq 'HASH') { my $opt = $_[1]; for my $method (keys %$opt) { $json->$method( $opt->{$method} ); } } return $json->decode( $_[0] ); } sub true { $JSON::true } sub false { $JSON::false } sub boolean { # might be called as method or as function, so pop() to get the last arg instead of shift() to get the first pop() ? $JSON::true : $JSON::false } sub null { undef; } sub require_xs_version { $RequiredVersion{'JSON::XS'}; } sub backend { my $proto = shift; $JSON::Backend; } #*module = *backend; sub is_xs { return $_[0]->backend->is_xs; } sub is_pp { return $_[0]->backend->is_pp; } sub pureperl_only_methods { @PPOnlyMethods; } sub property { my ($self, $name, $value) = @_; if (@_ == 1) { my %props; for $name (@Properties) { my $method = 'get_' . $name; if ($name eq 'max_size') { my $value = $self->$method(); $props{$name} = $value == 1 ? 0 : $value; next; } $props{$name} = $self->$method(); } return \%props; } elsif (@_ > 3) { Carp::croak('property() can take only the option within 2 arguments.'); } elsif (@_ == 2) { if ( my $method = $self->can('get_' . $name) ) { if ($name eq 'max_size') { my $value = $self->$method(); return $value == 1 ? 0 : $value; } $self->$method(); } } else { $self->$name($value); } } # INTERNAL sub __load_xs { my ($module, $opt) = @_; $JSON::DEBUG and Carp::carp "Load $module."; my $required_version = $RequiredVersion{$module} || ''; eval qq| use $module $required_version (); |; if ($@) { if (defined $opt and $opt & $_INSTALL_DONT_DIE) { $JSON::DEBUG and Carp::carp "Can't load $module...($@)"; return 0; } Carp::croak $@; } $JSON::BackendModuleXS = $module; return 1; } sub _load_xs { my ($module, $opt) = @_; __load_xs($module, $opt) or return; my $data = join("", <DATA>); # this code is from Jcode 2.xx. close(DATA); eval $data; JSON::Backend::XS->init($module); return 1; }; sub __load_pp { my ($module, $opt) = @_; $JSON::DEBUG and Carp::carp "Load $module."; my $required_version = $RequiredVersion{$module} || ''; eval qq| use $module $required_version () |; if ($@) { if ( $module eq 'JSON::PP' ) { $JSON::DEBUG and Carp::carp "Can't load $module ($@), so try to load JSON::backportPP"; $module = 'JSON::backportPP'; local $^W; # if PP installed but invalid version, backportPP redefines methods. eval qq| require $module |; } Carp::croak $@ if $@; } $JSON::BackendModulePP = $module; return 1; } sub _load_pp { my ($module, $opt) = @_; __load_pp($module, $opt); JSON::Backend::PP->init($module); }; # # Helper classes for Backend Module (PP) # package JSON::Backend::PP; sub init { my ($class, $module) = @_; # name may vary, but the module should (always) be a JSON::PP local $^W; no strict qw(refs); # this routine may be called after JSON::Backend::XS init was called. *{"JSON::decode_json"} = \&{"JSON::PP::decode_json"}; *{"JSON::encode_json"} = \&{"JSON::PP::encode_json"}; *{"JSON::is_bool"} = \&{"JSON::PP::is_bool"}; $JSON::true = ${"JSON::PP::true"}; $JSON::false = ${"JSON::PP::false"}; push @JSON::Backend::PP::ISA, 'JSON::PP'; push @JSON::ISA, $class; $JSON::Backend = $class; $JSON::BackendModule = $module; my $version = ${"$class\::VERSION"} = $module->VERSION; $version =~ s/_//; if ($version < 3.99) { push @XSOnlyMethods, qw/allow_tags get_allow_tags/; } else { push @Properties, 'allow_tags'; } for my $method (@XSOnlyMethods) { *{"JSON::$method"} = sub { Carp::carp("$method is not supported by $module $version."); $_[0]; }; } return 1; } sub is_xs { 0 }; sub is_pp { 1 }; # # To save memory, the below lines are read only when XS backend is used. # package JSON; 1; __DATA__ # # Helper classes for Backend Module (XS) # package JSON::Backend::XS; sub init { my ($class, $module) = @_; local $^W; no strict qw(refs); *{"JSON::decode_json"} = \&{"$module\::decode_json"}; *{"JSON::encode_json"} = \&{"$module\::encode_json"}; *{"JSON::is_bool"} = \&{"$module\::is_bool"}; $JSON::true = ${"$module\::true"}; $JSON::false = ${"$module\::false"}; push @JSON::Backend::XS::ISA, $module; push @JSON::ISA, $class; $JSON::Backend = $class; $JSON::BackendModule = $module; ${"$class\::VERSION"} = $module->VERSION; if ( $module->VERSION < 3 ) { eval 'package JSON::PP::Boolean'; push @{"$module\::Boolean::ISA"}, qw(JSON::PP::Boolean); } for my $method (@PPOnlyMethods) { *{"JSON::$method"} = sub { Carp::carp("$method is not supported by $module."); $_[0]; }; } return 1; } sub is_xs { 1 }; sub is_pp { 0 }; sub support_by_pp { my ($class, @methods) = @_; JSON::__load_pp('JSON::PP'); local $^W; no strict qw(refs); for my $method (@methods) { my $pp_method = JSON::PP->can($method) or next; *{"JSON::$method"} = sub { if (!$_[0]->isa('JSON::PP')) { my $xs_self = $_[0]; my $pp_self = JSON::PP->new; for (@Properties) { my $getter = "get_$_"; $pp_self->$_($xs_self->$getter); } $_[0] = $pp_self; } $pp_method->(@_); }; } $JSON::DEBUG and Carp::carp("set -support_by_pp mode."); } 1; __END__ =head1 NAME JSON - JSON (JavaScript Object Notation) encoder/decoder =head1 SYNOPSIS use JSON; # imports encode_json, decode_json, to_json and from_json. # simple and fast interfaces (expect/generate UTF-8) $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; # OO-interface $json = JSON->new->allow_nonref; $json_text = $json->encode( $perl_scalar ); $perl_scalar = $json->decode( $json_text ); $pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing =head1 DESCRIPTION This module is a thin wrapper for L<JSON::XS>-compatible modules with a few additional features. All the backend modules convert a Perl data structure to a JSON text and vice versa. This module uses L<JSON::XS> by default, and when JSON::XS is not available, falls back on L<JSON::PP>, which is in the Perl core since 5.14. If JSON::PP is not available either, this module then falls back on JSON::backportPP (which is actually JSON::PP in a different .pm file) bundled in the same distribution as this module. You can also explicitly specify to use L<Cpanel::JSON::XS>, a fork of JSON::XS by Reini Urban. All these backend modules have slight incompatibilities between them, including extra features that other modules don't support, but as long as you use only common features (most important ones are described below), migration from backend to backend should be reasonably easy. For details, see each backend module you use. =head1 CHOOSING BACKEND This module respects an environmental variable called C<PERL_JSON_BACKEND> when it decides a backend module to use. If this environmental variable is not set, it tries to load JSON::XS, and if JSON::XS is not available, it falls back on JSON::PP, and then JSON::backportPP if JSON::PP is not available either. If you always don't want it to fall back on pure perl modules, set the variable like this (C<export> may be C<setenv>, C<set> and the likes, depending on your environment): > export PERL_JSON_BACKEND=JSON::XS If you prefer Cpanel::JSON::XS to JSON::XS, then: > export PERL_JSON_BACKEND=Cpanel::JSON::XS,JSON::XS,JSON::PP You may also want to set this variable at the top of your test files, in order not to be bothered with incompatibilities between backends (you need to wrap this in C<BEGIN>, and set before actually C<use>-ing JSON module, as it decides its backend as soon as it's loaded): BEGIN { $ENV{PERL_JSON_BACKEND}='JSON::backportPP'; } use JSON; =head1 USING OPTIONAL FEATURES There are a few options you can set when you C<use> this module. These historical options are only kept for backward compatibility, and should not be used in a new application. =over =item -support_by_pp BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' } use JSON -support_by_pp; my $json = JSON->new; # escape_slash is for JSON::PP only. $json->allow_nonref->escape_slash->encode("/"); With this option, this module loads its pure perl backend along with its XS backend (if available), and lets the XS backend to watch if you set a flag only JSON::PP supports. When you do, the internal JSON::XS object is replaced with a newly created JSON::PP object with the setting copied from the XS object, so that you can use JSON::PP flags (and its slower C<decode>/C<encode> methods) from then on. In other words, this is not something that allows you to hook JSON::XS to change its behavior while keeping its speed. JSON::XS and JSON::PP objects are quite different (JSON::XS object is a blessed scalar reference, while JSON::PP object is a blessed hash reference), and can't share their internals. To avoid needless overhead (by copying settings), you are advised not to use this option and just to use JSON::PP explicitly when you need JSON::PP features. =item -convert_blessed_universally use JSON -convert_blessed_universally; my $json = JSON->new->allow_nonref->convert_blessed; my $object = bless {foo => 'bar'}, 'Foo'; $json->encode($object); # => {"foo":"bar"} JSON::XS-compatible backend modules don't encode blessed objects by default (except for their boolean values, which are typically blessed JSON::PP::Boolean objects). If you need to encode a data structure that may contain objects, you usually need to look into the structure and replace objects with alternative non-blessed values, or enable C<convert_blessed> and provide a C<TO_JSON> method for each object's (base) class that may be found in the structure, in order to let the methods replace the objects with whatever scalar values the methods return. If you need to serialise data structures that may contain arbitrary objects, it's probably better to use other serialisers (such as L<Sereal> or L<Storable> for example), but if you do want to use this module for that purpose, C<-convert_blessed_universally> option may help, which tweaks C<encode> method of the backend to install C<UNIVERSAL::TO_JSON> method (locally) before encoding, so that all the objects that don't have their own C<TO_JSON> method can fall back on the method in the C<UNIVERSAL> namespace. Note that you still need to enable C<convert_blessed> flag to actually encode objects in a data structure, and C<UNIVERSAL::TO_JSON> method installed by this option only converts blessed hash/array references into their unblessed clone (including private keys/values that are not supposed to be exposed). Other blessed references will be converted into null. This feature is experimental and may be removed in the future. =item -no_export When you don't want to import functional interfaces from a module, you usually supply C<()> to its C<use> statement. use JSON (); # no functional interfaces If you don't want to import functional interfaces, but you also want to use any of the above options, add C<-no_export> to the option list. # no functional interfaces, while JSON::PP support is enabled. use JSON -support_by_pp, -no_export; =back =head1 FUNCTIONAL INTERFACE This section is taken from JSON::XS. C<encode_json> and C<decode_json> are exported by default. This module also exports C<to_json> and C<from_json> for backward compatibility. These are slower, and may expect/generate different stuff from what C<encode_json> and C<decode_json> do, depending on their options. It's better just to use Object-Oriented interfaces than using these two functions. =head2 encode_json $json_text = encode_json $perl_scalar Converts the given Perl data structure to a UTF-8 encoded, binary string (that is, the string contains octets only). Croaks on error. This function call is functionally identical to: $json_text = JSON->new->utf8->encode($perl_scalar) Except being faster. =head2 decode_json $perl_scalar = decode_json $json_text The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries to parse that as an UTF-8 encoded JSON text, returning the resulting reference. Croaks on error. This function call is functionally identical to: $perl_scalar = JSON->new->utf8->decode($json_text) Except being faster. =head2 to_json $json_text = to_json($perl_scalar[, $optional_hashref]) Converts the given Perl data structure to a Unicode string by default. Croaks on error. Basically, this function call is functionally identical to: $json_text = JSON->new->encode($perl_scalar) Except being slower. You can pass an optional hash reference to modify its behavior, but that may change what C<to_json> expects/generates (see C<ENCODING/CODESET FLAG NOTES> for details). $json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1}) # => JSON->new->utf8(1)->pretty(1)->encode($perl_scalar) =head2 from_json $perl_scalar = from_json($json_text[, $optional_hashref]) The opposite of C<to_json>: expects a Unicode string and tries to parse it, returning the resulting reference. Croaks on error. Basically, this function call is functionally identical to: $perl_scalar = JSON->new->decode($json_text) You can pass an optional hash reference to modify its behavior, but that may change what C<from_json> expects/generates (see C<ENCODING/CODESET FLAG NOTES> for details). $perl_scalar = from_json($json_text, {utf8 => 1}) # => JSON->new->utf8(1)->decode($json_text) =head2 JSON::is_bool $is_boolean = JSON::is_bool($scalar) Returns true if the passed scalar represents either JSON::true or JSON::false, two constants that act like C<1> and C<0> respectively and are also used to represent JSON C<true> and C<false> in Perl strings. See L<MAPPING>, below, for more information on how JSON values are mapped to Perl. =head1 COMMON OBJECT-ORIENTED INTERFACE This section is also taken from JSON::XS. The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. =head2 new $json = JSON->new Creates a new JSON::XS-compatible backend object that can be used to de/encode JSON strings. All boolean flags described below are by default I<disabled> (with the exception of C<allow_nonref>, which defaults to I<enabled> since version C<4.0>). The mutators for flags all return the backend object again and thus calls can be chained: my $json = JSON->new->utf8->space_after->encode({a => [1,2]}) => {"a": [1, 2]} =head2 ascii $json = $json->ascii([$enable]) $enabled = $json->get_ascii If C<$enable> is true (or missing), then the C<encode> method will not generate characters outside the code range C<0..127> (which is ASCII). Any Unicode characters outside that range will be escaped using either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. The resulting encoded JSON text can be treated as a native Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, or any other superset of ASCII. If C<$enable> is false, then the C<encode> method will not escape Unicode characters unless required by the JSON syntax or other flags. This results in a faster and more compact format. See also the section I<ENCODING/CODESET FLAG NOTES> later in this document. The main use for this flag is to produce JSON texts that can be transmitted over a 7-bit channel, as the encoded JSON texts will not contain any 8 bit characters. JSON->new->ascii(1)->encode([chr 0x10401]) => ["\ud801\udc01"] =head2 latin1 $json = $json->latin1([$enable]) $enabled = $json->get_latin1 If C<$enable> is true (or missing), then the C<encode> method will encode the resulting JSON text as latin1 (or iso-8859-1), escaping any characters outside the code range C<0..255>. The resulting string can be treated as a latin1-encoded JSON text or a native Unicode string. The C<decode> method will not be affected in any way by this flag, as C<decode> by default expects Unicode, which is a strict superset of latin1. If C<$enable> is false, then the C<encode> method will not escape Unicode characters unless required by the JSON syntax or other flags. See also the section I<ENCODING/CODESET FLAG NOTES> later in this document. The main use for this flag is efficiently encoding binary data as JSON text, as most octets will not be escaped, resulting in a smaller encoded size. The disadvantage is that the resulting JSON text is encoded in latin1 (and must correctly be treated as such when storing and transferring), a rare encoding for JSON. It is therefore most useful when you want to store data structures known to contain binary data efficiently in files or databases, not when talking to other JSON encoders/decoders. JSON->new->latin1->encode (["\x{89}\x{abc}"] => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) =head2 utf8 $json = $json->utf8([$enable]) $enabled = $json->get_utf8 If C<$enable> is true (or missing), then the C<encode> method will encode the JSON result into UTF-8, as required by many protocols, while the C<decode> method expects to be handled an UTF-8-encoded string. Please note that UTF-8-encoded strings do not contain any characters outside the range C<0..255>, they are thus useful for bytewise/binary I/O. In future versions, enabling this option might enable autodetection of the UTF-16 and UTF-32 encoding families, as described in RFC4627. If C<$enable> is false, then the C<encode> method will return the JSON string as a (non-encoded) Unicode string, while C<decode> expects thus a Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs to be done yourself, e.g. using the Encode module. See also the section I<ENCODING/CODESET FLAG NOTES> later in this document. Example, output UTF-16BE-encoded JSON: use Encode; $jsontext = encode "UTF-16BE", JSON->new->encode ($object); Example, decode UTF-32LE-encoded JSON: use Encode; $object = JSON->new->decode (decode "UTF-32LE", $jsontext); =head2 pretty $json = $json->pretty([$enable]) This enables (or disables) all of the C<indent>, C<space_before> and C<space_after> (and in the future possibly more) flags in one call to generate the most readable (or most compact) form possible. =head2 indent $json = $json->indent([$enable]) $enabled = $json->get_indent If C<$enable> is true (or missing), then the C<encode> method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, indenting them properly. If C<$enable> is false, no newlines or indenting will be produced, and the resulting JSON text is guaranteed not to contain any C<newlines>. This setting has no effect when decoding JSON texts. =head2 space_before $json = $json->space_before([$enable]) $enabled = $json->get_space_before If C<$enable> is true (or missing), then the C<encode> method will add an extra optional space before the C<:> separating keys from values in JSON objects. If C<$enable> is false, then the C<encode> method will not add any extra space at those places. This setting has no effect when decoding JSON texts. You will also most likely combine this setting with C<space_after>. Example, space_before enabled, space_after and indent disabled: {"key" :"value"} =head2 space_after $json = $json->space_after([$enable]) $enabled = $json->get_space_after If C<$enable> is true (or missing), then the C<encode> method will add an extra optional space after the C<:> separating keys from values in JSON objects and extra whitespace after the C<,> separating key-value pairs and array members. If C<$enable> is false, then the C<encode> method will not add any extra space at those places. This setting has no effect when decoding JSON texts. Example, space_before and indent disabled, space_after enabled: {"key": "value"} =head2 relaxed $json = $json->relaxed([$enable]) $enabled = $json->get_relaxed If C<$enable> is true (or missing), then C<decode> will accept some extensions to normal JSON syntax (see below). C<encode> will not be affected in any way. I<Be aware that this option makes you accept invalid JSON texts as if they were valid!>. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) If C<$enable> is false (the default), then C<decode> will only accept valid JSON texts. Currently accepted extensions are: =over 4 =item * list items can have an end-comma JSON I<separates> array elements and key-value pairs with commas. This can be annoying if you write JSON texts manually and want to be able to quickly append elements, so this extension accepts comma at the end of such items not just between them: [ 1, 2, <- this comma not normally allowed ] { "k1": "v1", "k2": "v2", <- this comma not normally allowed } =item * shell-style '#'-comments Whenever JSON allows whitespace, shell-style comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. [ 1, # this comment not allowed in JSON # neither this one... ] =back =head2 canonical $json = $json->canonical([$enable]) $enabled = $json->get_canonical If C<$enable> is true (or missing), then the C<encode> method will output JSON objects by sorting their keys. This is adding a comparatively high overhead. If C<$enable> is false, then the C<encode> method will output key-value pairs in the order Perl stores them (which will likely change between runs of the same script, and can change even within the same run from 5.18 onwards). This option is useful if you want the same data structure to be encoded as the same JSON text (given the same overall settings). If it is disabled, the same hash might be encoded differently even if contains the same data, as key-value pairs have no inherent ordering in Perl. This setting has no effect when decoding JSON texts. This setting has currently no effect on tied hashes. =head2 allow_nonref $json = $json->allow_nonref([$enable]) $enabled = $json->get_allow_nonref Unlike other boolean options, this option is enabled by default beginning with version C<4.0>. If C<$enable> is true (or missing), then the C<encode> method can convert a non-reference into its corresponding string, number or null JSON value, which is an extension to RFC4627. Likewise, C<decode> will accept those JSON values instead of croaking. If C<$enable> is false, then the C<encode> method will croak if it isn't passed an arrayref or hashref, as JSON texts must either be an object or array. Likewise, C<decode> will croak if given something that is not a JSON object or array. Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, resulting in an invalid JSON text: JSON->new->allow_nonref->encode ("Hello, World!") => "Hello, World!" =head2 allow_unknown $json = $json->allow_unknown ([$enable]) $enabled = $json->get_allow_unknown If C<$enable> is true (or missing), then C<encode> will I<not> throw an exception when it encounters values it cannot represent in JSON (for example, filehandles) but instead will encode a JSON C<null> value. Note that blessed objects are not included here and are handled separately by c<allow_blessed>. If C<$enable> is false (the default), then C<encode> will throw an exception when it encounters anything it cannot encode as JSON. This option does not affect C<decode> in any way, and it is recommended to leave it off unless you know your communications partner. =head2 allow_blessed $json = $json->allow_blessed([$enable]) $enabled = $json->get_allow_blessed See L<OBJECT SERIALISATION> for details. If C<$enable> is true (or missing), then the C<encode> method will not barf when it encounters a blessed reference that it cannot convert otherwise. Instead, a JSON C<null> value is encoded instead of the object. If C<$enable> is false (the default), then C<encode> will throw an exception when it encounters a blessed object that it cannot convert otherwise. This setting has no effect on C<decode>. =head2 convert_blessed $json = $json->convert_blessed([$enable]) $enabled = $json->get_convert_blessed See L<OBJECT SERIALISATION> for details. If C<$enable> is true (or missing), then C<encode>, upon encountering a blessed object, will check for the availability of the C<TO_JSON> method on the object's class. If found, it will be called in scalar context and the resulting scalar will be encoded instead of the object. The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> returns other blessed objects, those will be handled in the same way. C<TO_JSON> must take care of not causing an endless recursion cycle (== crash) in this case. The name of C<TO_JSON> was chosen because other methods called by the Perl core (== not by the user of the object) are usually in upper case letters and to avoid collisions with any C<to_json> function or method. If C<$enable> is false (the default), then C<encode> will not consider this type of conversion. This setting has no effect on C<decode>. =head2 allow_tags (since version 3.0) $json = $json->allow_tags([$enable]) $enabled = $json->get_allow_tags See L<OBJECT SERIALISATION> for details. If C<$enable> is true (or missing), then C<encode>, upon encountering a blessed object, will check for the availability of the C<FREEZE> method on the object's class. If found, it will be used to serialise the object into a nonstandard tagged JSON value (that JSON decoders cannot decode). It also causes C<decode> to parse such tagged JSON values and deserialise them via a call to the C<THAW> method. If C<$enable> is false (the default), then C<encode> will not consider this type of conversion, and tagged JSON values will cause a parse error in C<decode>, as if tags were not part of the grammar. =head2 boolean_values (since version 4.0) $json->boolean_values([$false, $true]) ($false, $true) = $json->get_boolean_values By default, JSON booleans will be decoded as overloaded C<$JSON::false> and C<$JSON::true> objects. With this method you can specify your own boolean values for decoding - on decode, JSON C<false> will be decoded as a copy of C<$false>, and JSON C<true> will be decoded as C<$true> ("copy" here is the same thing as assigning a value to another variable, i.e. C<$copy = $false>). This is useful when you want to pass a decoded data structure directly to other serialisers like YAML, Data::MessagePack and so on. Note that this works only when you C<decode>. You can set incompatible boolean objects (like L<boolean>), but when you C<encode> a data structure with such boolean objects, you still need to enable C<convert_blessed> (and add a C<TO_JSON> method if necessary). Calling this method without any arguments will reset the booleans to their default values. C<get_boolean_values> will return both C<$false> and C<$true> values, or the empty list when they are set to the default. =head2 filter_json_object $json = $json->filter_json_object([$coderef]) When C<$coderef> is specified, it will be called from C<decode> each time it decodes a JSON object. The only argument is a reference to the newly-created hash. If the code references returns a single scalar (which need not be a reference), this value (or rather a copy of it) is inserted into the deserialised data structure. If it returns an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the original deserialised hash will be inserted. This setting can slow down decoding considerably. When C<$coderef> is omitted or undefined, any existing callback will be removed and C<decode> will not change the deserialised hash in any way. Example, convert all JSON objects into the integer 5: my $js = JSON->new->filter_json_object(sub { 5 }); # returns [5] $js->decode('[{}]'); # returns 5 $js->decode('{"a":1, "b":2}'); =head2 filter_json_single_key_object $json = $json->filter_json_single_key_object($key [=> $coderef]) Works remotely similar to C<filter_json_object>, but is only called for JSON objects having a single key named C<$key>. This C<$coderef> is called before the one specified via C<filter_json_object>, if any. It gets passed the single value in the JSON object. If it returns a single value, it will be inserted into the data structure. If it returns nothing (not even C<undef> but the empty list), the callback from C<filter_json_object> will be called next, as if no single-key callback were specified. If C<$coderef> is omitted or undefined, the corresponding callback will be disabled. There can only ever be one callback for a given key. As this callback gets called less often then the C<filter_json_object> one, decoding speed will not usually suffer as much. Therefore, single-key objects make excellent targets to serialise Perl objects into, especially as single-key JSON objects are as close to the type-tagged value concept as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not support this in any way, so you need to make sure your data never looks like a serialised Perl hash. Typical names for the single object key are C<__class_whatever__>, or C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even things like C<__class_md5sum(classname)__>, to reduce the risk of clashing with real hashes. Example, decode JSON objects of the form C<< { "__widget__" => <id> } >> into the corresponding C<< $WIDGET{<id>} >> object: # return whatever is in $WIDGET{5}: JSON ->new ->filter_json_single_key_object (__widget__ => sub { $WIDGET{ $_[0] } }) ->decode ('{"__widget__": 5') # this can be used with a TO_JSON method in some "widget" class # for serialisation to json: sub WidgetBase::TO_JSON { my ($self) = @_; unless ($self->{id}) { $self->{id} = ..get..some..id..; $WIDGET{$self->{id}} = $self; } { __widget__ => $self->{id} } } =head2 max_depth $json = $json->max_depth([$maximum_nesting_depth]) $max_depth = $json->get_max_depth Sets the maximum nesting level (default C<512>) accepted while encoding or decoding. If a higher nesting level is detected in JSON text or a Perl data structure, then the encoder and decoder will stop and croak at that point. Nesting level is defined by number of hash- or arrayrefs that the encoder needs to traverse to reach a given point or the number of C<{> or C<[> characters without their matching closing parenthesis crossed to reach a given character in a string. Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. If no argument is given, the highest possible setting will be used, which is rarely useful. See L<JSON::XS/SECURITY CONSIDERATIONS> for more info on why this is useful. =head2 max_size $json = $json->max_size([$maximum_string_size]) $max_size = $json->get_max_size Set the maximum length a JSON text may have (in bytes) where decoding is being attempted. The default is C<0>, meaning no limit. When C<decode> is called on a string that is longer then this many bytes, it will not attempt to decode the string but throw an exception. This setting has no effect on C<encode> (yet). If no argument is given, the limit check will be deactivated (same as when C<0> is specified). See L<JSON::XS/SECURITY CONSIDERATIONS> for more info on why this is useful. =head2 encode $json_text = $json->encode($perl_scalar) Converts the given Perl value or data structure to its JSON representation. Croaks on error. =head2 decode $perl_scalar = $json->decode($json_text) The opposite of C<encode>: expects a JSON text and tries to parse it, returning the resulting simple scalar or reference. Croaks on error. =head2 decode_prefix ($perl_scalar, $characters) = $json->decode_prefix($json_text) This works like the C<decode> method, but instead of raising an exception when there is trailing garbage after the first JSON object, it will silently stop parsing there and return the number of characters consumed so far. This is useful if your JSON texts are not delimited by an outer protocol and you need to know where the JSON text ends. JSON->new->decode_prefix ("[1] the tail") => ([1], 3) =head1 ADDITIONAL METHODS The following methods are for this module only. =head2 backend $backend = $json->backend Since 2.92, C<backend> method returns an abstract backend module used currently, which should be JSON::Backend::XS (which inherits JSON::XS or Cpanel::JSON::XS), or JSON::Backend::PP (which inherits JSON::PP), not to monkey-patch the actual backend module globally. If you need to know what is used actually, use C<isa>, instead of string comparison. =head2 is_xs $boolean = $json->is_xs Returns true if the backend inherits JSON::XS or Cpanel::JSON::XS. =head2 is_pp $boolean = $json->is_pp Returns true if the backend inherits JSON::PP. =head2 property $settings = $json->property() Returns a reference to a hash that holds all the common flag settings. $json = $json->property('utf8' => 1) $value = $json->property('utf8') # 1 You can use this to get/set a value of a particular flag. =head2 boolean $boolean_object = JSON->boolean($scalar) Returns $JSON::true if $scalar contains a true value, $JSON::false otherwise. You can use this as a full-qualified function (C<JSON::boolean($scalar)>). =head1 INCREMENTAL PARSING This section is also taken from JSON::XS. In some cases, there is the need for incremental parsing of JSON texts. While this module always has to keep both JSON text and resulting Perl data structure in memory at one time, it does allow you to parse a JSON stream incrementally. It does so by accumulating text until it has a full JSON object, which it then can decode. This process is similar to using C<decode_prefix> to see if a full JSON object is available, but is much more efficient (and can be implemented with a minimum of method calls). This module will only attempt to parse the JSON text once it is sure it has enough text to get a decisive result, using a very simple but truly incremental parser. This means that it sometimes won't stop as early as the full parser, for example, it doesn't detect mismatched parentheses. The only thing it guarantees is that it starts decoding as soon as a syntactically valid JSON text has been seen. This means you need to set resource limits (e.g. C<max_size>) to ensure the parser will stop parsing in the presence if syntax errors. The following methods implement this incremental parser. =head2 incr_parse $json->incr_parse( [$string] ) # void context $obj_or_undef = $json->incr_parse( [$string] ) # scalar context @obj_or_empty = $json->incr_parse( [$string] ) # list context This is the central parsing function. It can both append new text and extract objects from the stream accumulated so far (both of these functions are optional). If C<$string> is given, then this string is appended to the already existing JSON fragment stored in the C<$json> object. After that, if the function is called in void context, it will simply return without doing anything further. This can be used to add more text in as many chunks as you want. If the method is called in scalar context, then it will try to extract exactly I<one> JSON object. If that is successful, it will return this object, otherwise it will return C<undef>. If there is a parse error, this method will croak just as C<decode> would do (one can then use C<incr_skip> to skip the erroneous part). This is the most common way of using the method. And finally, in list context, it will try to extract as many objects from the stream as it can find and return them, or the empty list otherwise. For this to work, there must be no separators (other than whitespace) between the JSON objects or arrays, instead they must be concatenated back-to-back. If an error occurs, an exception will be raised as in the scalar context case. Note that in this case, any previously-parsed JSON texts will be lost. Example: Parse some JSON arrays/objects in a given string and return them. my @objs = JSON->new->incr_parse ("[5][7][1,2]"); =head2 incr_text $lvalue_string = $json->incr_text This method returns the currently stored JSON fragment as an lvalue, that is, you can manipulate it. This I<only> works when a preceding call to C<incr_parse> in I<scalar context> successfully returned an object. Under all other circumstances you must not call this function (I mean it. although in simple tests it might actually work, it I<will> fail under real world conditions). As a special exception, you can also call this method before having parsed anything. That means you can only use this function to look at or manipulate text before or after complete JSON objects, not while the parser is in the middle of parsing a JSON object. This function is useful in two cases: a) finding the trailing text after a JSON object or b) parsing multiple JSON objects separated by non-JSON text (such as commas). =head2 incr_skip $json->incr_skip This will reset the state of the incremental parser and will remove the parsed text from the input buffer so far. This is useful after C<incr_parse> died, in which case the input buffer and incremental parser state is left unchanged, to skip the text parsed so far and to reset the parse state. The difference to C<incr_reset> is that only text until the parse error occurred is removed. =head2 incr_reset $json->incr_reset This completely resets the incremental parser, that is, after this call, it will be as if the parser had never parsed anything. This is useful if you want to repeatedly parse JSON objects and want to ignore any trailing data, which means you have to reset the parser after each successful decode. =head1 MAPPING Most of this section is also taken from JSON::XS. This section describes how the backend modules map Perl values to JSON values and vice versa. These mappings are designed to "do the right thing" in most circumstances automatically, preserving round-tripping characteristics (what you put in comes out as something equivalent). For the more enlightened: note that in the following descriptions, lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl> refers to the abstract Perl language itself. =head2 JSON -> PERL =over 4 =item object A JSON object becomes a reference to a hash in Perl. No ordering of object keys is preserved (JSON does not preserver object key ordering itself). =item array A JSON array becomes a reference to an array in Perl. =item string A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON are represented by the same codepoints in the Perl string, so no manual decoding is necessary. =item number A JSON number becomes either an integer, numeric (floating point) or string scalar in perl, depending on its range and any fractional parts. On the Perl level, there is no difference between those as Perl handles all the conversion details, but an integer may take slightly less memory and might represent more values exactly than floating point numbers. If the number consists of digits only, this module will try to represent it as an integer value. If that fails, it will try to represent it as a numeric (floating point) value if that is possible without loss of precision. Otherwise it will preserve the number as a string value (in which case you lose roundtripping ability, as the JSON number will be re-encoded to a JSON string). Numbers containing a fractional or exponential part will always be represented as numeric (floating point) values, possibly at a loss of precision (in which case you might lose perfect roundtripping ability, but the JSON number will still be re-encoded as a JSON number). Note that precision is not accuracy - binary floating point values cannot represent most decimal fractions exactly, and when converting from and to floating point, this module only guarantees precision up to but not including the least significant bit. =item true, false These JSON atoms become C<JSON::true> and C<JSON::false>, respectively. They are overloaded to act almost exactly like the numbers C<1> and C<0>. You can check whether a scalar is a JSON boolean by using the C<JSON::is_bool> function. =item null A JSON null atom becomes C<undef> in Perl. =item shell-style comments (C<< # I<text> >>) As a nonstandard extension to the JSON syntax that is enabled by the C<relaxed> setting, shell-style comments are allowed. They can start anywhere outside strings and go till the end of the line. =item tagged values (C<< (I<tag>)I<value> >>). Another nonstandard extension to the JSON syntax, enabled with the C<allow_tags> setting, are tagged values. In this implementation, the I<tag> must be a perl package/class name encoded as a JSON string, and the I<value> must be a JSON array encoding optional constructor arguments. See L<OBJECT SERIALISATION>, below, for details. =back =head2 PERL -> JSON The mapping from Perl to JSON is slightly more difficult, as Perl is a truly typeless language, so we can only guess which JSON type is meant by a Perl value. =over 4 =item hash references Perl hash references become JSON objects. As there is no inherent ordering in hash keys (or JSON objects), they will usually be encoded in a pseudo-random order. This module can optionally sort the hash keys (determined by the I<canonical> flag), so the same data structure will serialise to the same JSON text (given same settings and version of the same backend), but this incurs a runtime overhead and is only rarely useful, e.g. when you want to compare some JSON text against another for equality. =item array references Perl array references become JSON arrays. =item other references Other unblessed references are generally not allowed and will cause an exception to be thrown, except for references to the integers C<0> and C<1>, which get turned into C<false> and C<true> atoms in JSON. You can also use C<JSON::false> and C<JSON::true> to improve readability. encode_json [\0,JSON::true] # yields [false,true] =item JSON::true, JSON::false, JSON::null These special values become JSON true and JSON false values, respectively. You can also use C<\1> and C<\0> directly if you want. =item blessed objects Blessed objects are not directly representable in JSON, but C<JSON::XS> allows various ways of handling objects. See L<OBJECT SERIALISATION>, below, for details. =item simple scalars Simple Perl scalars (any scalar that is not a reference) are the most difficult objects to encode: this module will encode undefined scalars as JSON C<null> values, scalars that have last been used in a string context before encoding as JSON strings, and anything else as number value: # dump as number encode_json [2] # yields [2] encode_json [-3.0e17] # yields [-3e+17] my $value = 5; encode_json [$value] # yields [5] # used as string, so dump as string print $value; encode_json [$value] # yields ["5"] # undef becomes null encode_json [undef] # yields [null] You can force the type to be a string by stringifying it: my $x = 3.1; # some variable containing a number "$x"; # stringified $x .= ""; # another, more awkward way to stringify print $x; # perl does it for you, too, quite often You can force the type to be a number by numifying it: my $x = "3"; # some variable containing a string $x += 0; # numify it, ensuring it will be dumped as a number $x *= 1; # same thing, the choice is yours. You can not currently force the type in other, less obscure, ways. Tell me if you need this capability (but don't forget to explain why it's needed :). Since version 2.91_01, JSON::PP uses a different number detection logic that converts a scalar that is possible to turn into a number safely. The new logic is slightly faster, and tends to help people who use older perl or who want to encode complicated data structure. However, this may results in a different JSON text from the one JSON::XS encodes (and thus may break tests that compare entire JSON texts). If you do need the previous behavior for better compatibility or for finer control, set PERL_JSON_PP_USE_B environmental variable to true before you C<use> JSON. Note that numerical precision has the same meaning as under Perl (so binary to decimal conversion follows the same rules as in Perl, which can differ to other languages). Also, your perl interpreter might expose extensions to the floating point numbers of your platform, such as infinities or NaN's - these cannot be represented in JSON, and it is an error to pass those in. JSON.pm backend modules trust what you pass to C<encode> method (or C<encode_json> function) is a clean, validated data structure with values that can be represented as valid JSON values only, because it's not from an external data source (as opposed to JSON texts you pass to C<decode> or C<decode_json>, which JSON backends consider tainted and don't trust). As JSON backends don't know exactly what you and consumers of your JSON texts want the unexpected values to be (you may want to convert them into null, or to stringify them with or without normalisation (string representation of infinities/NaN may vary depending on platforms), or to croak without conversion), you're advised to do what you and your consumers need before you encode, and also not to numify values that may start with values that look like a number (including infinities/NaN), without validating. =back =head2 OBJECT SERIALISATION As JSON cannot directly represent Perl objects, you have to choose between a pure JSON representation (without the ability to deserialise the object automatically again), and a nonstandard extension to the JSON syntax, tagged values. =head3 SERIALISATION What happens when this module encounters a Perl object depends on the C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are used in this order: =over 4 =item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method. In this case, C<JSON> creates a tagged JSON value, using a nonstandard extension to the JSON syntax. This works by invoking the C<FREEZE> method on the object, with the first argument being the object to serialise, and the second argument being the constant string C<JSON> to distinguish it from other serialisers. The C<FREEZE> method can return any number of values (i.e. zero or more). These values and the package/classname of the object will then be encoded as a tagged JSON value in the following format: ("classname")[FREEZE return values...] e.g.: ("URI")["http://www.google.com/"] ("MyDate")[2013,10,29] ("ImageData::JPEG")["Z3...VlCg=="] For example, the hypothetical C<My::Object> C<FREEZE> method might use the objects C<type> and C<id> members to encode the object: sub My::Object::FREEZE { my ($self, $serialiser) = @_; ($self->{type}, $self->{id}) } =item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method. In this case, the C<TO_JSON> method of the object is invoked in scalar context. It must return a single scalar that can be directly encoded into JSON. This scalar replaces the object in the JSON text. For example, the following C<TO_JSON> method will convert all L<URI> objects to JSON strings when serialised. The fact that these values originally were L<URI> objects is lost. sub URI::TO_JSON { my ($uri) = @_; $uri->as_string } =item 3. C<allow_blessed> is enabled. The object will be serialised as a JSON null value. =item 4. none of the above If none of the settings are enabled or the respective methods are missing, this module throws an exception. =back =head3 DESERIALISATION For deserialisation there are only two cases to consider: either nonstandard tagging was used, in which case C<allow_tags> decides, or objects cannot be automatically be deserialised, in which case you can use postprocessing or the C<filter_json_object> or C<filter_json_single_key_object> callbacks to get some real objects our of your JSON. This section only considers the tagged value case: a tagged JSON object is encountered during decoding and C<allow_tags> is disabled, a parse error will result (as if tagged values were not part of the grammar). If C<allow_tags> is enabled, this module will look up the C<THAW> method of the package/classname used during serialisation (it will not attempt to load the package as a Perl module). If there is no such method, the decoding will fail with an error. Otherwise, the C<THAW> method is invoked with the classname as first argument, the constant string C<JSON> as second argument, and all the values from the JSON array (the values originally returned by the C<FREEZE> method) as remaining arguments. The method must then return the object. While technically you can return any Perl scalar, you might have to enable the C<allow_nonref> setting to make that work in all cases, so better return an actual blessed reference. As an example, let's implement a C<THAW> function that regenerates the C<My::Object> from the C<FREEZE> example earlier: sub My::Object::THAW { my ($class, $serialiser, $type, $id) = @_; $class->new (type => $type, id => $id) } =head1 ENCODING/CODESET FLAG NOTES This section is taken from JSON::XS. The interested reader might have seen a number of flags that signify encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be some confusion on what these do, so here is a short comparison: C<utf8> controls whether the JSON text created by C<encode> (and expected by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only control whether C<encode> escapes character values outside their respective codeset range. Neither of these flags conflict with each other, although some combinations make less sense than others. Care has been taken to make all flags symmetrical with respect to C<encode> and C<decode>, that is, texts encoded with any combination of these flag values will be correctly decoded when the same flags are used - in general, if you use different flag settings while encoding vs. when decoding you likely have a bug somewhere. Below comes a verbose discussion of these flags. Note that a "codeset" is simply an abstract set of character-codepoint pairs, while an encoding takes those codepoint numbers and I<encodes> them, in our case into octets. Unicode is (among other things) a codeset, UTF-8 is an encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at the same time, which can be confusing. =over 4 =item C<utf8> flag disabled When C<utf8> is disabled (the default), then C<encode>/C<decode> generate and expect Unicode strings, that is, characters with high ordinal Unicode values (> 255) will be encoded as such characters, and likewise such characters are decoded as-is, no changes to them will be done, except "(re-)interpreting" them as Unicode codepoints or Unicode characters, respectively (to Perl, these are the same thing in strings unless you do funny/weird/dumb stuff). This is useful when you want to do the encoding yourself (e.g. when you want to have UTF-16 encoded JSON texts) or when some other layer does the encoding for you (for example, when printing to a terminal using a filehandle that transparently encodes to UTF-8 you certainly do NOT want to UTF-8 encode your data first and have Perl encode it another time). =item C<utf8> flag enabled If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all characters using the corresponding UTF-8 multi-byte sequence, and will expect your input strings to be encoded as UTF-8, that is, no "character" of the input string must have any value > 255, as UTF-8 does not allow that. The C<utf8> flag therefore switches between two modes: disabled means you will get a Unicode string in Perl, enabled means you get an UTF-8 encoded octet/binary string in Perl. =item C<latin1> or C<ascii> flags enabled With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining characters as specified by the C<utf8> flag. If C<utf8> is disabled, then the result is also correctly encoded in those character sets (as both are proper subsets of Unicode, meaning that a Unicode string with all character values < 256 is the same thing as a ISO-8859-1 string, and a Unicode string with all character values < 128 is the same thing as an ASCII string in Perl). If C<utf8> is enabled, you still get a correct UTF-8-encoded string, regardless of these flags, just some more characters will be escaped using C<\uXXXX> then before. Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8 encoding, while ASCII-encoded strings are. That is because the ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being a subset of Unicode), while ASCII is. Surprisingly, C<decode> will ignore these flags and so treat all input values as governed by the C<utf8> flag. If it is disabled, this allows you to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings. So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag - they only govern when the JSON output engine escapes a character or not. The main use for C<latin1> is to relatively efficiently store binary data as JSON, at the expense of breaking compatibility with most JSON decoders. The main use for C<ascii> is to force the output to not contain characters with values > 127, which means you can interpret the resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and 8-bit-encoding, and still get the same data structure back. This is useful when your channel for JSON transfer is not 8-bit clean or the encoding might be mangled in between (e.g. in mail), and works because ASCII is a proper subset of most 8-bit and multibyte encodings in use in the world. =back =head1 BACKWARD INCOMPATIBILITY Since version 2.90, stringification (and string comparison) for C<JSON::true> and C<JSON::false> has not been overloaded. It shouldn't matter as long as you treat them as boolean values, but a code that expects they are stringified as "true" or "false" doesn't work as you have expected any more. if (JSON::true eq 'true') { # now fails print "The result is $JSON::true now."; # => The result is 1 now. And now these boolean values don't inherit JSON::Boolean, either. When you need to test a value is a JSON boolean value or not, use C<JSON::is_bool> function, instead of testing the value inherits a particular boolean class or not. =head1 BUGS Please report bugs on backend selection and additional features this module provides to RT or GitHub issues for this module: L<https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON> L<https://github.com/makamaka/JSON/issues> As for bugs on a specific behavior, please report to the author of the backend module you are using. As for new features and requests to change common behaviors, please ask the author of JSON::XS (Marc Lehmann, E<lt>schmorp[at]schmorp.deE<gt>) first, by email (important!), to keep compatibility among JSON.pm backends. =head1 SEE ALSO L<JSON::XS>, L<Cpanel::JSON::XS>, L<JSON::PP> for backends. L<JSON::MaybeXS>, an alternative that prefers Cpanel::JSON::XS. C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>) RFC7159 (L<http://www.ietf.org/rfc/rfc7159.txt>) RFC8259 (L<http://www.ietf.org/rfc/rfc8259.txt>) =head1 AUTHOR Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt> JSON::XS was written by Marc Lehmann E<lt>schmorp[at]schmorp.deE<gt> The release of this new version owes to the courtesy of Marc Lehmann. =head1 CURRENT MAINTAINER Kenichi Ishigaki, E<lt>ishigaki[at]cpan.orgE<gt> =head1 COPYRIGHT AND LICENSE Copyright 2005-2013 by Makamaka Hannyaharamitu Most of the documentation is taken from JSON::XS by Marc Lehmann This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[Z >Y� � man3/Sub::Uplevel.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Sub::Uplevel 3" .TH Sub::Uplevel 3 "2017-04-01" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Sub::Uplevel \- apparently run a function in a higher stack frame .SH "VERSION" .IX Header "VERSION" version 0.2800 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Sub::Uplevel; \& \& sub foo { \& print join " \- ", caller; \& } \& \& sub bar { \& uplevel 1, \e&foo; \& } \& \& #line 11 \& bar(); # main \- foo.plx \- 11 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Like Tcl's \fBuplevel()\fR function, but not quite so dangerous. The idea is just to fool \fBcaller()\fR. All the really naughty bits of Tcl's \&\fBuplevel()\fR are avoided. .PP \&\fB\s-1THIS IS NOT THE SORT OF THING YOU WANT TO DO EVERYDAY\s0\fR .IP "\fBuplevel\fR" 4 .IX Item "uplevel" .Vb 1 \& uplevel $num_frames, \e&func, @args; .Ve .Sp Makes the given function think it's being executed \f(CW$num_frames\fR higher than the current stack level. So when they use caller($frames) it will actually give caller($frames + \f(CW$num_frames\fR) for them. .Sp \&\f(CW\*(C`uplevel(1, \e&some_func, @_)\*(C'\fR is effectively \f(CW\*(C`goto &some_func\*(C'\fR but you don't immediately exit the current subroutine. So while you can't do this: .Sp .Vb 5 \& sub wrapper { \& print "Before\en"; \& goto &some_func; \& print "After\en"; \& } .Ve .Sp you can do this: .Sp .Vb 6 \& sub wrapper { \& print "Before\en"; \& my @out = uplevel 1, &some_func; \& print "After\en"; \& return @out; \& } .Ve .Sp \&\f(CW\*(C`uplevel\*(C'\fR has the ability to issue a warning if \f(CW$num_frames\fR is more than the current call stack depth, although this warning is disabled and compiled out by default as the check is relatively expensive. .Sp To enable the check for debugging or testing, you should set the global \&\f(CW$Sub::Uplevel::CHECK_FRAMES\fR to true before loading Sub::Uplevel for the first time as follows: .Sp .Vb 1 \& #!/usr/bin/perl \& \& BEGIN { \& $Sub::Uplevel::CHECK_FRAMES = 1; \& } \& use Sub::Uplevel; .Ve .Sp Setting or changing the global after the module has been loaded will have no effect. .SH "EXAMPLE" .IX Header "EXAMPLE" The main reason I wrote this module is so I could write wrappers around functions and they wouldn't be aware they've been wrapped. .PP .Vb 1 \& use Sub::Uplevel; \& \& my $original_foo = \e&foo; \& \& *foo = sub { \& my @output = uplevel 1, $original_foo; \& print "foo() returned: @output"; \& return @output; \& }; .Ve .PP If this code frightens you \fByou should not use this module.\fR .SH "BUGS and CAVEATS" .IX Header "BUGS and CAVEATS" Well, the bad news is \fBuplevel()\fR is about 5 times slower than a normal function call. \s-1XS\s0 implementation anyone? It also slows down every invocation of \fBcaller()\fR, regardless of whether \fBuplevel()\fR is in effect. .PP Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of each uplevel call. It does its best to work with any previously existing CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within each uplevel call) such as from Contextual::Return or Hook::LexWrap. .PP However, if you are routinely using multiple modules that override CORE::GLOBAL::caller, you are probably asking for trouble. .PP You \fBshould\fR load Sub::Uplevel as early as possible within your program. As with all \s-1CORE::GLOBAL\s0 overloading, the overload will not affect modules that have already been compiled prior to the overload. One module that often is unavoidably loaded prior to Sub::Uplevel is Exporter. To forcibly recompile Exporter (and Exporter::Heavy) after loading Sub::Uplevel, use it with the \&\*(L":aggressive\*(R" tag: .PP .Vb 1 \& use Sub::Uplevel qw/:aggressive/; .Ve .PP The private function \f(CW\*(C`Sub::Uplevel::_force_reload()\*(C'\fR may be passed a list of additional modules to reload if \*(L":aggressive\*(R" is not aggressive enough. Reloading modules may break things, so only use this as a last resort. .PP As of version 0.20, Sub::Uplevel requires Perl 5.6 or greater. .SH "HISTORY" .IX Header "HISTORY" Those who do not learn from \s-1HISTORY\s0 are doomed to repeat it. .PP The lesson here is simple: Don't sit next to a Tcl programmer at the dinner table. .SH "THANKS" .IX Header "THANKS" Thanks to Brent Welch, Damian Conway and Robin Houston. .PP See http://www.perl.com/perl/misc/Artistic.html .SH "SEE ALSO" .IX Header "SEE ALSO" PadWalker (for the similar idea with lexicals), Hook::LexWrap, Tcl's \fBuplevel()\fR at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at <https://github.com/Perl\-Toolchain\-Gang/Sub\-Uplevel/issues>. You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP <https://github.com/Perl\-Toolchain\-Gang/Sub\-Uplevel> .PP .Vb 1 \& git clone https://github.com/Perl\-Toolchain\-Gang/Sub\-Uplevel.git .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Michael Schwern <mschwern@cpan.org> .IP "\(bu" 4 David Golden <dagolden@cpan.org> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Adam Kennedy <adamk@cpan.org> .IP "\(bu" 4 Alexandr Ciornii <alexchorny@gmail.com> .IP "\(bu" 4 David Golden <xdg@xdg.me> .IP "\(bu" 4 Graham Ollis <plicease@cpan.org> .IP "\(bu" 4 J. Nick Koston <nick@cpanel.net> .IP "\(bu" 4 Michael Gray <mg13@sanger.ac.uk> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2017 by Michael Schwern and David Golden. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ arch/auto/Sub/Uplevel/.existsnu �[��� PK � �[ lib/auto/Sub/Uplevel/.existsnu �[��� PK � �[ lib/Sub/.existsnu �[��� PK � �[�&�5�F �F lib/Sub/Uplevel.pmnu ��6�$ package Sub::Uplevel; use 5.006; use strict; # ABSTRACT: apparently run a function in a higher stack frame our $VERSION = '0.2800'; # Frame check global constant our $CHECK_FRAMES; BEGIN { $CHECK_FRAMES = !! $CHECK_FRAMES; } use constant CHECK_FRAMES => $CHECK_FRAMES; # We must override *CORE::GLOBAL::caller if it hasn't already been # overridden or else Perl won't see our local override later. if ( not defined *CORE::GLOBAL::caller{CODE} ) { *CORE::GLOBAL::caller = \&_normal_caller; } # modules to force reload if ":aggressive" is specified my @reload_list = qw/Exporter Exporter::Heavy/; sub import { no strict 'refs'; ## no critic my ($class, @args) = @_; for my $tag ( @args, 'uplevel' ) { if ( $tag eq 'uplevel' ) { my $caller = caller(0); *{"$caller\::uplevel"} = \&uplevel; } elsif( $tag eq ':aggressive' ) { _force_reload( @reload_list ); } else { die qq{"$tag" is not exported by the $class module\n} } } return; } sub _force_reload { no warnings 'redefine'; local $^W = 0; for my $m ( @_ ) { $m =~ s{::}{/}g; $m .= ".pm"; require $m if delete $INC{$m}; } } #pod =head1 SYNOPSIS #pod #pod use Sub::Uplevel; #pod #pod sub foo { #pod print join " - ", caller; #pod } #pod #pod sub bar { #pod uplevel 1, \&foo; #pod } #pod #pod #line 11 #pod bar(); # main - foo.plx - 11 #pod #pod =head1 DESCRIPTION #pod #pod Like Tcl's uplevel() function, but not quite so dangerous. The idea #pod is just to fool caller(). All the really naughty bits of Tcl's #pod uplevel() are avoided. #pod #pod B<THIS IS NOT THE SORT OF THING YOU WANT TO DO EVERYDAY> #pod #pod =over 4 #pod #pod =item B<uplevel> #pod #pod uplevel $num_frames, \&func, @args; #pod #pod Makes the given function think it's being executed $num_frames higher #pod than the current stack level. So when they use caller($frames) it #pod will actually give caller($frames + $num_frames) for them. #pod #pod C<uplevel(1, \&some_func, @_)> is effectively C<goto &some_func> but #pod you don't immediately exit the current subroutine. So while you can't #pod do this: #pod #pod sub wrapper { #pod print "Before\n"; #pod goto &some_func; #pod print "After\n"; #pod } #pod #pod you can do this: #pod #pod sub wrapper { #pod print "Before\n"; #pod my @out = uplevel 1, &some_func; #pod print "After\n"; #pod return @out; #pod } #pod #pod C<uplevel> has the ability to issue a warning if C<$num_frames> is more than #pod the current call stack depth, although this warning is disabled and compiled #pod out by default as the check is relatively expensive. #pod #pod To enable the check for debugging or testing, you should set the global #pod C<$Sub::Uplevel::CHECK_FRAMES> to true before loading Sub::Uplevel for the #pod first time as follows: #pod #pod #!/usr/bin/perl #pod #pod BEGIN { #pod $Sub::Uplevel::CHECK_FRAMES = 1; #pod } #pod use Sub::Uplevel; #pod #pod Setting or changing the global after the module has been loaded will have #pod no effect. #pod #pod =cut # @Up_Frames -- uplevel stack # $Caller_Proxy -- whatever caller() override was in effect before uplevel our (@Up_Frames, $Caller_Proxy); sub _apparent_stack_height { my $height = 1; # start above this function while ( 1 ) { last if ! defined scalar $Caller_Proxy->($height); $height++; } return $height - 1; # subtract 1 for this function } sub uplevel { # Backwards compatible version of "no warnings 'redefine'" my $old_W = $^W; $^W = 0; # Update the caller proxy if the uplevel override isn't in effect local $Caller_Proxy = *CORE::GLOBAL::caller{CODE} if *CORE::GLOBAL::caller{CODE} != \&_uplevel_caller; local *CORE::GLOBAL::caller = \&_uplevel_caller; # Restore old warnings state $^W = $old_W; if ( CHECK_FRAMES and $_[0] >= _apparent_stack_height() ) { require Carp; Carp::carp("uplevel $_[0] is more than the caller stack"); } local @Up_Frames = (shift, @Up_Frames ); my $function = shift; return $function->(@_); } sub _normal_caller (;$) { ## no critic Prototypes my ($height) = @_; $height++; my @caller = CORE::caller($height); if ( CORE::caller() eq 'DB' ) { # Oops, redo picking up @DB::args package DB; @caller = CORE::caller($height); } return if ! @caller; # empty return $caller[0] if ! wantarray; # scalar context return @_ ? @caller : @caller[0..2]; # extra info or regular } sub _uplevel_caller (;$) { ## no critic Prototypes my $height = $_[0] || 0; # shortcut if no uplevels have been called # always add +1 to CORE::caller (proxy caller function) # to skip this function's caller return $Caller_Proxy->( $height + 1 ) if ! @Up_Frames; #pod =begin _private #pod #pod So it has to work like this: #pod #pod Call stack Actual uplevel 1 #pod CORE::GLOBAL::caller #pod Carp::short_error_loc 0 #pod Carp::shortmess_heavy 1 0 #pod Carp::croak 2 1 #pod try_croak 3 2 #pod uplevel 4 #pod function_that_called_uplevel 5 #pod caller_we_want_to_see 6 3 #pod its_caller 7 4 #pod #pod So when caller(X) winds up below uplevel(), it only has to use #pod CORE::caller(X+1) (to skip CORE::GLOBAL::caller). But when caller(X) #pod winds up no or above uplevel(), it's CORE::caller(X+1+uplevel+1). #pod #pod Which means I'm probably going to have to do something nasty like walk #pod up the call stack on each caller() to see if I'm going to wind up #pod before or after Sub::Uplevel::uplevel(). #pod #pod =end _private #pod #pod =begin _dagolden #pod #pod I found the description above a bit confusing. Instead, this is the logic #pod that I found clearer when CORE::GLOBAL::caller is invoked and we have to #pod walk up the call stack: #pod #pod * if searching up to the requested height in the real call stack doesn't find #pod a call to uplevel, then we can return the result at that height in the #pod call stack #pod #pod * if we find a call to uplevel, we need to keep searching upwards beyond the #pod requested height at least by the amount of upleveling requested for that #pod call to uplevel (from the Up_Frames stack set during the uplevel call) #pod #pod * additionally, we need to hide the uplevel subroutine call, too, so we search #pod upwards one more level for each call to uplevel #pod #pod * when we've reached the top of the search, we want to return that frame #pod in the call stack, i.e. the requested height plus any uplevel adjustments #pod found during the search #pod #pod =end _dagolden #pod #pod =cut my $saw_uplevel = 0; my $adjust = 0; # walk up the call stack to fight the right package level to return; # look one higher than requested for each call to uplevel found # and adjust by the amount found in the Up_Frames stack for that call. # We *must* use CORE::caller here since we need the real stack not what # some other override says the stack looks like, just in case that other # override breaks things in some horrible way my $test_caller; for ( my $up = 0; $up <= $height + $adjust; $up++ ) { $test_caller = scalar CORE::caller($up + 1); if( $test_caller && $test_caller eq __PACKAGE__ ) { # add one for each uplevel call seen # and look into the uplevel stack for the offset $adjust += 1 + $Up_Frames[$saw_uplevel]; $saw_uplevel++; } } # For returning values, we pass through the call to the proxy caller # function, just at a higher stack level my @caller = $Caller_Proxy->($height + $adjust + 1); if ( CORE::caller() eq 'DB' ) { # Oops, redo picking up @DB::args package DB; @caller = $Sub::Uplevel::Caller_Proxy->($height + $adjust + 1); } return if ! @caller; # empty return $caller[0] if ! wantarray; # scalar context return @_ ? @caller : @caller[0..2]; # extra info or regular } #pod =back #pod #pod =head1 EXAMPLE #pod #pod The main reason I wrote this module is so I could write wrappers #pod around functions and they wouldn't be aware they've been wrapped. #pod #pod use Sub::Uplevel; #pod #pod my $original_foo = \&foo; #pod #pod *foo = sub { #pod my @output = uplevel 1, $original_foo; #pod print "foo() returned: @output"; #pod return @output; #pod }; #pod #pod If this code frightens you B<you should not use this module.> #pod #pod #pod =head1 BUGS and CAVEATS #pod #pod Well, the bad news is uplevel() is about 5 times slower than a normal #pod function call. XS implementation anyone? It also slows down every invocation #pod of caller(), regardless of whether uplevel() is in effect. #pod #pod Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of #pod each uplevel call. It does its best to work with any previously existing #pod CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within #pod each uplevel call) such as from Contextual::Return or Hook::LexWrap. #pod #pod However, if you are routinely using multiple modules that override #pod CORE::GLOBAL::caller, you are probably asking for trouble. #pod #pod You B<should> load Sub::Uplevel as early as possible within your program. As #pod with all CORE::GLOBAL overloading, the overload will not affect modules that #pod have already been compiled prior to the overload. One module that often is #pod unavoidably loaded prior to Sub::Uplevel is Exporter. To forcibly recompile #pod Exporter (and Exporter::Heavy) after loading Sub::Uplevel, use it with the #pod ":aggressive" tag: #pod #pod use Sub::Uplevel qw/:aggressive/; #pod #pod The private function C<Sub::Uplevel::_force_reload()> may be passed a list of #pod additional modules to reload if ":aggressive" is not aggressive enough. #pod Reloading modules may break things, so only use this as a last resort. #pod #pod As of version 0.20, Sub::Uplevel requires Perl 5.6 or greater. #pod #pod =head1 HISTORY #pod #pod Those who do not learn from HISTORY are doomed to repeat it. #pod #pod The lesson here is simple: Don't sit next to a Tcl programmer at the #pod dinner table. #pod #pod =head1 THANKS #pod #pod Thanks to Brent Welch, Damian Conway and Robin Houston. #pod #pod See http://www.perl.com/perl/misc/Artistic.html #pod #pod =head1 SEE ALSO #pod #pod PadWalker (for the similar idea with lexicals), Hook::LexWrap, #pod Tcl's uplevel() at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm #pod #pod =cut 1; __END__ =pod =encoding UTF-8 =head1 NAME Sub::Uplevel - apparently run a function in a higher stack frame =head1 VERSION version 0.2800 =head1 SYNOPSIS use Sub::Uplevel; sub foo { print join " - ", caller; } sub bar { uplevel 1, \&foo; } #line 11 bar(); # main - foo.plx - 11 =head1 DESCRIPTION Like Tcl's uplevel() function, but not quite so dangerous. The idea is just to fool caller(). All the really naughty bits of Tcl's uplevel() are avoided. B<THIS IS NOT THE SORT OF THING YOU WANT TO DO EVERYDAY> =over 4 =item B<uplevel> uplevel $num_frames, \&func, @args; Makes the given function think it's being executed $num_frames higher than the current stack level. So when they use caller($frames) it will actually give caller($frames + $num_frames) for them. C<uplevel(1, \&some_func, @_)> is effectively C<goto &some_func> but you don't immediately exit the current subroutine. So while you can't do this: sub wrapper { print "Before\n"; goto &some_func; print "After\n"; } you can do this: sub wrapper { print "Before\n"; my @out = uplevel 1, &some_func; print "After\n"; return @out; } C<uplevel> has the ability to issue a warning if C<$num_frames> is more than the current call stack depth, although this warning is disabled and compiled out by default as the check is relatively expensive. To enable the check for debugging or testing, you should set the global C<$Sub::Uplevel::CHECK_FRAMES> to true before loading Sub::Uplevel for the first time as follows: #!/usr/bin/perl BEGIN { $Sub::Uplevel::CHECK_FRAMES = 1; } use Sub::Uplevel; Setting or changing the global after the module has been loaded will have no effect. =begin _private So it has to work like this: Call stack Actual uplevel 1 CORE::GLOBAL::caller Carp::short_error_loc 0 Carp::shortmess_heavy 1 0 Carp::croak 2 1 try_croak 3 2 uplevel 4 function_that_called_uplevel 5 caller_we_want_to_see 6 3 its_caller 7 4 So when caller(X) winds up below uplevel(), it only has to use CORE::caller(X+1) (to skip CORE::GLOBAL::caller). But when caller(X) winds up no or above uplevel(), it's CORE::caller(X+1+uplevel+1). Which means I'm probably going to have to do something nasty like walk up the call stack on each caller() to see if I'm going to wind up before or after Sub::Uplevel::uplevel(). =end _private =begin _dagolden I found the description above a bit confusing. Instead, this is the logic that I found clearer when CORE::GLOBAL::caller is invoked and we have to walk up the call stack: * if searching up to the requested height in the real call stack doesn't find a call to uplevel, then we can return the result at that height in the call stack * if we find a call to uplevel, we need to keep searching upwards beyond the requested height at least by the amount of upleveling requested for that call to uplevel (from the Up_Frames stack set during the uplevel call) * additionally, we need to hide the uplevel subroutine call, too, so we search upwards one more level for each call to uplevel * when we've reached the top of the search, we want to return that frame in the call stack, i.e. the requested height plus any uplevel adjustments found during the search =end _dagolden =back =head1 EXAMPLE The main reason I wrote this module is so I could write wrappers around functions and they wouldn't be aware they've been wrapped. use Sub::Uplevel; my $original_foo = \&foo; *foo = sub { my @output = uplevel 1, $original_foo; print "foo() returned: @output"; return @output; }; If this code frightens you B<you should not use this module.> =head1 BUGS and CAVEATS Well, the bad news is uplevel() is about 5 times slower than a normal function call. XS implementation anyone? It also slows down every invocation of caller(), regardless of whether uplevel() is in effect. Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of each uplevel call. It does its best to work with any previously existing CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within each uplevel call) such as from Contextual::Return or Hook::LexWrap. However, if you are routinely using multiple modules that override CORE::GLOBAL::caller, you are probably asking for trouble. You B<should> load Sub::Uplevel as early as possible within your program. As with all CORE::GLOBAL overloading, the overload will not affect modules that have already been compiled prior to the overload. One module that often is unavoidably loaded prior to Sub::Uplevel is Exporter. To forcibly recompile Exporter (and Exporter::Heavy) after loading Sub::Uplevel, use it with the ":aggressive" tag: use Sub::Uplevel qw/:aggressive/; The private function C<Sub::Uplevel::_force_reload()> may be passed a list of additional modules to reload if ":aggressive" is not aggressive enough. Reloading modules may break things, so only use this as a last resort. As of version 0.20, Sub::Uplevel requires Perl 5.6 or greater. =head1 HISTORY Those who do not learn from HISTORY are doomed to repeat it. The lesson here is simple: Don't sit next to a Tcl programmer at the dinner table. =head1 THANKS Thanks to Brent Welch, Damian Conway and Robin Houston. See http://www.perl.com/perl/misc/Artistic.html =head1 SEE ALSO PadWalker (for the similar idea with lexicals), Hook::LexWrap, Tcl's uplevel() at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan =head1 SUPPORT =head2 Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at L<https://github.com/Perl-Toolchain-Gang/Sub-Uplevel/issues>. You will be notified automatically of any progress on your issue. =head2 Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. L<https://github.com/Perl-Toolchain-Gang/Sub-Uplevel> git clone https://github.com/Perl-Toolchain-Gang/Sub-Uplevel.git =head1 AUTHORS =over 4 =item * Michael Schwern <mschwern@cpan.org> =item * David Golden <dagolden@cpan.org> =back =head1 CONTRIBUTORS =for stopwords Adam Kennedy Alexandr Ciornii David Golden Graham Ollis J. Nick Koston Michael Gray =over 4 =item * Adam Kennedy <adamk@cpan.org> =item * Alexandr Ciornii <alexchorny@gmail.com> =item * David Golden <xdg@xdg.me> =item * Graham Ollis <plicease@cpan.org> =item * J. Nick Koston <nick@cpanel.net> =item * Michael Gray <mg13@sanger.ac.uk> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2017 by Michael Schwern and David Golden. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[z�>P� � man3/HTTP::Date.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::Date 3" .TH HTTP::Date 3 "2023-07-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::Date \- HTTP::Date \- date conversion routines .SH "VERSION" .IX Header "VERSION" version 6.06 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use HTTP::Date; \& \& $string = time2str($time); # Format as GMT ASCII time \& $time = str2time($string); # convert ASCII date to machine time .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides functions that deal the date formats used by the \&\s-1HTTP\s0 protocol (and then some more). Only the first two functions, \&\fBtime2str()\fR and \fBstr2time()\fR, are exported by default. .IP "time2str( [$time] )" 4 .IX Item "time2str( [$time] )" The \fBtime2str()\fR function converts a machine time (seconds since epoch) to a string. If the function is called without an argument or with an undefined argument, it will use the current time. .Sp The string returned is in the format preferred for the \s-1HTTP\s0 protocol. This is a fixed length subset of the format defined by \s-1RFC 1123,\s0 represented in Universal Time (\s-1GMT\s0). An example of a time stamp in this format is: .Sp .Vb 1 \& Sun, 06 Nov 1994 08:49:37 GMT .Ve .ie n .IP "str2time( $str [, $zone] )" 4 .el .IP "str2time( \f(CW$str\fR [, \f(CW$zone\fR] )" 4 .IX Item "str2time( $str [, $zone] )" The \fBstr2time()\fR function converts a string to machine time. It returns \&\f(CW\*(C`undef\*(C'\fR if the format of \f(CW$str\fR is unrecognized, otherwise whatever the \&\f(CW\*(C`Time::Local\*(C'\fR functions can make out of the parsed time. Dates before the system's epoch may not work on all operating systems. The time formats recognized are the same as for \fBparse_date()\fR. .Sp The function also takes an optional second argument that specifies the default time zone to use when converting the date. This parameter is ignored if the zone is found in the date string itself. If this parameter is missing, and the date string format does not contain any zone specification, then the local time zone is assumed. .Sp If the zone is not "\f(CW\*(C`GMT\*(C'\fR\*(L" or numerical (like \*(R"\f(CW\*(C`\-0800\*(C'\fR\*(L" or \&\*(R"\f(CW+0100\fR"), then the \f(CW\*(C`Time::Zone\*(C'\fR module must be installed in order to get the date recognized. .ie n .IP "parse_date( $str )" 4 .el .IP "parse_date( \f(CW$str\fR )" 4 .IX Item "parse_date( $str )" This function will try to parse a date string, and then return it as a list of numerical values followed by a (possible undefined) time zone specifier; ($year, \f(CW$month\fR, \f(CW$day\fR, \f(CW$hour\fR, \f(CW$min\fR, \f(CW$sec\fR, \f(CW$tz\fR). The \f(CW$year\fR will be the full 4\-digit year, and \f(CW$month\fR numbers start with 1 (for January). .Sp In scalar context the numbers are interpolated in a string of the \&\*(L"YYYY-MM-DD hh:mm:ss \s-1TZ\s0\*(R"\-format and returned. .Sp If the date is unrecognized, then the empty list is returned (\f(CW\*(C`undef\*(C'\fR in scalar context). .Sp The function is able to parse the following formats: .Sp .Vb 5 \& "Wed, 09 Feb 1994 22:23:32 GMT" \-\- HTTP format \& "Thu Feb 3 17:03:55 GMT 1994" \-\- ctime(3) format \& "Thu Feb 3 00:00:00 1994", \-\- ANSI C asctime() format \& "Tuesday, 08\-Feb\-94 14:15:29 GMT" \-\- old rfc850 HTTP format \& "Tuesday, 08\-Feb\-1994 14:15:29 GMT" \-\- broken rfc850 HTTP format \& \& "03/Feb/1994:17:03:55 \-0700" \-\- common logfile format \& "09 Feb 1994 22:23:32 GMT" \-\- HTTP format (no weekday) \& "08\-Feb\-94 14:15:29 GMT" \-\- rfc850 format (no weekday) \& "08\-Feb\-1994 14:15:29 GMT" \-\- broken rfc850 format (no weekday) \& \& "1994\-02\-03 14:15:29 \-0100" \-\- ISO 8601 format \& "1994\-02\-03 14:15:29" \-\- zone is optional \& "1994\-02\-03" \-\- only date \& "1994\-02\-03T14:15:29" \-\- Use T as separator \& "19940203T141529Z" \-\- ISO 8601 compact format \& "19940203" \-\- only date \& \& "08\-Feb\-94" \-\- old rfc850 HTTP format (no weekday, no time) \& "08\-Feb\-1994" \-\- broken rfc850 HTTP format (no weekday, no time) \& "09 Feb 1994" \-\- proposed new HTTP format (no weekday, no time) \& "03/Feb/1994" \-\- common logfile format (no time, no offset) \& \& "Feb 3 1994" \-\- Unix \*(Aqls \-l\*(Aq format \& "Feb 3 17:03" \-\- Unix \*(Aqls \-l\*(Aq format \& \& "11\-15\-96 03:52PM" \-\- Windows \*(Aqdir\*(Aq format \& "11\-15\-1996 03:52PM" \-\- Windows \*(Aqdir\*(Aq format with four\-digit year .Ve .Sp The parser ignores leading and trailing whitespace. It also allow the seconds to be missing and the month to be numerical in most formats. .Sp If the year is missing, then we assume that the date is the first matching date \fIbefore\fR current month. If the year is given with only 2 digits, then \fBparse_date()\fR will select the century that makes the year closest to the current date. .IP "time2iso( [$time] )" 4 .IX Item "time2iso( [$time] )" Same as \fBtime2str()\fR, but returns a \*(L"YYYY-MM-DD hh:mm:ss\*(R"\-formatted string representing time in the local time zone. .IP "time2isoz( [$time] )" 4 .IX Item "time2isoz( [$time] )" Same as \fBtime2str()\fR, but returns a \*(L"YYYY-MM-DD hh:mm:ssZ\*(R"\-formatted string representing Universal Time. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\*(L"time\*(R" in perlfunc, Time::Zone .SH "AUTHOR" .IX Header "AUTHOR" Gisle Aas <gisle@activestate.com> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 1995 by Gisle Aas. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ arch/auto/HTTP/Date/.existsnu �[��� PK � �[ lib/HTTP/.existsnu �[��� PK � �[t8��. �. lib/HTTP/Date.pmnu ��6�$ package HTTP::Date; use strict; our $VERSION = '6.06'; require Exporter; our @ISA = qw(Exporter); our @EXPORT = qw(time2str str2time); our @EXPORT_OK = qw(parse_date time2iso time2isoz); require Time::Local; our ( @DoW, @MoY, %MoY ); @DoW = qw(Sun Mon Tue Wed Thu Fri Sat); @MoY = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec); @MoY{@MoY} = ( 1 .. 12 ); my %GMT_ZONE = ( GMT => 1, UTC => 1, UT => 1, Z => 1 ); sub time2str (;$) { my $time = shift; $time = time unless defined $time; my ( $sec, $min, $hour, $mday, $mon, $year, $wday ) = gmtime($time); sprintf( "%s, %02d %s %04d %02d:%02d:%02d GMT", $DoW[$wday], $mday, $MoY[$mon], $year + 1900, $hour, $min, $sec ); } sub str2time ($;$) { my $str = shift; return undef unless defined $str; # fast exit for strictly conforming string if ( $str =~ /^[SMTWF][a-z][a-z], (\d\d) ([JFMAJSOND][a-z][a-z]) (\d\d\d\d) (\d\d):(\d\d):(\d\d) GMT$/ ) { return eval { my $t = Time::Local::timegm( $6, $5, $4, $1, $MoY{$2} - 1, $3 ); $t < 0 ? undef : $t; }; } my @d = parse_date($str); return undef unless @d; $d[1]--; # month my $tz = pop(@d); unless ( defined $tz ) { unless ( defined( $tz = shift ) ) { return eval { my $frac = $d[-1]; $frac -= ( $d[-1] = int($frac) ); my $t = Time::Local::timelocal( reverse @d ) + $frac; $t < 0 ? undef : $t; }; } } my $offset = 0; if ( $GMT_ZONE{ uc $tz } ) { # offset already zero } elsif ( $tz =~ /^([-+])?(\d\d?):?(\d\d)?$/ ) { $offset = 3600 * $2; $offset += 60 * $3 if $3; $offset *= -1 if $1 && $1 eq '-'; } else { eval { require Time::Zone } || return undef; $offset = Time::Zone::tz_offset($tz); return undef unless defined $offset; } return eval { my $frac = $d[-1]; $frac -= ( $d[-1] = int($frac) ); my $t = Time::Local::timegm( reverse @d ) + $frac; $t < 0 ? undef : $t - $offset; }; } sub parse_date ($) { local ($_) = shift; return unless defined; # More lax parsing below s/^\s+//; # kill leading space s/^(?:Sun|Mon|Tue|Wed|Thu|Fri|Sat)[a-z]*,?\s*//i; # Useless weekday my ( $day, $mon, $yr, $hr, $min, $sec, $tz, $ampm ); # Then we are able to check for most of the formats with this regexp ( ( $day, $mon, $yr, $hr, $min, $sec, $tz ) = /^ (\d\d?) # day (?:\s+|[-\/]) (\w+) # month (?:\s+|[-\/]) (\d+) # year (?: (?:\s+|:) # separator before clock (\d\d?):(\d\d) # hour:min (?::(\d\d))? # optional seconds )? # optional clock \s* ([-+]?\d{2,4}|(?![APap][Mm]\b)[A-Za-z]+)? # timezone \s* (?:\(\w+\)|\w{3,})? # ASCII representation of timezone. \s*$ /x ) || # Try the ctime and asctime format ( ( $mon, $day, $hr, $min, $sec, $tz, $yr ) = /^ (\w{1,3}) # month \s+ (\d\d?) # day \s+ (\d\d?):(\d\d) # hour:min (?::(\d\d))? # optional seconds \s+ (?:([A-Za-z]+)\s+)? # optional timezone (\d+) # year \s*$ # allow trailing whitespace /x ) || # Then the Unix 'ls -l' date format ( ( $mon, $day, $yr, $hr, $min, $sec ) = /^ (\w{3}) # month \s+ (\d\d?) # day \s+ (?: (\d\d\d\d) | # year (\d{1,2}):(\d{2}) # hour:min (?::(\d\d))? # optional seconds ) \s*$ /x ) || # ISO 8601 format '1996-02-29 12:00:00 -0100' and variants ( ( $yr, $mon, $day, $hr, $min, $sec, $tz ) = /^ (\d{4}) # year [-\/]? (\d\d?) # numerical month [-\/]? (\d\d?) # day (?: (?:\s+|[-:Tt]) # separator before clock (\d\d?):?(\d\d) # hour:min (?::?(\d\d(?:\.\d*)?))? # optional seconds (and fractional) )? # optional clock \s* ([-+]?\d\d?:?(:?\d\d)? |Z|z)? # timezone (Z is "zero meridian", i.e. GMT) \s*$ /x ) || # Windows 'dir': '11-12-96 03:52PM' and four-digit year variant ( ( $mon, $day, $yr, $hr, $min, $ampm ) = /^ (\d{2}) # numerical month - (\d{2}) # day - (\d{2,4}) # year \s+ (\d\d?):(\d\d)([APap][Mm]) # hour:min AM or PM \s*$ /x ) || return; # unrecognized format # Translate month name to number $mon = $MoY{$mon} || $MoY{"\u\L$mon"} || ( $mon =~ /^\d\d?$/ && $mon >= 1 && $mon <= 12 && int($mon) ) || return; # If the year is missing, we assume first date before the current, # because of the formats we support such dates are mostly present # on "ls -l" listings. unless ( defined $yr ) { my $cur_mon; ( $cur_mon, $yr ) = (localtime)[ 4, 5 ]; $yr += 1900; $cur_mon++; $yr-- if $mon > $cur_mon; } elsif ( length($yr) < 3 ) { # Find "obvious" year my $cur_yr = (localtime)[5] + 1900; my $m = $cur_yr % 100; my $tmp = $yr; $yr += $cur_yr - $m; $m -= $tmp; $yr += ( $m > 0 ) ? 100 : -100 if abs($m) > 50; } # Make sure clock elements are defined $hr = 0 unless defined($hr); $min = 0 unless defined($min); $sec = 0 unless defined($sec); # Compensate for AM/PM if ($ampm) { $ampm = uc $ampm; $hr = 0 if $hr == 12 && $ampm eq 'AM'; $hr += 12 if $ampm eq 'PM' && $hr != 12; } return ( $yr, $mon, $day, $hr, $min, $sec, $tz ) if wantarray; if ( defined $tz ) { $tz = "Z" if $tz =~ /^(GMT|UTC?|[-+]?0+)$/; } else { $tz = ""; } return sprintf( "%04d-%02d-%02d %02d:%02d:%02d%s", $yr, $mon, $day, $hr, $min, $sec, $tz ); } sub time2iso (;$) { my $time = shift; $time = time unless defined $time; my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time); sprintf( "%04d-%02d-%02d %02d:%02d:%02d", $year + 1900, $mon + 1, $mday, $hour, $min, $sec ); } sub time2isoz (;$) { my $time = shift; $time = time unless defined $time; my ( $sec, $min, $hour, $mday, $mon, $year ) = gmtime($time); sprintf( "%04d-%02d-%02d %02d:%02d:%02dZ", $year + 1900, $mon + 1, $mday, $hour, $min, $sec ); } 1; # ABSTRACT: HTTP::Date - date conversion routines # __END__ =pod =encoding UTF-8 =head1 NAME HTTP::Date - HTTP::Date - date conversion routines =head1 VERSION version 6.06 =head1 SYNOPSIS use HTTP::Date; $string = time2str($time); # Format as GMT ASCII time $time = str2time($string); # convert ASCII date to machine time =head1 DESCRIPTION This module provides functions that deal the date formats used by the HTTP protocol (and then some more). Only the first two functions, time2str() and str2time(), are exported by default. =over 4 =item time2str( [$time] ) The time2str() function converts a machine time (seconds since epoch) to a string. If the function is called without an argument or with an undefined argument, it will use the current time. The string returned is in the format preferred for the HTTP protocol. This is a fixed length subset of the format defined by RFC 1123, represented in Universal Time (GMT). An example of a time stamp in this format is: Sun, 06 Nov 1994 08:49:37 GMT =item str2time( $str [, $zone] ) The str2time() function converts a string to machine time. It returns C<undef> if the format of $str is unrecognized, otherwise whatever the C<Time::Local> functions can make out of the parsed time. Dates before the system's epoch may not work on all operating systems. The time formats recognized are the same as for parse_date(). The function also takes an optional second argument that specifies the default time zone to use when converting the date. This parameter is ignored if the zone is found in the date string itself. If this parameter is missing, and the date string format does not contain any zone specification, then the local time zone is assumed. If the zone is not "C<GMT>" or numerical (like "C<-0800>" or "C<+0100>"), then the C<Time::Zone> module must be installed in order to get the date recognized. =item parse_date( $str ) This function will try to parse a date string, and then return it as a list of numerical values followed by a (possible undefined) time zone specifier; ($year, $month, $day, $hour, $min, $sec, $tz). The $year will be the full 4-digit year, and $month numbers start with 1 (for January). In scalar context the numbers are interpolated in a string of the "YYYY-MM-DD hh:mm:ss TZ"-format and returned. If the date is unrecognized, then the empty list is returned (C<undef> in scalar context). The function is able to parse the following formats: "Wed, 09 Feb 1994 22:23:32 GMT" -- HTTP format "Thu Feb 3 17:03:55 GMT 1994" -- ctime(3) format "Thu Feb 3 00:00:00 1994", -- ANSI C asctime() format "Tuesday, 08-Feb-94 14:15:29 GMT" -- old rfc850 HTTP format "Tuesday, 08-Feb-1994 14:15:29 GMT" -- broken rfc850 HTTP format "03/Feb/1994:17:03:55 -0700" -- common logfile format "09 Feb 1994 22:23:32 GMT" -- HTTP format (no weekday) "08-Feb-94 14:15:29 GMT" -- rfc850 format (no weekday) "08-Feb-1994 14:15:29 GMT" -- broken rfc850 format (no weekday) "1994-02-03 14:15:29 -0100" -- ISO 8601 format "1994-02-03 14:15:29" -- zone is optional "1994-02-03" -- only date "1994-02-03T14:15:29" -- Use T as separator "19940203T141529Z" -- ISO 8601 compact format "19940203" -- only date "08-Feb-94" -- old rfc850 HTTP format (no weekday, no time) "08-Feb-1994" -- broken rfc850 HTTP format (no weekday, no time) "09 Feb 1994" -- proposed new HTTP format (no weekday, no time) "03/Feb/1994" -- common logfile format (no time, no offset) "Feb 3 1994" -- Unix 'ls -l' format "Feb 3 17:03" -- Unix 'ls -l' format "11-15-96 03:52PM" -- Windows 'dir' format "11-15-1996 03:52PM" -- Windows 'dir' format with four-digit year The parser ignores leading and trailing whitespace. It also allow the seconds to be missing and the month to be numerical in most formats. If the year is missing, then we assume that the date is the first matching date I<before> current month. If the year is given with only 2 digits, then parse_date() will select the century that makes the year closest to the current date. =item time2iso( [$time] ) Same as time2str(), but returns a "YYYY-MM-DD hh:mm:ss"-formatted string representing time in the local time zone. =item time2isoz( [$time] ) Same as time2str(), but returns a "YYYY-MM-DD hh:mm:ssZ"-formatted string representing Universal Time. =back =head1 SEE ALSO L<perlfunc/time>, L<Time::Zone> =head1 AUTHOR Gisle Aas <gisle@activestate.com> =head1 COPYRIGHT AND LICENSE This software is copyright (c) 1995 by Gisle Aas. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[ lib/auto/HTTP/Date/.existsnu �[��� PK � �[F���6 6 man3/Test::Deep::RegexpOnly.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::RegexpOnly 3" .TH Test::Deep::RegexpOnly 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::RegexpOnly .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[T�|�- - man3/Test::Deep::Shallow.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Shallow 3" .TH Test::Deep::Shallow 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Shallow .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ t�F3 3 man3/Test::Deep::RegexpRef.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::RegexpRef 3" .TH Test::Deep::RegexpRef 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::RegexpRef .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�h��� � man3/Test::Deep::NoTest.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::NoTest 3" .TH Test::Deep::NoTest 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::NoTest \- Use Test::Deep outside of the testing framework .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Test::Deep::NoTest; \& \& if (eq_deeply($a, $b)) { \& print "they were deeply equal\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This exports all the same things as Test::Deep but it does not load Test::Builder so it can be used in ordinary non-test situations. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[Q� _$ $ man3/Test::Deep::Hash.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Hash 3" .TH Test::Deep::Hash 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Hash .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�D^�! ! man3/Test::Deep::Ref.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Ref 3" .TH Test::Deep::Ref 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Ref .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�XQ�' ' man3/Test::Deep::Stack.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Stack 3" .TH Test::Deep::Stack 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Stack .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[r��- - man3/Test::Deep::Methods.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Methods 3" .TH Test::Deep::Methods 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Methods .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[����3 3 man3/Test::Deep::ArrayEach.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ArrayEach 3" .TH Test::Deep::ArrayEach 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ArrayEach .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��[* * man3/Test::Deep::Number.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Number 3" .TH Test::Deep::Number 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Number .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[J��' ' man3/Test::Deep::Cache.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Cache 3" .TH Test::Deep::Cache 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Cache .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�h8�< < ! man3/Test::Deep::HashKeysOnly.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::HashKeysOnly 3" .TH Test::Deep::HashKeysOnly 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::HashKeysOnly .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �["��n? ? " man3/Test::Deep::RegexpRefOnly.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::RegexpRefOnly 3" .TH Test::Deep::RegexpRefOnly 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::RegexpRefOnly .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[qco! ! man3/Test::Deep::Set.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Set 3" .TH Test::Deep::Set 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Set .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�[�q' ' man3/Test::Deep::Array.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Array 3" .TH Test::Deep::Array 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Array .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[v�+� man3/Test::Deep::MM.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::MM 3" .TH Test::Deep::MM 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::MM .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�T * * man3/Test::Deep::Regexp.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Regexp 3" .TH Test::Deep::Regexp 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Regexp .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��5? ? " man3/Test::Deep::RegexpMatches.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::RegexpMatches 3" .TH Test::Deep::RegexpMatches 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::RegexpMatches .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��H9 9 man3/Test::Deep::ListMethods.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ListMethods 3" .TH Test::Deep::ListMethods 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ListMethods .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��ӭ? ? " man3/Test::Deep::RegexpVersion.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::RegexpVersion 3" .TH Test::Deep::RegexpVersion 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::RegexpVersion .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ �4* * man3/Test::Deep::Ignore.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Ignore 3" .TH Test::Deep::Ignore 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Ignore .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��M- - man3/Test::Deep::Blessed.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Blessed 3" .TH Test::Deep::Blessed 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Blessed .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��l�9 9 man3/Test::Deep::ArrayLength.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ArrayLength 3" .TH Test::Deep::ArrayLength 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ArrayLength .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�L|�3 3 man3/Test::Deep::ScalarRef.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ScalarRef 3" .TH Test::Deep::ScalarRef 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ScalarRef .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�!��! ! man3/Test::Deep::All.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::All 3" .TH Test::Deep::All 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::All .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[��Lg! ! man3/Test::Deep::Any.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Any 3" .TH Test::Deep::Any 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Any .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[H�Y9< < ! man3/Test::Deep::HashElements.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::HashElements 3" .TH Test::Deep::HashElements 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::HashElements .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[���0 0 man3/Test::Deep::HashEach.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::HashEach 3" .TH Test::Deep::HashEach 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::HashEach .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[D�q� � man3/Test::Deep.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep 3" .TH Test::Deep 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep \- Extremely flexible deep comparison .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Test::More tests => $Num_Tests; \& use Test::Deep; \& \& cmp_deeply( \& $actual_horrible_nested_data_structure, \& $expected_horrible_nested_data_structure, \& "got the right horrible nested data structure" \& ); \& \& cmp_deeply( \& $object, \& methods(name => "John", phone => "55378008"), \& "object methods ok" \& ); \& \& cmp_deeply( \& \e@array, \& [$hash1, $hash2, ignore()], \& "first 2 elements are as expected, ignoring 3" \& ); \& \& cmp_deeply( \& $object, \& noclass({value => 5}), \& "object looks ok, not checking its class" \& ); \& \& cmp_deeply( \& \e@result, \& bag(\*(Aqa\*(Aq, \*(Aqb\*(Aq, {key => [1, 2]}), \& "array has the 3 things we wanted in some order" \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" If you don't know anything about automated testing in Perl then you should probably read about Test::Simple and Test::More before preceding. Test::Deep uses the Test::Builder framework. .PP Test::Deep gives you very flexible ways to check that the result you got is the result you were expecting. At its simplest it compares two structures by going through each level, ensuring that the values match, that arrays and hashes have the same elements and that references are blessed into the correct class. It also handles circular data structures without getting caught in an infinite loop. .PP Where it becomes more interesting is in allowing you to do something besides simple exact comparisons. With strings, the \f(CW\*(C`eq\*(C'\fR operator checks that 2 strings are exactly equal but sometimes that's not what you want. When you don't know exactly what the string should be but you do know some things about how it should look, \f(CW\*(C`eq\*(C'\fR is no good and you must use pattern matching instead. Test::Deep provides pattern matching for complex data structures .PP Test::Deep has \fB\f(BIa lot\fB\fR of exports. See \*(L"\s-1EXPORTS\*(R"\s0 below. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "EXAMPLES" .IX Header "EXAMPLES" How Test::Deep works is much easier to understand by seeing some examples. .SS "Without Test::Deep" .IX Subsection "Without Test::Deep" Say you want to test a function which returns a string. You know that your string should be a 7 digit number beginning with 0, \f(CW\*(C`eq\*(C'\fR is no good in this situation, you need a regular expression. So you could use Test::More's \&\f(CW\*(C`like()\*(C'\fR function: .PP .Vb 1 \& like($string, qr/^0[0\-9]{6}$/, "number looks good"); .Ve .PP Similarly, to check that a string looks like a name, you could do: .PP .Vb 2 \& like($string, qr/^(Mr|Mrs|Miss) \ew+ \ew+$/, \& "got title, first and last name"); .Ve .PP Now imagine your function produces a hash with some personal details in it. You want to make sure that there are 2 keys, Name and Phone and that the name looks like a name and the phone number looks like a phone number. You could do: .PP .Vb 4 \& $hash = make_person(); \& like($hash\->{Name}, qr/^(Mr|Mrs|Miss) \ew+ \ew+$/, "name ok"); \& like($hash\->{Phone}, qr/^0[0\-9]{6}$/, "phone ok"); \& is(scalar keys %$hash, 2, "correct number of keys"); .Ve .PP But that's not quite right, what if make_person has a serious problem and didn't even return a hash? We really need to write .PP .Vb 12 \& if (ref($hash) eq "HASH") \& { \& like($hash\->{Name}, qr/^(Mr|Mrs|Miss) \ew+ \ew+$/, "name ok"); \& like($hash\->{Phone}, qr/^0[0\-9]{6}$/, "phone ok"); \& is(scalar keys %$hash, 2, "correct number of keys"); \& } \& else \& { \& fail("person not a hash"); \& fail("person not a hash"); \& fail("person not a hash"); # need 3 to keep the plan correct \& } .Ve .PP Already this is getting messy, now imagine another entry in the hash, an array of children's names. This would require .PP .Vb 10 \& if (ref($hash) eq "HASH") \& { \& like($hash\->{Name}, $name_pat, "name ok"); \& like($hash\->{Phone}, \*(Aq/^0d{6}$/\*(Aq, "phone ok"); \& my $cn = $hash\->{ChildNames}; \& if (ref($cn) eq "ARRAY") \& { \& foreach my $child (@$cn) \& { \& like($child, $name_pat); \& } \& } \& else \& { \& fail("child names not an array") \& } \& } \& else \& { \& fail("person not a hash"); \& } .Ve .PP This is a horrible mess and because we don't know in advance how many children's names there will be, we can't make a plan for our test anymore (actually, we could but it would make things even more complicated). .PP Test::Deep to the rescue. .SS "With Test::Deep" .IX Subsection "With Test::Deep" .Vb 10 \& my $name_re = re(\*(Aq^(Mr|Mrs|Miss) \ew+ \ew+$\*(Aq); \& cmp_deeply( \& $person, \& { \& Name => $name_re, \& Phone => re(\*(Aq^0d{6}$\*(Aq), \& ChildNames => array_each($name_re) \& }, \& "person ok" \& ); .Ve .PP This will do everything that the messy code above does and it will give a sensible message telling you exactly what went wrong if it finds a part of \&\f(CW$person\fR that doesn't match the pattern. \f(CW\*(C`re()\*(C'\fR and \f(CW\*(C`array_each()\*(C'\fR are special function imported from Test::Deep. They create a marker that tells Test::Deep that something different is happening here. Instead of just doing a simple comparison and checking are two things exactly equal, it should do something else. .PP If a person was asked to check that 2 structures are equal, they could print them both out and compare them line by line. The markers above are similar to writing a note in red pen on one of the printouts telling the person that for this piece of the structure, they should stop doing simple line by line comparison and do something else. .PP \&\f(CW\*(C`re($regex)\*(C'\fR means that Test::Deep should check that the current piece of data matches the regex in \f(CW$regex\fR. \f(CW\*(C`array_each($struct)\*(C'\fR means that Test::Deep should expect the current piece of data to be an array and it should check that every element of that array matches \f(CW$struct\fR. In this case, every element of \f(CW\*(C`$person\->{ChildNames}\*(C'\fR should look like a name. If say the 3rd one didn't you would get an error message something like .PP .Vb 3 \& Using Regexp on $data\->{ChildNames}[3] \& got : \*(AqQueen John Paul Sartre\*(Aq \& expect : /^(Mr|Mrs|Miss) \ew+ \ew+$/ .Ve .PP There are lots of other special comparisons available, see \&\*(L"\s-1SPECIAL COMPARISONS PROVIDED\*(R"\s0 below for the full list. .SS "Reusing structures" .IX Subsection "Reusing structures" Test::Deep is good for reusing test structures so you can do this .PP .Vb 6 \& my $name_re = re(\*(Aq^(Mr|Mrs|Miss) \ew+ \ew+$\*(Aq); \& my $person_cmp = { \& Name => $name_re, \& Phone => re(\*(Aq^0d{6}$\*(Aq), \& ChildNames => array_each($name_re) \& }; \& \& cmp_deeply($person1, $person_cmp, "person ok"); \& cmp_deeply($person2, $person_cmp, "person ok"); \& cmp_deeply($person3, $person_cmp, "person ok"); .Ve .PP You can even put \f(CW$person_cmp\fR in a module and let other people use it when they are writing test scripts for modules that use your modules. .PP To make things a little more difficult, lets change the person data structure so that instead of a list of ChildNames, it contains a list of hashes, one for each child. So in fact our person structure will contain other person structures which may contain other person structures and so on. This is easy to handle with Test::Deep because Test::Deep structures can include themselves. Simply do .PP .Vb 6 \& my $name_re = re(\*(Aq^(Mr|Mrs|Miss) \ew+ \ew+$\*(Aq); \& my $person_cmp = { \& Name => $name_re, \& Phone => re(\*(Aq^0d{6}$\*(Aq), \& # note no mention of Children here \& }; \& \& $person_cmp\->{Children} = array_each($person_cmp); \& \& cmp_deeply($person, $person_cmp, "person ok"); .Ve .PP This will now check that \f(CW$person\fR\->{Children} is an array and that every element of that array also matches \f(CW$person_cmp\fR, this includes checking that its children also match the same pattern and so on. .SS "Circular data structures" .IX Subsection "Circular data structures" A circular data structure is one which loops back on itself, you can make one easily by doing .PP .Vb 3 \& my @b; \& my @a = (1, 2, 3, \e@b); \& push(@b, \e@a); .Ve .PP now \f(CW@a\fR contains a reference to be \f(CW@b\fR and \f(CW@b\fR contains a reference to \&\f(CW@a\fR. This causes problems if you have a program that wants to look inside \&\f(CW@a\fR and keep looking deeper and deeper at every level, it could get caught in an infinite loop looking into \f(CW@a\fR then \f(CW@b\fR then \f(CW@a\fR then \f(CW@b\fR and so on. .PP Test::Deep avoids this problem so we can extend our example further by saying that a person should also list their parents. .PP .Vb 6 \& my $name_re = re(\*(Aq^(Mr|Mrs|Miss) \ew+ \ew+$\*(Aq); \& my $person_cmp = { \& Name => $name_re, \& Phone => re(\*(Aq^0d{6}$\*(Aq), \& # note no mention of Children here \& }; \& \& $person_cmp\->{Children} = each_array($person_cmp); \& $person_cmp\->{Parents} = each_array($person_cmp); \& \& cmp_deeply($person, $person_cmp, "person ok"); .Ve .PP So this will check that for each child \f(CW$child\fR in \f(CW\*(C`$person\->{Children}\*(C'\fR that the \f(CW\*(C`$child\->{Parents}\*(C'\fR matches \f(CW$person_cmp\fR however it is smart enough not to get caught in an infinite loop where it keeps bouncing between the same Parent and Child. .SH "TERMINOLOGY" .IX Header "TERMINOLOGY" \&\f(CW\*(C`cmp_deeply($got, $expected, $name)\*(C'\fR takes 3 arguments. \f(CW$got\fR is the structure that you are checking, you must not include any special comparisons in this structure or you will get a fatal error. \f(CW$expected\fR describes what Test::Deep will be looking for in \f(CW$got\fR. You can put special comparisons in \f(CW$expected\fR if you want to. .PP As Test::Deep descends through the 2 structures, it compares them one piece at a time, so at any point in the process, Test::Deep is thinking about 2 things \- the current value from \f(CW$got\fR and the current value from \&\f(CW$expected\fR. In the documentation, I call them \f(CW$got_v\fR and \f(CW\*(C`exp_v\*(C'\fR respectively. .SH "COMPARISON FUNCTIONS" .IX Header "COMPARISON FUNCTIONS" \fIcmp_deeply\fR .IX Subsection "cmp_deeply" .PP .Vb 1 \& my $ok = cmp_deeply($got, $expected, $name) .Ve .PP \&\f(CW$got\fR is the result to be checked. \f(CW$expected\fR is the structure against which \f(CW$got\fR will be check. \f(CW$name\fR is the test name. .PP This is the main comparison function, the others are just wrappers around this. \f(CW$got\fR and \f(CW$expected\fR are compared recursively. Each value in \&\f(CW$expected\fR defines what's expected at the corresponding location in \f(CW$got\fR. Simple scalars are compared with \f(CW\*(C`eq\*(C'\fR. References to structures like hashes and arrays are compared recursively. .PP Items in \f(CW$expected\fR, though, can also represent complex tests that check for numbers in a given range, hashes with at least a certain set of keys, a string matching a regex, or many other things. .PP See \*(L"\s-1WHAT ARE SPECIAL COMPARISONS\*(R"\s0 for details. .PP \fIcmp_bag\fR .IX Subsection "cmp_bag" .PP .Vb 1 \& my $ok = cmp_bag(\e@got, \e@bag, $name) .Ve .PP Is shorthand for cmp_deeply(\e@got, bag(@bag), \f(CW$name\fR) .PP \&\fIn.b.\fR: Both arguments must be array refs. If they aren't an exception will be thrown. .PP \fIcmp_set\fR .IX Subsection "cmp_set" .PP .Vb 1 \& my $ok = cmp_set(\e@got, \e@set, $name) .Ve .PP Is shorthand for cmp_deeply(\e@got, set(@set), \f(CW$name\fR) .PP \fIcmp_methods\fR .IX Subsection "cmp_methods" .PP .Vb 1 \& my $ok = cmp_methods(\e@got, \e@methods, $name) .Ve .PP Is shorthand for cmp_deeply(\e@got, methods(@methods), \f(CW$name\fR) .PP \fIeq_deeply\fR .IX Subsection "eq_deeply" .PP .Vb 1 \& my $ok = eq_deeply($got, $expected) .Ve .PP This is the same as \fBcmp_deeply()\fR except it just returns true or false. It does not create diagnostics or talk to Test::Builder, but if you want to use it in a non-testing environment then you should import it through Test::Deep::NoTest. For example .PP .Vb 2 \& use Test::Deep::NoTest; \& print "a equals b" unless eq_deeply($a, $b); .Ve .PP otherwise the Test::Builder framework will be loaded and testing messages will be output when your program ends. .PP \fIcmp_details\fR .IX Subsection "cmp_details" .PP .Vb 1 \& ($ok, $stack) = cmp_details($got, $expected) .Ve .PP This behaves much like eq_deeply, but it additionally allows you to produce diagnostics in case of failure by passing the value in \f(CW$stack\fR to \f(CW\*(C`deep_diag\*(C'\fR. .PP Do not make assumptions about the structure or content of \f(CW$stack\fR and do not use it if \f(CW$ok\fR contains a true value. .PP See \*(L"\s-1USING TEST::DEEP WITH TEST::BUILDER\*(R"\s0 for example uses. .SH "SPECIAL COMPARISONS PROVIDED" .IX Header "SPECIAL COMPARISONS PROVIDED" In the documentation below, \f(CW$got_v\fR is used to indicate any given value within the \f(CW$got\fR structure. .PP \fIignore\fR .IX Subsection "ignore" .PP .Vb 1 \& cmp_deeply( $got, ignore() ); .Ve .PP This makes Test::Deep skip tests on \f(CW$got_v\fR. No matter what value \f(CW$got_v\fR has, Test::Deep will think it's correct. This is useful if some part of the structure you are testing is very complicated and already tested elsewhere, or if it is unpredictable. .PP .Vb 8 \& cmp_deeply( \& $got, \& { \& name => \*(AqJohn\*(Aq, \& random => ignore(), \& address => [ \*(Aq5 A street\*(Aq, \*(Aqa town\*(Aq, \*(Aqa country\*(Aq ], \& } \& ); .Ve .PP is the equivalent of checking .PP .Vb 3 \& $got\->{name} eq \*(AqJohn\*(Aq; \& exists $got\->{random}; \& cmp_deeply($got\->{address}, [\*(Aq5 A street\*(Aq, \*(Aqa town\*(Aq, \*(Aqa country\*(Aq]); .Ve .PP \fImethods\fR .IX Subsection "methods" .PP .Vb 1 \& cmp_deeply( $got, methods(%hash) ); .Ve .PP \&\f(CW%hash\fR is a hash of method call => expected value pairs. .PP This lets you call methods on an object and check the result of each call. The methods will be called in the order supplied. If you want to pass arguments to the method you should wrap the method name and arguments in an array reference. .PP .Vb 4 \& cmp_deeply( \& $obj, \& methods(name => "John", ["favourite", "food"] => "taco") \& ); .Ve .PP is roughly the equivalent of checking that .PP .Vb 2 \& $obj\->name eq "John" \& $obj\->favourite("food") eq "taco" .Ve .PP The methods will be called in the order you supply them and will be called in scalar context. If you need to test methods called in list context then you should use \f(CW\*(C`listmethods()\*(C'\fR. .PP \&\fB\s-1NOTE\s0\fR Just as in a normal test script, you need to be careful if the methods you call have side effects like changing the object or other objects in the structure. Although the order of the methods is fixed, the order of some other tests is not so if \f(CW$expected\fR is .PP .Vb 4 \& { \& manager => methods(@manager_methods), \& coder => methods(@coder_methods) \& } .Ve .PP there is no way to know which if manager and coder will be tested first. If the methods you are testing depend on and alter global variables or if manager and coder are the same object then you may run into problems. .PP \fIlistmethods\fR .IX Subsection "listmethods" .PP .Vb 1 \& cmp_deeply( $got, listmethods(%hash) ); .Ve .PP \&\f(CW%hash\fR is a hash of pairs mapping method names to expected return values. .PP This is almost identical to \fBmethods()\fR except the methods are called in list context instead of scalar context. This means that the expected return values supplied must be in array references. .PP .Vb 7 \& cmp_deeply( \& $obj, \& listmethods( \& name => [ "John" ], \& ["favourites", "food"] => ["Mapo tofu", "Gongbao chicken"] \& ) \& ); .Ve .PP is the equivalent of checking that .PP .Vb 2 \& cmp_deeply([$obj\->name], ["John"]); \& cmp_deeply([$obj\->favourites("food")], ["Mapo tofu", "Gongbao chicken"]); .Ve .PP The methods will be called in the order you supply them. .PP \&\fB\s-1NOTE\s0\fR The same caveats apply as for \fBmethods()\fR. .PP \fIshallow\fR .IX Subsection "shallow" .PP .Vb 1 \& cmp_deeply( $got, shallow($thing) ); .Ve .PP \&\f(CW$thing\fR is a ref. .PP This prevents Test::Deep from looking inside \f(CW$thing\fR. It allows you to check that \f(CW$got_v\fR and \f(CW$thing\fR are references to the same variable. So .PP .Vb 2 \& my @a = @b = (1, 2, 3); \& cmp_deeply(\e@a, \e@b); .Ve .PP will pass because \f(CW@a\fR and \f(CW@b\fR have the same elements however .PP .Vb 1 \& cmp_deeply(\e@a, shallow(\e@b)) .Ve .PP will fail because although \f(CW\*(C`\e@a\*(C'\fR and \f(CW\*(C`\e@b\*(C'\fR both contain \f(CW\*(C`1, 2, 3\*(C'\fR they are references to different arrays. .PP \fInoclass\fR .IX Subsection "noclass" .PP .Vb 1 \& cmp_deeply( $got, noclass($thing) ); .Ve .PP \&\f(CW$thing\fR is a structure to be compared against. .PP This makes Test::Deep ignore the class of objects, so it just looks at the data they contain. Class checking will be turned off until Test::Deep is finished comparing \f(CW$got_v\fR against \f(CW$thing\fR. Once Test::Deep comes out of \&\f(CW$thing\fR it will go back to its previous setting for checking class. .PP This can be useful when you want to check that objects have been constructed correctly but you don't want to write lots of \&\f(CW\*(C`bless\*(C'\fRes. If \f(CW@people\fR is an array of Person objects then .PP .Vb 4 \& cmp_deeply(\e@people, [ \& bless {name => \*(AqJohn\*(Aq, phone => \*(Aq555\-5555\*(Aq}, "Person", \& bless {name => \*(AqAnne\*(Aq, phone => \*(Aq444\-4444\*(Aq}, "Person", \& ]); .Ve .PP can be replaced with .PP .Vb 4 \& cmp_deeply(\e@people, noclass([ \& {name => \*(AqJohn\*(Aq, phone => \*(Aq555\-5555\*(Aq}, \& {name => \*(AqAnne\*(Aq, phone => \*(Aq444\-4444\*(Aq} \& ])); .Ve .PP However, this is testing so you should also check that the objects are blessed correctly. You could use a map to bless all those hashes or you could do a second test like .PP .Vb 1 \& cmp_deeply(\e@people, array_each(isa("Person")); .Ve .PP \fIuseclass\fR .IX Subsection "useclass" .PP .Vb 1 \& cmp_deeply( $got, useclass($thing) ); .Ve .PP This turns back on the class comparison while inside a \f(CW\*(C`noclass()\*(C'\fR. .PP .Vb 8 \& cmp_deeply( \& $got, \& noclass( \& [ \& useclass( $object ) \& ] \& ) \& ) .Ve .PP In this example the class of the array reference in \f(CW$got\fR is ignored but the class of \f(CW$object\fR is checked, as is the class of everything inside \&\f(CW$object\fR. .PP \fIre\fR .IX Subsection "re" .PP .Vb 1 \& cmp_deeply( $got, re($regexp, $capture_data, $flags) ); .Ve .PP \&\f(CW$regexp\fR is either a regular expression reference produced with \f(CW\*(C`qr/.../\*(C'\fR or a string which will be used to construct a regular expression. .PP \&\f(CW$capture_data\fR is optional and is used to check the strings captured by an regex. This should can be an array ref or a Test::Deep comparator that works on array refs. .PP \&\f(CW$flags\fR is an optional string which controls whether the regex runs as a global match. If \f(CW$flags\fR is \*(L"g\*(R" then the regex will run as \f(CW\*(C`m/$regexp/g\*(C'\fR. .PP Without \f(CW$capture_data\fR, this simply compares \f(CW$got_v\fR with the regular expression provided. So .PP .Vb 1 \& cmp_deeply($got, [ re("ferg") ]) .Ve .PP is the equivalent of .PP .Vb 1 \& $got\->[0] =~ /ferg/ .Ve .PP With \f(CW$capture_data\fR, .PP .Vb 1 \& cmp_deeply($got, [re($regex, $capture_data)]) .Ve .PP is the equivalent of .PP .Vb 2 \& my @data = $got\->[0] =~ /$regex/; \& cmp_deeply(\e@data, $capture_data); .Ve .PP So you can do something simple like .PP .Vb 1 \& cmp_deeply($got, re(qr/(\ed\ed)(\ew\ew)/, [25, "ab" ])) .Ve .PP to check that \f(CW\*(C`(\ed\ed)\*(C'\fR was 25 and \f(CW\*(C`(\ew\ew)\*(C'\fR was \*(L"ab\*(R" but you can also use Test::Deep objects to do more complex testing of the captured values .PP .Vb 8 \& cmp_deeply( \& "cat=2,dog=67,sheep=3,goat=2,dog=5", \& re( \& qr/(\eD+)=\ed+,?/, \& set(qw( cat sheep dog )), \& "g" \& ), \& ); .Ve .PP here, the regex will match the string and will capture the animal names and check that they match the specified set, in this case it will fail, complaining that \*(L"goat\*(R" is not in the set. .PP \fIall\fR .IX Subsection "all" .PP .Vb 1 \& cmp_deeply( $got, all(@expecteds) ); .Ve .PP \&\f(CW@expecteds\fR is an array of expected structures. .PP This allows you to compare data against multiple expected results and make sure each of them matches. .PP .Vb 1 \& cmp_deeply($got, all(isa("Person"), methods(name => \*(AqJohn\*(Aq))) .Ve .PP is equivalent to .PP .Vb 2 \& $got\->isa("Person") \& $got\->name eq \*(AqJohn\*(Aq .Ve .PP If either test fails then the whole thing is considered a fail. This is a short-circuit test, the testing is stopped after the first failure, although in the future it may complete all tests so that diagnostics can be output for all failures. When reporting failure, the parts are counted from 1. .PP Thanks to the magic of overloading, you can write .PP .Vb 1 \& any( re("^wi"), all(isa("Person"), methods(name => \*(AqJohn\*(Aq)) ) .Ve .PP as .PP .Vb 1 \& re("^wi") | isa("Person") & methods(name => \*(AqJohn\*(Aq) .Ve .PP Note \fBsingle\fR \f(CW\*(C`|\*(C'\fR not double, as \f(CW\*(C`||\*(C'\fR cannot be overloaded. This will only work when there is a special comparison involved. If you write .PP .Vb 1 \& "john" | "anne" | "robert" .Ve .PP Perl will turn this into .PP .Vb 1 \& "{onort" .Ve .PP which is presumably not what you wanted. This is because perl ors them together as strings before Test::Deep gets a chance to do any overload tricks. .PP \fIany\fR .IX Subsection "any" .PP .Vb 1 \& cmp_deeply( $got, any(@expecteds) ); .Ve .PP \&\f(CW@expecteds\fR is an array of expected structures. .PP This can be used to compare data against multiple expected results and make sure that at least one of them matches. This is a short-circuit test so if a test passes then none of the tests after that will be attempted. .PP You can also use overloading with \f(CW\*(C`|\*(C'\fR similarly to \fBall()\fR. .PP \fIIsa\fR .IX Subsection "Isa" .PP .Vb 1 \& cmp_deeply( $got, Isa($class) ); .Ve .PP \fIisa\fR .IX Subsection "isa" .PP .Vb 1 \& cmp_deeply( $got, isa($class) ); .Ve .PP \&\f(CW$class\fR is a class name. .PP This uses \f(CW\*(C`UNIVERSAL::isa()\*(C'\fR to check that \f(CW$got_v\fR is blessed into the class \f(CW$class\fR. .PP \&\fB\s-1NOTE:\s0\fR \f(CW\*(C`Isa()\*(C'\fR does exactly as documented here, but \f(CW\*(C`isa()\*(C'\fR is slightly different. If \f(CW\*(C`isa()\*(C'\fR is called with 1 argument it falls through to \&\f(CW\*(C`Isa()\*(C'\fR. If \f(CW\*(C`isa()\*(C'\fR called with 2 arguments, it falls through to \&\f(CW\*(C`UNIVERSAL::isa\*(C'\fR. This is to prevent breakage when you import \f(CW\*(C`isa()\*(C'\fR into a package that is used as a class. Without this, anyone calling \&\f(CW\*(C`Class\->isa($other_class)\*(C'\fR would get the wrong answer. This is a hack to patch over the fact that \f(CW\*(C`isa\*(C'\fR is exported by default. .PP \fIobj_isa\fR .IX Subsection "obj_isa" .PP .Vb 1 \& cmp_deeply( $got, obj_isa($class) ); .Ve .PP This test accepts only objects that are instances of \f(CW$class\fR or a subclass. Unlike the \f(CW\*(C`Isa\*(C'\fR test, this test will never accept class names. .PP \fIarray_each\fR .IX Subsection "array_each" .PP .Vb 1 \& cmp_deeply( \e@got, array_each($thing) ); .Ve .PP \&\f(CW$thing\fR is a structure to be compared against. .PP <$got_v> must be an array reference. Each element of it will be compared to \&\f(CW$thing\fR. This is useful when you have an array of similar things, for example objects of a known type and you don't want to have to repeat the same test for each one. .PP .Vb 7 \& my $common_tests = all( \& isa("MyFile"), \& methods( \& handle => isa("IO::Handle") \& filename => re("^/home/ted/tmp"), \& ) \& ); \& \& cmp_deeply($got, array_each($common_tests)); .Ve .PP is similar to .PP .Vb 3 \& foreach my $got_v (@$got) { \& cmp_deeply($got_v, $common_tests) \& } .Ve .PP Except it will not explode if \f(CW$got\fR is not an array reference. It will check that each of the objects in \f(CW@$got\fR is a MyFile and that each one gives the correct results for its methods. .PP You could go further, if for example there were 3 files and you knew the size of each one you could do this .PP .Vb 12 \& cmp_deeply( \& $got, \& all( \& array_each($common_tests), \& [ \& methods(size => 1000), \& methods(size => 200), \& methods(size => 20) \& ] \& ) \& ) \& cmp_deeply($got, array_each($structure)); .Ve .PP \fIhash_each\fR .IX Subsection "hash_each" .PP .Vb 1 \& cmp_deeply( \e%got, hash_each($thing) ); .Ve .PP This test behaves like \f(CW\*(C`array_each\*(C'\fR (see above) but tests that each hash value passes its tests. .PP \fIstr\fR .IX Subsection "str" .PP .Vb 1 \& cmp_deeply( $got, str($string) ); .Ve .PP \&\f(CW$string\fR is a string. .PP This will stringify \f(CW$got_v\fR and compare it to \f(CW$string\fR using \f(CW\*(C`eq\*(C'\fR, even if \f(CW$got_v\fR is a ref. It is useful for checking the stringified value of an overloaded reference. .PP \fInum\fR .IX Subsection "num" .PP .Vb 1 \& cmp_deeply( $got, num($number, $tolerance) ); .Ve .PP \&\f(CW$number\fR is a number. .PP \&\f(CW$tolerance\fR is an optional number. .PP This will add 0 to \f(CW$got_v\fR and check if it's numerically equal to \&\f(CW$number\fR, even if \f(CW$got_v\fR is a ref. It is useful for checking the numerical value of an overloaded reference. If \f(CW$tolerance\fR is supplied then this will check that \f(CW$got_v\fR and \f(CW$exp_v\fR are less than \&\f(CW$tolerance\fR apart. This is useful when comparing floating point numbers as rounding errors can make it hard or impossible for \f(CW$got_v\fR to be exactly equal to \f(CW$exp_v\fR. When \f(CW$tolerance\fR is supplied, the test passes if \&\f(CW\*(C`abs($got_v \- $exp_v) <= $tolerance\*(C'\fR. .PP \&\fBNote\fR in Perl, \f(CW\*(C`"12blah" == 12\*(C'\fR because Perl will be smart and convert \&\*(L"12blah\*(R" into 12. You may not want this. There was a strict mode but that is now gone. A \*(L"looks like a number\*(R" test will replace it soon. Until then you can usually just use the \fBstring()\fR comparison to be more strict. This will work fine for almost all situations, however it will not work when <$got_v> is an overloaded value who's string and numerical values differ. .PP \fIbool, true, false\fR .IX Subsection "bool, true, false" .PP .Vb 3 \& cmp_deeply( $got, bool($value) ); \& cmp_deeply( $got, true ); \& cmp_deeply( $got, false ); .Ve .PP \&\f(CW$value\fR is anything you like but it's probably best to use 0 or 1 .PP This will check that \f(CW$got_v\fR and \f(CW$value\fR have the same truth value, that is they will give the same result when used in boolean context, like in an \&\f(CW\*(C`if()\*(C'\fR statement. .PP \&\fBNote:\fR \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR are only imported by special request. .PP \fIcode\fR .IX Subsection "code" .PP .Vb 1 \& cmp_deeply( $got, code(\e&subref) ); .Ve .PP \&\f(CW\*(C`\e&subref\*(C'\fR is a reference to a subroutine which will be passed a single argument, it then should return a true or false and possibly a string .PP This will pass \f(CW$got_v\fR to the subroutine which returns true or false to indicate a pass or fail. Fails can be accompanied by a diagnostic string which gives an explanation of why it's a fail. .PP .Vb 12 \& sub check_name \& { \& my $name = shift; \& if ($boss\->likes($name)) \& { \& return 1; \& } \& else \& { \& return (0, "the boss doesn\*(Aqt like your name"); \& } \& } \& \& cmp_deeply("Brian", code(\e&check_name)); .Ve .SS "\s-1SET COMPARISONS\s0" .IX Subsection "SET COMPARISONS" Set comparisons give special semantics to array comparisons: .IP "\(bu" 4 The order of items in a set is irrelevant .IP "\(bu" 4 The presence of duplicate items in a set is ignored. .PP As such, in any set comparison, the following arrays are equal: .PP .Vb 5 \& [ 1, 2 ] \& [ 1, 1, 2 ] \& [ 1, 2, 1 ] \& [ 2, 1, 1 ] \& [ 1, 1, 2 ] .Ve .PP All are interpreted by \f(CW\*(C`set\*(C'\fR semantics as if the set was only specified as: .PP .Vb 1 \& [ 1, 2 ] .Ve .PP All \f(CW\*(C`set\*(C'\fR functions return an object which can have additional items added to it: .PP .Vb 2 \& my $set = set( 1, 2 ); \& $set\->add(1, 3, 1 ); # Set is now ( 1, 2, 3 ) .Ve .PP Special care must be taken when using special comparisons within sets. See \&\*(L"\s-1SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS\*(R"\s0 for details. .PP \fIset\fR .IX Subsection "set" .PP .Vb 1 \& cmp_deeply( \e@got, set(@elements) ); .Ve .PP This does a set comparison, that is, it compares two arrays but ignores the order of the elements and it ignores duplicate elements, but ensures that all items in \f(CW@elements\fR will be in \f(CW$got\fR and all items in \f(CW$got\fR will be in \f(CW@elements\fR. .PP So the following tests will be passes, and will be equivalent: .PP .Vb 2 \& cmp_deeply([1, 2, 2, 3], set(3, 2, 1, 1)); \& cmp_deeply([1, 2, 3], set(3, 2, 1)); .Ve .PP \fIsupersetof\fR .IX Subsection "supersetof" .PP .Vb 1 \& cmp_deeply( \e@got, supersetof(@elements) ); .Ve .PP This function works much like \f(CW\*(C`set\*(C'\fR, and performs a set comparison of \f(CW$got_v\fR with the elements of \f(CW@elements\fR. .PP \&\f(CW\*(C`supersetof\*(C'\fR is however slightly relaxed, such that \f(CW$got\fR may contain things not in \f(CW@elements\fR, but must at least contain all \f(CW@elements\fR. .PP These two statements are equivalent, and will be passes: .PP .Vb 2 \& cmp_deeply([1,2,3,3,4,5], supersetof(2,2,3)); \& cmp_deeply([1,2,3,4,5], supersetof(2,3)); .Ve .PP But these will be failures: .PP .Vb 2 \& cmp_deeply([1,2,3,4,5], supersetof(2,3,6)); # 6 not in superset \& cmp_deeply([1], supersetof(1,2)); # 2 not in superset .Ve .PP \fIsubsetof\fR .IX Subsection "subsetof" .PP .Vb 1 \& cmp_deeply( \e@got, subsetof(@elements) ); .Ve .PP This function works much like \f(CW\*(C`set\*(C'\fR, and performs a set comparison of \f(CW$got_v\fR with the elements of \f(CW@elements\fR. .PP This is the inverse of \f(CW\*(C`supersetof\*(C'\fR, which expects all unique elements found in \f(CW$got_v\fR must be in \f(CW@elements\fR. .PP .Vb 3 \& cmp_deeply([1,2,4,5], subsetof(2,3,3) ) # Fail: 1,4 & 5 extra \& cmp_deeply([2,3,3], subsetof(1,2,4,5) ) # Fail: 3 extra \& cmp_deeply([2,3,3], subsetof(1,2,4,5,3)) # Pass .Ve .PP \fInone\fR .IX Subsection "none" .PP .Vb 1 \& cmp_deeply( $got, none(@elements) ); .Ve .PP \&\f(CW@elements\fR is an array of elements, wherein no elements in \f(CW@elements\fR may be equal to \f(CW$got_v\fR. .PP \fInoneof\fR .IX Subsection "noneof" .PP .Vb 1 \& cmp_deeply( \e@got, noneof(@elements) ); .Ve .PP \&\f(CW@elements\fR is an array of elements, wherein no elements in \f(CW@elements\fR may be found in \f(CW$got_v\fR. .PP For example: .PP .Vb 3 \& # Got has no 1, no 2, and no 3 \& cmp_deeply( [1], noneof( 1, 2, 3 ) ); # fail \& cmp_deeply( [5], noneof( 1, 2, 3 ) ); # pass .Ve .SS "\s-1BAG COMPARISONS\s0" .IX Subsection "BAG COMPARISONS" Bag comparisons give special semantics to array comparisons, that are similar to set comparisons, but slightly different. .IP "\(bu" 4 The order of items in a bag is irrelevant .IP "\(bu" 4 The presence of duplicate items in a bag is \fB\s-1PRESERVED\s0\fR .PP As such, in any bag comparison, the following arrays are equal: .PP .Vb 4 \& [ 1, 1, 2 ] \& [ 1, 2, 1 ] \& [ 2, 1, 1 ] \& [ 1, 1, 2 ] .Ve .PP However, they are \fB\s-1NOT\s0\fR equal to any of the following: .PP .Vb 3 \& [ 1, 2 ] \& [ 1, 2, 2 ] \& [ 1, 1, 1, 2 ] .Ve .PP All \f(CW\*(C`bag\*(C'\fR functions return an object which can have additional items added to it: .PP .Vb 2 \& my $bag = bag( 1, 2 ); \& $bag\->add(1, 3, 1 ); # Bag is now ( 1, 1, 1, 2, 3 ) .Ve .PP Special care must be taken when using special comparisons within bags. See \&\*(L"\s-1SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS\*(R"\s0 for details. .PP \fIbag\fR .IX Subsection "bag" .PP .Vb 1 \& cmp_deeply( \e@got, bag(@elements) ); .Ve .PP This does an order-insensitive bag comparison between \f(CW$got\fR and \&\f(CW@elements\fR, ensuring that: .ie n .IP "each item in @elements is found in $got" 4 .el .IP "each item in \f(CW@elements\fR is found in \f(CW$got\fR" 4 .IX Item "each item in @elements is found in $got" .PD 0 .ie n .IP "the number of times a $expected_v is found in @elements is reflected in $got" 4 .el .IP "the number of times a \f(CW$expected_v\fR is found in \f(CW@elements\fR is reflected in \f(CW$got\fR" 4 .IX Item "the number of times a $expected_v is found in @elements is reflected in $got" .ie n .IP "no items are found in $got other than those in @elements." 4 .el .IP "no items are found in \f(CW$got\fR other than those in \f(CW@elements\fR." 4 .IX Item "no items are found in $got other than those in @elements." .PD .PP As such, the following are passes, and are equivalent to each other: .PP .Vb 3 \& cmp_deeply([1, 2, 2], bag(2, 2, 1)) \& cmp_deeply([2, 1, 2], bag(2, 2, 1)) \& cmp_deeply([2, 2, 1], bag(2, 2, 1)) .Ve .PP But the following are failures: .PP .Vb 2 \& cmp_deeply([1, 2, 2], bag(2, 2, 1, 1)) # Not enough 1\*(Aqs in Got \& cmp_deeply([1, 2, 2, 1], bag(2, 2, 1) ) # Too many 1\*(Aqs in Got .Ve .PP \fIsuperbagof\fR .IX Subsection "superbagof" .PP .Vb 1 \& cmp_deeply( \e@got, superbagof( @elements ) ); .Ve .PP This function works much like \f(CW\*(C`bag\*(C'\fR, and performs a bag comparison of \f(CW$got_v\fR with the elements of \f(CW@elements\fR. .PP \&\f(CW\*(C`superbagof\*(C'\fR is however slightly relaxed, such that \f(CW$got\fR may contain things not in \f(CW@elements\fR, but must at least contain all \f(CW@elements\fR. .PP So: .PP .Vb 2 \& # pass \& cmp_deeply( [1, 1, 2], superbagof( 1 ) ); \& \& # fail: not enough 1\*(Aqs in superbag \& cmp_deeply( [1, 1, 2], superbagof( 1, 1, 1 )); .Ve .PP \fIsubbagof\fR .IX Subsection "subbagof" .PP .Vb 1 \& cmp_deeply( \e@got, subbagof(@elements) ); .Ve .PP This function works much like \f(CW\*(C`bag\*(C'\fR, and performs a bag comparison of \f(CW$got_v\fR with the elements of \f(CW@elements\fR. .PP This is the inverse of \f(CW\*(C`superbagof\*(C'\fR, and expects all elements in \f(CW$got\fR to be in \f(CW@elements\fR, while allowing items to exist in \f(CW@elements\fR that are not in \f(CW$got\fR .PP .Vb 2 \& # pass \& cmp_deeply( [1], subbagof( 1, 1, 2 ) ); \& \& # fail: too many 1\*(Aqs in subbag \& cmp_deeply( [1, 1, 1], subbagof( 1, 1, 2 ) ); .Ve .SS "\s-1HASH COMPARISONS\s0" .IX Subsection "HASH COMPARISONS" Typically, if you're doing simple hash comparisons, .PP .Vb 1 \& cmp_deeply( \e%got, \e%expected ) .Ve .PP is sufficient. \f(CW\*(C`cmp_deeply\*(C'\fR will ensure \f(CW%got\fR and \f(CW%hash\fR have identical keys, and each key from either has the same corresponding value. .PP \fIsuperhashof\fR .IX Subsection "superhashof" .PP .Vb 1 \& cmp_deeply( \e%got, superhashof(\e%hash) ); .Ve .PP This will check that the hash \f(CW%$got\fR is a \*(L"super-hash\*(R" of \f(CW%hash\fR. That is that all the key and value pairs in \f(CW%hash\fR appear in \f(CW%$got\fR but \&\f(CW%$got\fR can have extra ones also. .PP For example .PP .Vb 1 \& cmp_deeply({a => 1, b => 2}, superhashof({a => 1})) .Ve .PP will pass but .PP .Vb 1 \& cmp_deeply({a => 1, b => 2}, superhashof({a => 1, c => 3})) .Ve .PP will fail. .PP \fIsubhashof\fR .IX Subsection "subhashof" .PP .Vb 1 \& cmp_deeply( \e%got, subhashof(\e%hash) ); .Ve .PP This will check that the hash \f(CW%$got\fR is a \*(L"sub-hash\*(R" of \f(CW%hash\fR. That is that all the key and value pairs in \f(CW%$got\fR also appear in \f(CW%hash\fR. .PP For example .PP .Vb 1 \& cmp_deeply({a => 1}, subhashof({a => 1, b => 2})) .Ve .PP will pass but .PP .Vb 1 \& cmp_deeply({a => 1, c => 3}, subhashof({a => 1, b => 2})) .Ve .PP will fail. .SH "DIAGNOSTIC FUNCTIONS" .IX Header "DIAGNOSTIC FUNCTIONS" \fIdeep_diag\fR .IX Subsection "deep_diag" .PP .Vb 1 \& my $reason = deep_diag($stack); .Ve .PP \&\f(CW$stack\fR is a value returned by cmp_details. Do not call this function if cmp_details returned a true value for \f(CW$ok\fR. .PP \&\f(CW\*(C`deep_diag()\*(C'\fR returns a human readable string describing how the comparison failed. .SH "ANOTHER EXAMPLE" .IX Header "ANOTHER EXAMPLE" You've written a module to handle people and their film interests. Say you have a function that returns an array of people from a query, each person is a hash with 2 keys: Name and Age and the array is sorted by Name. You can do .PP .Vb 8 \& cmp_deeply( \& $result, \& [ \& {Name => \*(AqAnne\*(Aq, Age => 26}, \& {Name => "Bill", Age => 47} \& {Name => \*(AqJohn\*(Aq, Age => 25}, \& ] \& ); .Ve .PP Soon after, your query function changes and all the results now have an \s-1ID\s0 field. Now your test is failing again because you left out \s-1ID\s0 from each of the hashes. The problem is that the IDs are generated by the database and you have no way of knowing what each person's \s-1ID\s0 is. With Test::Deep you can change your query to .PP .Vb 8 \& cmp_deeply( \& $result, \& [ \& {Name => \*(AqJohn\*(Aq, Age => 25, ID => ignore()}, \& {Name => \*(AqAnne\*(Aq, Age => 26, ID => ignore()}, \& {Name => "Bill", Age => 47, ID => ignore()} \& ] \& ); .Ve .PP But your test still fails. Now, because you're using a database, you no longer know what order the people will appear in. You could add a sort into the database query but that could slow down your application. Instead you can get Test::Deep to ignore the order of the array by doing a bag comparison instead. .PP .Vb 8 \& cmp_deeply( \& $result, \& bag( \& {Name => \*(AqJohn\*(Aq, Age => 25, ID => ignore()}, \& {Name => \*(AqAnne\*(Aq, Age => 26, ID => ignore()}, \& {Name => "Bill", Age => 47, ID => ignore()} \& ) \& ); .Ve .PP Finally person gets even more complicated and includes a new field called Movies, this is a list of movies that the person has seen recently, again these movies could also come back in any order so we need a bag inside our other bag comparison, giving us something like .PP .Vb 8 \& cmp_deeply( \& $result, \& bag( \& {Name => \*(AqJohn\*(Aq, Age => 25, ID => ignore(), Movies => bag(...)}, \& {Name => \*(AqAnne\*(Aq, Age => 26, ID => ignore(), Movies => bag(...)}, \& {Name => "Bill", Age => 47, ID => ignore(), Movies => bag(...)} \& ) \& ); .Ve .SH "USING TEST::DEEP WITH TEST::BUILDER" .IX Header "USING TEST::DEEP WITH TEST::BUILDER" Combining \f(CW\*(C`cmp_details\*(C'\fR and \f(CW\*(C`deep_diag\*(C'\fR makes it possible to use Test::Deep in your own test classes. .PP In a Test::Builder subclass, create a test method in the following form: .PP .Vb 4 \& sub behaves_ok { \& my $self = shift; \& my $expected = shift; \& my $test_name = shift; \& \& my $got = do_the_important_work_here(); \& \& my ($ok, $stack) = cmp_details($got, $expected); \& unless ($Test\->ok($ok, $test_name)) { \& my $diag = deep_diag($stack); \& $Test\->diag($diag); \& } \& } .Ve .PP As the subclass defines a test class, not tests themselves, make sure it uses Test::Deep::NoTest, not \f(CW\*(C`Test::Deep\*(C'\fR itself. .SH "LIMITATIONS" .IX Header "LIMITATIONS" Currently any \s-1CODE, GLOB\s0 or \s-1IO\s0 refs will be compared using \fBshallow()\fR, which means only their memory addresses are compared. .SH "BUGS" .IX Header "BUGS" There is a bug in set and bag compare to do with competing SCs. It only occurs when you put certain special comparisons inside bag or set comparisons you don't need to worry about it. The full details are in the \&\f(CW\*(C`bag()\*(C'\fR docs. It will be fixed in an upcoming version. .SH "CAVEATS" .IX Header "CAVEATS" .SS "\s-1SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS\s0" .IX Subsection "SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS" If you use certain special comparisons within a bag or set comparison there is a danger that a test will fail when it should have passed. It can only happen if two or more special comparisons in the bag are competing to match elements. Consider this comparison .PP .Vb 1 \& cmp_deeply([\*(Aqfurry\*(Aq, \*(Aqfurball\*(Aq], bag(re("^fur"), re("furb"))) .Ve .PP There are two things that could happen, hopefully \f(CW\*(C`re("^fur")\*(C'\fR is paired with \&\*(L"furry\*(R" and \f(CW\*(C`re("^furb")\*(C'\fR is paired with \*(L"furb\*(R" and everything is fine but it could happen that \f(CW\*(C`re("^fur")\*(C'\fR is paired with \*(L"furball\*(R" and then \f(CW\*(C`re("^furb")\*(C'\fR cannot find a match and so the test fails. Examples of other competing comparisons are \f(CW\*(C`bag(1, 2, 2)\*(C'\fR vs \f(CW\*(C`set(1, 2)\*(C'\fR and \&\f(CW\*(C`methods(m1 => "v1", m2 => "v2")\*(C'\fR vs \f(CW\*(C`methods(m1 => "v1")\*(C'\fR .PP This problem is could be solved by using a slower and more complicated algorithm for set and bag matching. Something for the future... .SH "WHAT ARE SPECIAL COMPARISONS?" .IX Header "WHAT ARE SPECIAL COMPARISONS?" A special comparison (\s-1SC\s0) is simply an object that inherits from Test::Deep::Cmp. Whenever \f(CW$expected_v\fR is an \s-1SC\s0 then instead of checking \&\f(CW\*(C`$got_v eq $expected_v\*(C'\fR, we pass control over to the \s-1SC\s0 and let it do its thing. .PP Test::Deep exports lots of \s-1SC\s0 constructors, to make it easy for you to use them in your test scripts. For example is \f(CW\*(C`re("hello")\*(C'\fR is just a handy way of creating a Test::Deep::Regexp object that will match any string containing \&\*(L"hello\*(R". So .PP .Vb 1 \& cmp_deeply([ \*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqhello world\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, re("^hello")]); .Ve .PP will check \f(CW\*(Aqa\*(Aq eq \*(Aqa\*(Aq\fR, \f(CW\*(Aqb\*(Aq eq \*(Aqb\*(Aq\fR but when it comes to comparing \&\f(CW\*(Aqhello world\*(Aq\fR and \f(CW\*(C`re("^hello")\*(C'\fR it will see that \&\f(CW$expected_v\fR is an \s-1SC\s0 and so will pass control to the Test::Deep::Regexp class by do something like \f(CW\*(C`$expected_v\->descend($got_v)\*(C'\fR. The \f(CW\*(C`descend()\*(C'\fR method should just return true or false. .PP This gives you enough to write your own SCs but I haven't documented how diagnostics works because it's about to get an overhaul (theoretically). .SH "EXPORTS" .IX Header "EXPORTS" By default, Test::Deep will export everything in its \f(CW\*(C`v0\*(C'\fR tag, as if you had written: .PP .Vb 1 \& use Test::Deep \*(Aq:v0\*(Aq; .Ve .PP Those things are: .PP .Vb 6 \& all any array array_each arrayelementsonly arraylength arraylengthonly bag \& blessed bool cmp_bag cmp_deeply cmp_methods cmp_set code eq_deeply hash \& hash_each hashkeys hashkeysonly ignore Isa isa listmethods methods noclass \& none noneof num obj_isa re reftype regexpmatches regexponly regexpref \& regexprefonly scalarrefonly scalref set shallow str subbagof subhashof \& subsetof superbagof superhashof supersetof useclass .Ve .PP A slightly better set of exports is the \f(CW\*(C`v1\*(C'\fR set. It's all the same things, with the exception of \f(CW\*(C`Isa\*(C'\fR and \f(CW\*(C`blessed\*(C'\fR. If you want to import \&\*(L"everything\*(R", you probably want to \f(CW\*(C`use Test::Deep \*(Aq:V1\*(Aq;\*(C'\fR. .PP There's another magic export group: \f(CW\*(C`:preload\*(C'\fR. If that is specified, all of the Test::Deep plugins will be loaded immediately instead of lazily. .SH "SEE ALSO" .IX Header "SEE ALSO" Test::More .SH "THANKS" .IX Header "THANKS" Thanks to Michael G Schwern for Test::More's is_deeply function which inspired this library. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Alexander Karelas <karjala@karjala.org> .IP "\(bu" 4 Belden Lyman <blyman@shutterstock.com> .IP "\(bu" 4 Daniel Böhmer <dboehmer@cpan.org> .IP "\(bu" 4 David Steinbrunner <dsteinbrunner@pobox.com> .IP "\(bu" 4 Denis Ibaev <dionys@gmail.com> .IP "\(bu" 4 Ed Adjei <edmund@cpan.org> .IP "\(bu" 4 Fabrice Gabolde <fabrice.gabolde@gmail.com> .IP "\(bu" 4 Felipe Gasper <felipe@felipegasper.com> .IP "\(bu" 4 Fergal Daly <fergal@esatclear.ie> .IP "\(bu" 4 George Hartzell <hartzell@alerce.com> .IP "\(bu" 4 Graham Knop <haarg@haarg.org> .IP "\(bu" 4 Ivan Bessarabov <ivan@bessarabov.ru> .IP "\(bu" 4 José Joaquín Atria <jjatria@cpan.org> .IP "\(bu" 4 Karen Etheridge <ether@cpan.org> .IP "\(bu" 4 Kent Fredric <kentfredric@gmail.com> .IP "\(bu" 4 Lance Wicks <lancew@cpan.org> .IP "\(bu" 4 Matthew Horsfall <wolfsage@gmail.com> .IP "\(bu" 4 Michael Hamlin <myrrhlin@gmail.com> .IP "\(bu" 4 Mohammad S Anwar <mohammad.anwar@yahoo.com> .IP "\(bu" 4 Peter Haworth <peter.haworth@headforwards.com> .IP "\(bu" 4 Philip J. Ludlam <p.ludlam@cv\-library.co.uk> .IP "\(bu" 4 Ricardo Signes <rjbs@semiotic.systems> .IP "\(bu" 4 Zoffix Znet <cpan@zoffix.com> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[[=s- - man3/Test::Deep::Boolean.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Boolean 3" .TH Test::Deep::Boolean 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Boolean .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[,�L�! ! man3/Test::Deep::Isa.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Isa 3" .TH Test::Deep::Isa 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Isa .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�'qn! ! man3/Test::Deep::Obj.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Obj 3" .TH Test::Deep::Obj 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Obj .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[De��K K & man3/Test::Deep::ArrayElementsOnly.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ArrayElementsOnly 3" .TH Test::Deep::ArrayElementsOnly 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ArrayElementsOnly .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�ؕ* * man3/Test::Deep::String.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::String 3" .TH Test::Deep::String 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::String .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�F�$ $ man3/Test::Deep::None.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::None 3" .TH Test::Deep::None 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::None .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[0NT�! ! man3/Test::Deep::Cmp.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Cmp 3" .TH Test::Deep::Cmp 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Cmp .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ت 1$ $ man3/Test::Deep::Code.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Code 3" .TH Test::Deep::Code 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Code .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[7N�K? ? " man3/Test::Deep::ScalarRefOnly.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ScalarRefOnly 3" .TH Test::Deep::ScalarRefOnly 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ScalarRefOnly .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�'�YE E $ man3/Test::Deep::ArrayLengthOnly.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::ArrayLengthOnly 3" .TH Test::Deep::ArrayLengthOnly 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::ArrayLengthOnly .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�(� ' ' man3/Test::Deep::Class.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Class 3" .TH Test::Deep::Class 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Class .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[�,hh- - man3/Test::Deep::RefType.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::RefType 3" .TH Test::Deep::RefType 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::RefType .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[U�j0 0 man3/Test::Deep::HashKeys.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::HashKeys 3" .TH Test::Deep::HashKeys 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::HashKeys .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[˨Tl? ? " man3/Test::Deep::Cache::Simple.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Deep::Cache::Simple 3" .TH Test::Deep::Cache::Simple 3 "2023-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Deep::Cache::Simple .SH "VERSION" .IX Header "VERSION" version 1.204 .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Fergal Daly .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 <cpan@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Fergal Daly. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ arch/auto/Test/Deep/.existsnu �[��� PK � �[��xϪo �o lib/Test/Deep.pmnu ��6�$ use v5.10.0; use strict; use warnings; package Test::Deep 1.204; # ABSTRACT: Extremely flexible deep comparison use Carp qw( confess ); use Test::Deep::Cache; use Test::Deep::Stack; use Test::Deep::RegexpVersion; require overload; use Scalar::Util; my $Test; unless (defined $Test::Deep::NoTest::NoTest) { # for people who want eq_deeply but not Test::Builder require Test::Builder; $Test = Test::Builder->new; } our ($Stack, %Compared, $CompareCache, %WrapCache, $Shallow); require Exporter; our @ISA = qw( Exporter ); our $Snobby = 1; # should we compare classes? our $Expects = 0; # are we comparing got vs expect or expect vs expect our $LeafWrapper; # to wrap simple values in a test; if not set, shallow() our $DNE = \""; our $DNE_ADDR = Scalar::Util::refaddr($DNE); # if no sub name is supplied then we use the package name in lower case my @constructors = ( All => "", Any => "", Array => "", ArrayEach => "array_each", ArrayElementsOnly => "", ArrayLength => "", ArrayLengthOnly => "", Blessed => "", Boolean => "bool", Code => "", Hash => "", HashEach => "hash_each", HashKeys => "", HashKeysOnly => "", Ignore => "", Isa => "Isa", ListMethods => "", Methods => "", None => "", Number => "num", Obj => "obj_isa", RefType => "", Regexp => "re", RegexpMatches => "", RegexpOnly => "", RegexpRef => "", RegexpRefOnly => "", ScalarRef => "scalref", ScalarRefOnly => "", Shallow => "", String => "str", ); my @CONSTRUCTORS_FROM_CLASSES; while (my ($pkg, $name) = splice @constructors, 0, 2) { $name = lc($pkg) unless $name; my $full_pkg = "Test::Deep::$pkg"; my $file = "$full_pkg.pm"; $file =~ s#::#/#g; my $sub = sub { # We might be in the middle of testing one of the globals that require() # overwrites. To simplify test authorship, we'll preserve any existing # value. { local $@; local $!; local $^E; require $file; } return $full_pkg->new(@_); }; { no strict 'refs'; *{$name} = $sub; } push @CONSTRUCTORS_FROM_CLASSES, $name; } { our @EXPORT_OK = qw( descend render_stack cmp_details deep_diag true false ); our %EXPORT_TAGS; $EXPORT_TAGS{preload} = []; $EXPORT_TAGS{v0} = [ qw( Isa blessed obj_isa all any array array_each arrayelementsonly arraylength arraylengthonly bag bool cmp_bag cmp_deeply cmp_methods cmp_set code eq_deeply hash hash_each hashkeys hashkeysonly ignore isa listmethods methods noclass none noneof num re reftype regexpmatches regexponly regexpref regexprefonly scalarrefonly scalref set shallow str subbagof subhashof subsetof superbagof superhashof supersetof useclass ) ]; $EXPORT_TAGS{v1} = [ qw( obj_isa all any array array_each arrayelementsonly arraylength arraylengthonly bag bool cmp_bag cmp_deeply cmp_methods cmp_set code eq_deeply hash hash_each hashkeys hashkeysonly ignore listmethods methods noclass none noneof num re reftype regexpmatches regexponly regexpref regexprefonly scalarrefonly scalref set shallow str subbagof subhashof subsetof superbagof superhashof supersetof useclass ) ]; our @EXPORT = @{ $EXPORT_TAGS{ v0 } }; $EXPORT_TAGS{all} = [ @EXPORT, @EXPORT_OK ]; } sub import { my $self = shift; my $from_notest = grep {$_ eq '_notest'} @_; if ($from_notest) { @_ = grep {$_ ne '_notest'} @_; } else { require Test::Builder; $Test = Test::Builder->new; } my @sans_preload = grep {; $_ ne ':preload' } @_; if (@_ != @sans_preload) { require Test::Deep::All; require Test::Deep::Any; require Test::Deep::Array; require Test::Deep::ArrayEach; require Test::Deep::ArrayElementsOnly; require Test::Deep::ArrayLength; require Test::Deep::ArrayLengthOnly; require Test::Deep::Blessed; require Test::Deep::Boolean; require Test::Deep::Cache::Simple; require Test::Deep::Cache; require Test::Deep::Class; require Test::Deep::Cmp; require Test::Deep::Code; require Test::Deep::Hash; require Test::Deep::HashEach; require Test::Deep::HashElements; require Test::Deep::HashKeys; require Test::Deep::HashKeysOnly; require Test::Deep::Ignore; require Test::Deep::Isa; require Test::Deep::ListMethods; require Test::Deep::Methods; require Test::Deep::MM; require Test::Deep::None; require Test::Deep::Number; require Test::Deep::Obj; require Test::Deep::Ref; require Test::Deep::RefType; require Test::Deep::Regexp; require Test::Deep::RegexpMatches; require Test::Deep::RegexpOnly; require Test::Deep::RegexpRef; require Test::Deep::RegexpRefOnly; require Test::Deep::RegexpVersion; require Test::Deep::ScalarRef; require Test::Deep::ScalarRefOnly; require Test::Deep::Set; require Test::Deep::Shallow; require Test::Deep::Stack; require Test::Deep::String; } $self->export_to_level(1, $self, @_); } # this is ugly, I should never have exported a sub called isa now I # have to try figure out if the recipient wanted my isa or if a class # imported us and UNIVERSAL::isa is being called on that class. # Luckily our isa always expects 1 argument and U::isa always expects # 2, so we can figure out (assuming the caller is not buggy). sub isa { if (@_ == 1) { goto &Isa; } else { goto &UNIVERSAL::isa; } } sub cmp_deeply { my ($d1, $d2, $name) = @_; my ($ok, $stack) = cmp_details($d1, $d2); if (not $Test->ok($ok, $name)) { my $diag = deep_diag($stack); $Test->diag($diag); } return $ok; } sub cmp_details { my ($d1, $d2) = @_; local $Stack = Test::Deep::Stack->new; local $CompareCache = Test::Deep::Cache->new; local %WrapCache; my $ok = descend($d1, $d2); return ($ok, $Stack); } sub eq_deeply { my ($d1, $d2) = @_; my ($ok) = cmp_details($d1, $d2); return $ok } sub eq_deeply_cache { # this is like cross between eq_deeply and descend(). It doesn't start # with a new $CompareCache but if the comparison fails it will leave # $CompareCache as if nothing happened. However, if the comparison # succeeds then $CompareCache retains all the new information # this allows Set and Bag to handle circular refs my ($d1, $d2, $name) = @_; local $Stack = Test::Deep::Stack->new; $CompareCache->local; my $ok = descend($d1, $d2); $CompareCache->finish($ok); return $ok; } sub deep_diag { my $stack = shift; # ick! incArrow and other things expect the stack has to be visible # in a well known place . TODO clean this up local $Stack = $stack; my $where = render_stack('$data', $stack); confess "No stack to diagnose" unless $stack; my $last = $stack->getLast; my $diag; my $message; my $got; my $expected; my $exp = $last->{exp}; if (Scalar::Util::blessed($exp)) { if ($exp->can("diagnostics")) { $diag = $exp->diagnostics($where, $last); $diag =~ s/\n+$/\n/; } else { if ($exp->can("diag_message")) { $message = $exp->diag_message($where); } } } if (not defined $diag) { $got //= $exp->renderGot($last->{got}); $expected //= $exp->renderExp; $message //= "Compared $where"; $diag = <<EOM $message got : $got expect : $expected EOM } return $diag; } sub render_val { my $val = shift; my $rendered; if (defined $val) { $rendered = ref($val) ? (Scalar::Util::refaddr($val) eq $DNE_ADDR ? "Does not exist" : overload::StrVal($val) ) : qq('$val'); } else { $rendered = "undef"; } return $rendered; } sub descend { my ($d1, $d2) = @_; if (!ref $d1 and !ref $d2) { # Shortcut comparison for the non-reference case. if (defined $d1) { return 1 if defined $d2 and $d1 eq $d2; } else { return 1 if !defined $d2; } } if (! $Expects and Scalar::Util::blessed($d1) and $d1->isa("Test::Deep::Cmp")) { my $where = $Stack->render('$data'); confess "Found a special comparison in $where\nYou can only use specials in the expects structure"; } if (ref $d1 and ref $d2) { # this check is only done when we're comparing 2 expecteds against each # other if ($Expects and Scalar::Util::blessed($d1) and $d1->isa("Test::Deep::Cmp")) { # check they are the same class return 0 unless Test::Deep::blessed(Scalar::Util::blessed($d2))->descend($d1); if ($d1->can("compare")) { return $d1->compare($d2); } } my $s1 = Scalar::Util::refaddr($d1); my $s2 = Scalar::Util::refaddr($d2); if ($s1 eq $s2) { return 1; } if ($CompareCache->cmp($d1, $d2)) { # we've tried comparing these already so either they turned out to # be the same or we must be in a loop and we have to assume they're # the same return 1; } else { $CompareCache->add($d1, $d2) } } $d2 = wrap($d2); $Stack->push({exp => $d2, got => $d1}); if (ref($d1) and (Scalar::Util::refaddr($d1) == $DNE_ADDR)) { # whatever it was supposed to be, it didn't exist and so it's an # automatic fail return 0; } if ($d2->descend($d1)) { # print "d1 = $d1, d2 = $d2\nok\n"; $Stack->pop; return 1; } else { # print "d1 = $d1, d2 = $d2\nnot ok\n"; return 0; } } sub wrap { my $data = shift; my $class = Scalar::Util::blessed($data); return $data if defined $class and $data->isa("Test::Deep::Cmp"); if (defined $class and $data->can('as_test_deep_cmp')) { my $cmp = $data->as_test_deep_cmp; return $cmp if $cmp->isa('Test::Deep::Cmp'); Carp::confess("object in expected structure provides as_test_deep_cmp but it did not return a Test::Deep::Cmp"); } my $reftype = _td_reftype($data); my $cmp; if($reftype eq '') { $cmp = $Test::Deep::LeafWrapper ? $Test::Deep::LeafWrapper->($data) : shallow($data); } else { my $addr = Scalar::Util::refaddr($data); return $WrapCache{$addr} if $WrapCache{$addr}; if($reftype eq 'ARRAY') { $cmp = array($data); } elsif($reftype eq 'HASH') { $cmp = hash($data); } elsif($reftype eq 'SCALAR' or $reftype eq 'REF') { $cmp = scalref($data); } elsif(($reftype eq 'Regexp') or ($reftype eq 'REGEXP')) { $cmp = regexpref($data); } else { $cmp = $Test::Deep::LeafWrapper ? $Test::Deep::LeafWrapper->($data) : shallow($data); } $WrapCache{$addr} = $cmp; } return $cmp; } sub _td_reftype { my $val = shift; my $reftype = Scalar::Util::reftype($val); return '' unless defined $reftype; return $reftype unless $Test::Deep::RegexpVersion::OldStyle; my $blessed = Scalar::Util::blessed($val); return $reftype unless defined $blessed; if ($blessed && $blessed eq "Regexp" and $reftype eq "SCALAR") { $reftype = "Regexp" } return $reftype; } sub render_stack { my ($var, $stack) = @_; return $stack->render($var); } sub cmp_methods { local $Test::Builder::Level = $Test::Builder::Level + 1; return cmp_deeply(shift, methods(@{shift()}), shift); } sub requireclass { require Test::Deep::Class; my $val = shift; return Test::Deep::Class->new(1, $val); } # docs and export say this is called useclass, doh! *useclass = \&requireclass; sub noclass { require Test::Deep::Class; my $val = shift; return Test::Deep::Class->new(0, $val); } sub set { require Test::Deep::Set; return Test::Deep::Set->new(1, "", @_); } sub supersetof { require Test::Deep::Set; return Test::Deep::Set->new(1, "sup", @_); } sub subsetof { require Test::Deep::Set; return Test::Deep::Set->new(1, "sub", @_); } sub noneof { require Test::Deep::Set; return Test::Deep::Set->new(1, "none", @_); } sub cmp_set { local $Test::Builder::Level = $Test::Builder::Level + 1; return cmp_deeply(shift, set(@{shift()}), shift); } sub bag { require Test::Deep::Set; return Test::Deep::Set->new(0, "", @_); } sub superbagof { require Test::Deep::Set; return Test::Deep::Set->new(0, "sup", @_); } sub subbagof { require Test::Deep::Set; return Test::Deep::Set->new(0, "sub", @_); } sub cmp_bag { local $Test::Builder::Level = $Test::Builder::Level + 1; my $ref = ref($_[1]) || ""; confess "Argument 2 to cmp_bag is not an ARRAY ref (".render_val($_[1]).")" unless $ref eq "ARRAY"; return cmp_deeply(shift, bag(@{shift()}), shift); } sub superhashof { require Test::Deep::Hash; my $val = shift; return Test::Deep::SuperHash->new($val); } sub subhashof { require Test::Deep::Hash; my $val = shift; return Test::Deep::SubHash->new($val); } sub true { bool(1); } sub false { bool(0); } sub builder { if (@_) { $Test = shift; } return $Test; } 1; =pod =encoding UTF-8 =head1 NAME Test::Deep - Extremely flexible deep comparison =head1 VERSION version 1.204 =head1 SYNOPSIS use Test::More tests => $Num_Tests; use Test::Deep; cmp_deeply( $actual_horrible_nested_data_structure, $expected_horrible_nested_data_structure, "got the right horrible nested data structure" ); cmp_deeply( $object, methods(name => "John", phone => "55378008"), "object methods ok" ); cmp_deeply( \@array, [$hash1, $hash2, ignore()], "first 2 elements are as expected, ignoring 3" ); cmp_deeply( $object, noclass({value => 5}), "object looks ok, not checking its class" ); cmp_deeply( \@result, bag('a', 'b', {key => [1, 2]}), "array has the 3 things we wanted in some order" ); =head1 DESCRIPTION If you don't know anything about automated testing in Perl then you should probably read about L<Test::Simple> and L<Test::More> before preceding. Test::Deep uses the L<Test::Builder> framework. Test::Deep gives you very flexible ways to check that the result you got is the result you were expecting. At its simplest it compares two structures by going through each level, ensuring that the values match, that arrays and hashes have the same elements and that references are blessed into the correct class. It also handles circular data structures without getting caught in an infinite loop. Where it becomes more interesting is in allowing you to do something besides simple exact comparisons. With strings, the C<eq> operator checks that 2 strings are exactly equal but sometimes that's not what you want. When you don't know exactly what the string should be but you do know some things about how it should look, C<eq> is no good and you must use pattern matching instead. Test::Deep provides pattern matching for complex data structures Test::Deep has B<I<a lot>> of exports. See L</EXPORTS> below. =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 EXAMPLES How Test::Deep works is much easier to understand by seeing some examples. =head2 Without Test::Deep Say you want to test a function which returns a string. You know that your string should be a 7 digit number beginning with 0, C<eq> is no good in this situation, you need a regular expression. So you could use Test::More's C<like()> function: like($string, qr/^0[0-9]{6}$/, "number looks good"); Similarly, to check that a string looks like a name, you could do: like($string, qr/^(Mr|Mrs|Miss) \w+ \w+$/, "got title, first and last name"); Now imagine your function produces a hash with some personal details in it. You want to make sure that there are 2 keys, Name and Phone and that the name looks like a name and the phone number looks like a phone number. You could do: $hash = make_person(); like($hash->{Name}, qr/^(Mr|Mrs|Miss) \w+ \w+$/, "name ok"); like($hash->{Phone}, qr/^0[0-9]{6}$/, "phone ok"); is(scalar keys %$hash, 2, "correct number of keys"); But that's not quite right, what if make_person has a serious problem and didn't even return a hash? We really need to write if (ref($hash) eq "HASH") { like($hash->{Name}, qr/^(Mr|Mrs|Miss) \w+ \w+$/, "name ok"); like($hash->{Phone}, qr/^0[0-9]{6}$/, "phone ok"); is(scalar keys %$hash, 2, "correct number of keys"); } else { fail("person not a hash"); fail("person not a hash"); fail("person not a hash"); # need 3 to keep the plan correct } Already this is getting messy, now imagine another entry in the hash, an array of children's names. This would require if (ref($hash) eq "HASH") { like($hash->{Name}, $name_pat, "name ok"); like($hash->{Phone}, '/^0d{6}$/', "phone ok"); my $cn = $hash->{ChildNames}; if (ref($cn) eq "ARRAY") { foreach my $child (@$cn) { like($child, $name_pat); } } else { fail("child names not an array") } } else { fail("person not a hash"); } This is a horrible mess and because we don't know in advance how many children's names there will be, we can't make a plan for our test anymore (actually, we could but it would make things even more complicated). Test::Deep to the rescue. =head2 With Test::Deep my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); cmp_deeply( $person, { Name => $name_re, Phone => re('^0d{6}$'), ChildNames => array_each($name_re) }, "person ok" ); This will do everything that the messy code above does and it will give a sensible message telling you exactly what went wrong if it finds a part of $person that doesn't match the pattern. C<re()> and C<array_each()> are special function imported from Test::Deep. They create a marker that tells Test::Deep that something different is happening here. Instead of just doing a simple comparison and checking are two things exactly equal, it should do something else. If a person was asked to check that 2 structures are equal, they could print them both out and compare them line by line. The markers above are similar to writing a note in red pen on one of the printouts telling the person that for this piece of the structure, they should stop doing simple line by line comparison and do something else. C<re($regex)> means that Test::Deep should check that the current piece of data matches the regex in C<$regex>. C<array_each($struct)> means that Test::Deep should expect the current piece of data to be an array and it should check that every element of that array matches C<$struct>. In this case, every element of C<< $person->{ChildNames} >> should look like a name. If say the 3rd one didn't you would get an error message something like Using Regexp on $data->{ChildNames}[3] got : 'Queen John Paul Sartre' expect : /^(Mr|Mrs|Miss) \w+ \w+$/ There are lots of other special comparisons available, see L<SPECIAL COMPARISONS PROVIDED> below for the full list. =head2 Reusing structures Test::Deep is good for reusing test structures so you can do this my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); my $person_cmp = { Name => $name_re, Phone => re('^0d{6}$'), ChildNames => array_each($name_re) }; cmp_deeply($person1, $person_cmp, "person ok"); cmp_deeply($person2, $person_cmp, "person ok"); cmp_deeply($person3, $person_cmp, "person ok"); You can even put $person_cmp in a module and let other people use it when they are writing test scripts for modules that use your modules. To make things a little more difficult, lets change the person data structure so that instead of a list of ChildNames, it contains a list of hashes, one for each child. So in fact our person structure will contain other person structures which may contain other person structures and so on. This is easy to handle with Test::Deep because Test::Deep structures can include themselves. Simply do my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); my $person_cmp = { Name => $name_re, Phone => re('^0d{6}$'), # note no mention of Children here }; $person_cmp->{Children} = array_each($person_cmp); cmp_deeply($person, $person_cmp, "person ok"); This will now check that $person->{Children} is an array and that every element of that array also matches C<$person_cmp>, this includes checking that its children also match the same pattern and so on. =head2 Circular data structures A circular data structure is one which loops back on itself, you can make one easily by doing my @b; my @a = (1, 2, 3, \@b); push(@b, \@a); now C<@a> contains a reference to be C<@b> and C<@b> contains a reference to C<@a>. This causes problems if you have a program that wants to look inside C<@a> and keep looking deeper and deeper at every level, it could get caught in an infinite loop looking into C<@a> then C<@b> then C<@a> then C<@b> and so on. Test::Deep avoids this problem so we can extend our example further by saying that a person should also list their parents. my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); my $person_cmp = { Name => $name_re, Phone => re('^0d{6}$'), # note no mention of Children here }; $person_cmp->{Children} = each_array($person_cmp); $person_cmp->{Parents} = each_array($person_cmp); cmp_deeply($person, $person_cmp, "person ok"); So this will check that for each child C<$child> in C<< $person->{Children} >> that the C<< $child->{Parents} >> matches C<$person_cmp> however it is smart enough not to get caught in an infinite loop where it keeps bouncing between the same Parent and Child. =head1 TERMINOLOGY C<cmp_deeply($got, $expected, $name)> takes 3 arguments. C<$got> is the structure that you are checking, you must not include any special comparisons in this structure or you will get a fatal error. C<$expected> describes what Test::Deep will be looking for in $got. You can put special comparisons in $expected if you want to. As Test::Deep descends through the 2 structures, it compares them one piece at a time, so at any point in the process, Test::Deep is thinking about 2 things - the current value from C<$got> and the current value from C<$expected>. In the documentation, I call them C<$got_v> and C<exp_v> respectively. =head1 COMPARISON FUNCTIONS =head3 cmp_deeply my $ok = cmp_deeply($got, $expected, $name) C<$got> is the result to be checked. C<$expected> is the structure against which C<$got> will be check. C<$name> is the test name. This is the main comparison function, the others are just wrappers around this. C<$got> and C<$expected> are compared recursively. Each value in C<$expected> defines what's expected at the corresponding location in C<$got>. Simple scalars are compared with C<eq>. References to structures like hashes and arrays are compared recursively. Items in C<$expected>, though, can also represent complex tests that check for numbers in a given range, hashes with at least a certain set of keys, a string matching a regex, or many other things. See L</WHAT ARE SPECIAL COMPARISONS> for details. =head3 cmp_bag my $ok = cmp_bag(\@got, \@bag, $name) Is shorthand for cmp_deeply(\@got, bag(@bag), $name) I<n.b.>: Both arguments must be array refs. If they aren't an exception will be thrown. =head3 cmp_set my $ok = cmp_set(\@got, \@set, $name) Is shorthand for cmp_deeply(\@got, set(@set), $name) =head3 cmp_methods my $ok = cmp_methods(\@got, \@methods, $name) Is shorthand for cmp_deeply(\@got, methods(@methods), $name) =head3 eq_deeply my $ok = eq_deeply($got, $expected) This is the same as cmp_deeply() except it just returns true or false. It does not create diagnostics or talk to L<Test::Builder>, but if you want to use it in a non-testing environment then you should import it through L<Test::Deep::NoTest>. For example use Test::Deep::NoTest; print "a equals b" unless eq_deeply($a, $b); otherwise the L<Test::Builder> framework will be loaded and testing messages will be output when your program ends. =head3 cmp_details ($ok, $stack) = cmp_details($got, $expected) This behaves much like eq_deeply, but it additionally allows you to produce diagnostics in case of failure by passing the value in C<$stack> to C<deep_diag>. Do not make assumptions about the structure or content of C<$stack> and do not use it if C<$ok> contains a true value. See L</USING TEST::DEEP WITH TEST::BUILDER> for example uses. =head1 SPECIAL COMPARISONS PROVIDED In the documentation below, C<$got_v> is used to indicate any given value within the C<$got> structure. =head3 ignore cmp_deeply( $got, ignore() ); This makes Test::Deep skip tests on C<$got_v>. No matter what value C<$got_v> has, Test::Deep will think it's correct. This is useful if some part of the structure you are testing is very complicated and already tested elsewhere, or if it is unpredictable. cmp_deeply( $got, { name => 'John', random => ignore(), address => [ '5 A street', 'a town', 'a country' ], } ); is the equivalent of checking $got->{name} eq 'John'; exists $got->{random}; cmp_deeply($got->{address}, ['5 A street', 'a town', 'a country']); =head3 methods cmp_deeply( $got, methods(%hash) ); %hash is a hash of method call => expected value pairs. This lets you call methods on an object and check the result of each call. The methods will be called in the order supplied. If you want to pass arguments to the method you should wrap the method name and arguments in an array reference. cmp_deeply( $obj, methods(name => "John", ["favourite", "food"] => "taco") ); is roughly the equivalent of checking that $obj->name eq "John" $obj->favourite("food") eq "taco" The methods will be called in the order you supply them and will be called in scalar context. If you need to test methods called in list context then you should use C<listmethods()>. B<NOTE> Just as in a normal test script, you need to be careful if the methods you call have side effects like changing the object or other objects in the structure. Although the order of the methods is fixed, the order of some other tests is not so if C<$expected> is { manager => methods(@manager_methods), coder => methods(@coder_methods) } there is no way to know which if manager and coder will be tested first. If the methods you are testing depend on and alter global variables or if manager and coder are the same object then you may run into problems. =head3 listmethods cmp_deeply( $got, listmethods(%hash) ); C<%hash> is a hash of pairs mapping method names to expected return values. This is almost identical to methods() except the methods are called in list context instead of scalar context. This means that the expected return values supplied must be in array references. cmp_deeply( $obj, listmethods( name => [ "John" ], ["favourites", "food"] => ["Mapo tofu", "Gongbao chicken"] ) ); is the equivalent of checking that cmp_deeply([$obj->name], ["John"]); cmp_deeply([$obj->favourites("food")], ["Mapo tofu", "Gongbao chicken"]); The methods will be called in the order you supply them. B<NOTE> The same caveats apply as for methods(). =head3 shallow cmp_deeply( $got, shallow($thing) ); C<$thing> is a ref. This prevents Test::Deep from looking inside C<$thing>. It allows you to check that C<$got_v> and C<$thing> are references to the same variable. So my @a = @b = (1, 2, 3); cmp_deeply(\@a, \@b); will pass because C<@a> and C<@b> have the same elements however cmp_deeply(\@a, shallow(\@b)) will fail because although C<\@a> and C<\@b> both contain C<1, 2, 3> they are references to different arrays. =head3 noclass cmp_deeply( $got, noclass($thing) ); C<$thing> is a structure to be compared against. This makes Test::Deep ignore the class of objects, so it just looks at the data they contain. Class checking will be turned off until Test::Deep is finished comparing C<$got_v> against C<$thing>. Once Test::Deep comes out of C<$thing> it will go back to its previous setting for checking class. This can be useful when you want to check that objects have been constructed correctly but you don't want to write lots of C<bless>es. If C<@people> is an array of Person objects then cmp_deeply(\@people, [ bless {name => 'John', phone => '555-5555'}, "Person", bless {name => 'Anne', phone => '444-4444'}, "Person", ]); can be replaced with cmp_deeply(\@people, noclass([ {name => 'John', phone => '555-5555'}, {name => 'Anne', phone => '444-4444'} ])); However, this is testing so you should also check that the objects are blessed correctly. You could use a map to bless all those hashes or you could do a second test like cmp_deeply(\@people, array_each(isa("Person")); =head3 useclass cmp_deeply( $got, useclass($thing) ); This turns back on the class comparison while inside a C<noclass()>. cmp_deeply( $got, noclass( [ useclass( $object ) ] ) ) In this example the class of the array reference in C<$got> is ignored but the class of C<$object> is checked, as is the class of everything inside C<$object>. =head3 re cmp_deeply( $got, re($regexp, $capture_data, $flags) ); C<$regexp> is either a regular expression reference produced with C<qr/.../> or a string which will be used to construct a regular expression. C<$capture_data> is optional and is used to check the strings captured by an regex. This should can be an array ref or a Test::Deep comparator that works on array refs. C<$flags> is an optional string which controls whether the regex runs as a global match. If C<$flags> is "g" then the regex will run as C<m/$regexp/g>. Without C<$capture_data>, this simply compares C<$got_v> with the regular expression provided. So cmp_deeply($got, [ re("ferg") ]) is the equivalent of $got->[0] =~ /ferg/ With C<$capture_data>, cmp_deeply($got, [re($regex, $capture_data)]) is the equivalent of my @data = $got->[0] =~ /$regex/; cmp_deeply(\@data, $capture_data); So you can do something simple like cmp_deeply($got, re(qr/(\d\d)(\w\w)/, [25, "ab" ])) to check that C<(\d\d)> was 25 and C<(\w\w)> was "ab" but you can also use Test::Deep objects to do more complex testing of the captured values cmp_deeply( "cat=2,dog=67,sheep=3,goat=2,dog=5", re( qr/(\D+)=\d+,?/, set(qw( cat sheep dog )), "g" ), ); here, the regex will match the string and will capture the animal names and check that they match the specified set, in this case it will fail, complaining that "goat" is not in the set. =head3 all cmp_deeply( $got, all(@expecteds) ); C<@expecteds> is an array of expected structures. This allows you to compare data against multiple expected results and make sure each of them matches. cmp_deeply($got, all(isa("Person"), methods(name => 'John'))) is equivalent to $got->isa("Person") $got->name eq 'John' If either test fails then the whole thing is considered a fail. This is a short-circuit test, the testing is stopped after the first failure, although in the future it may complete all tests so that diagnostics can be output for all failures. When reporting failure, the parts are counted from 1. Thanks to the magic of overloading, you can write any( re("^wi"), all(isa("Person"), methods(name => 'John')) ) as re("^wi") | isa("Person") & methods(name => 'John') Note B<single> C<|> not double, as C<||> cannot be overloaded. This will only work when there is a special comparison involved. If you write "john" | "anne" | "robert" Perl will turn this into "{onort" which is presumably not what you wanted. This is because perl ors them together as strings before Test::Deep gets a chance to do any overload tricks. =head3 any cmp_deeply( $got, any(@expecteds) ); C<@expecteds> is an array of expected structures. This can be used to compare data against multiple expected results and make sure that at least one of them matches. This is a short-circuit test so if a test passes then none of the tests after that will be attempted. You can also use overloading with C<|> similarly to all(). =head3 Isa cmp_deeply( $got, Isa($class) ); =head3 isa cmp_deeply( $got, isa($class) ); C<$class> is a class name. This uses C<UNIVERSAL::isa()> to check that C<$got_v> is blessed into the class C<$class>. B<NOTE:> C<Isa()> does exactly as documented here, but C<isa()> is slightly different. If C<isa()> is called with 1 argument it falls through to C<Isa()>. If C<isa()> called with 2 arguments, it falls through to C<UNIVERSAL::isa>. This is to prevent breakage when you import C<isa()> into a package that is used as a class. Without this, anyone calling C<Class-E<gt>isa($other_class)> would get the wrong answer. This is a hack to patch over the fact that C<isa> is exported by default. =head3 obj_isa cmp_deeply( $got, obj_isa($class) ); This test accepts only objects that are instances of C<$class> or a subclass. Unlike the C<Isa> test, this test will never accept class names. =head3 array_each cmp_deeply( \@got, array_each($thing) ); C<$thing> is a structure to be compared against. <$got_v> must be an array reference. Each element of it will be compared to C<$thing>. This is useful when you have an array of similar things, for example objects of a known type and you don't want to have to repeat the same test for each one. my $common_tests = all( isa("MyFile"), methods( handle => isa("IO::Handle") filename => re("^/home/ted/tmp"), ) ); cmp_deeply($got, array_each($common_tests)); is similar to foreach my $got_v (@$got) { cmp_deeply($got_v, $common_tests) } Except it will not explode if C<$got> is not an array reference. It will check that each of the objects in C<@$got> is a MyFile and that each one gives the correct results for its methods. You could go further, if for example there were 3 files and you knew the size of each one you could do this cmp_deeply( $got, all( array_each($common_tests), [ methods(size => 1000), methods(size => 200), methods(size => 20) ] ) ) cmp_deeply($got, array_each($structure)); =head3 hash_each cmp_deeply( \%got, hash_each($thing) ); This test behaves like C<array_each> (see above) but tests that each hash value passes its tests. =head3 str cmp_deeply( $got, str($string) ); $string is a string. This will stringify C<$got_v> and compare it to C<$string> using C<eq>, even if C<$got_v> is a ref. It is useful for checking the stringified value of an overloaded reference. =head3 num cmp_deeply( $got, num($number, $tolerance) ); C<$number> is a number. C<$tolerance> is an optional number. This will add 0 to C<$got_v> and check if it's numerically equal to C<$number>, even if C<$got_v> is a ref. It is useful for checking the numerical value of an overloaded reference. If C<$tolerance> is supplied then this will check that C<$got_v> and C<$exp_v> are less than C<$tolerance> apart. This is useful when comparing floating point numbers as rounding errors can make it hard or impossible for C<$got_v> to be exactly equal to C<$exp_v>. When C<$tolerance> is supplied, the test passes if C<abs($got_v - $exp_v) <= $tolerance>. B<Note> in Perl, C<"12blah" == 12> because Perl will be smart and convert "12blah" into 12. You may not want this. There was a strict mode but that is now gone. A "looks like a number" test will replace it soon. Until then you can usually just use the string() comparison to be more strict. This will work fine for almost all situations, however it will not work when <$got_v> is an overloaded value who's string and numerical values differ. =head3 bool, true, false cmp_deeply( $got, bool($value) ); cmp_deeply( $got, true ); cmp_deeply( $got, false ); C<$value> is anything you like but it's probably best to use 0 or 1 This will check that C<$got_v> and C<$value> have the same truth value, that is they will give the same result when used in boolean context, like in an C<if()> statement. B<Note:> C<true> and C<false> are only imported by special request. =head3 code cmp_deeply( $got, code(\&subref) ); C<\&subref> is a reference to a subroutine which will be passed a single argument, it then should return a true or false and possibly a string This will pass C<$got_v> to the subroutine which returns true or false to indicate a pass or fail. Fails can be accompanied by a diagnostic string which gives an explanation of why it's a fail. sub check_name { my $name = shift; if ($boss->likes($name)) { return 1; } else { return (0, "the boss doesn't like your name"); } } cmp_deeply("Brian", code(\&check_name)); =head2 SET COMPARISONS Set comparisons give special semantics to array comparisons: =over 4 =item * The order of items in a set is irrelevant =item * The presence of duplicate items in a set is ignored. =back As such, in any set comparison, the following arrays are equal: [ 1, 2 ] [ 1, 1, 2 ] [ 1, 2, 1 ] [ 2, 1, 1 ] [ 1, 1, 2 ] All are interpreted by C<set> semantics as if the set was only specified as: [ 1, 2 ] All C<set> functions return an object which can have additional items added to it: my $set = set( 1, 2 ); $set->add(1, 3, 1 ); # Set is now ( 1, 2, 3 ) Special care must be taken when using special comparisons within sets. See L</SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS> for details. =head3 set cmp_deeply( \@got, set(@elements) ); This does a set comparison, that is, it compares two arrays but ignores the order of the elements and it ignores duplicate elements, but ensures that all items in C<@elements> will be in C<$got> and all items in C<$got> will be in C<@elements>. So the following tests will be passes, and will be equivalent: cmp_deeply([1, 2, 2, 3], set(3, 2, 1, 1)); cmp_deeply([1, 2, 3], set(3, 2, 1)); =head3 supersetof cmp_deeply( \@got, supersetof(@elements) ); This function works much like L<< C<set>|/set >>, and performs a set comparison of C<$got_v> with the elements of C<@elements>. C<supersetof> is however slightly relaxed, such that C<$got> may contain things not in C<@elements>, but must at least contain all C<@elements>. These two statements are equivalent, and will be passes: cmp_deeply([1,2,3,3,4,5], supersetof(2,2,3)); cmp_deeply([1,2,3,4,5], supersetof(2,3)); But these will be failures: cmp_deeply([1,2,3,4,5], supersetof(2,3,6)); # 6 not in superset cmp_deeply([1], supersetof(1,2)); # 2 not in superset =head3 subsetof cmp_deeply( \@got, subsetof(@elements) ); This function works much like L<< C<set>|/set >>, and performs a set comparison of C<$got_v> with the elements of C<@elements>. This is the inverse of C<supersetof>, which expects all unique elements found in C<$got_v> must be in C<@elements>. cmp_deeply([1,2,4,5], subsetof(2,3,3) ) # Fail: 1,4 & 5 extra cmp_deeply([2,3,3], subsetof(1,2,4,5) ) # Fail: 3 extra cmp_deeply([2,3,3], subsetof(1,2,4,5,3)) # Pass =head3 none cmp_deeply( $got, none(@elements) ); @elements is an array of elements, wherein no elements in C<@elements> may be equal to C<$got_v>. =head3 noneof cmp_deeply( \@got, noneof(@elements) ); @elements is an array of elements, wherein no elements in C<@elements> may be found in C<$got_v>. For example: # Got has no 1, no 2, and no 3 cmp_deeply( [1], noneof( 1, 2, 3 ) ); # fail cmp_deeply( [5], noneof( 1, 2, 3 ) ); # pass =head2 BAG COMPARISONS Bag comparisons give special semantics to array comparisons, that are similar to L<< set comparisons|/SET COMPARISONS >>, but slightly different. =over 4 =item * The order of items in a bag is irrelevant =item * The presence of duplicate items in a bag is B<PRESERVED> =back As such, in any bag comparison, the following arrays are equal: [ 1, 1, 2 ] [ 1, 2, 1 ] [ 2, 1, 1 ] [ 1, 1, 2 ] However, they are B<NOT> equal to any of the following: [ 1, 2 ] [ 1, 2, 2 ] [ 1, 1, 1, 2 ] All C<bag> functions return an object which can have additional items added to it: my $bag = bag( 1, 2 ); $bag->add(1, 3, 1 ); # Bag is now ( 1, 1, 1, 2, 3 ) Special care must be taken when using special comparisons within bags. See L</SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS> for details. =head3 bag cmp_deeply( \@got, bag(@elements) ); This does an order-insensitive bag comparison between C<$got> and C<@elements>, ensuring that: =over 4 =item each item in C<@elements> is found in C<$got> =item the number of times a C<$expected_v> is found in C<@elements> is reflected in C<$got> =item no items are found in C<$got> other than those in C<@elements>. =back As such, the following are passes, and are equivalent to each other: cmp_deeply([1, 2, 2], bag(2, 2, 1)) cmp_deeply([2, 1, 2], bag(2, 2, 1)) cmp_deeply([2, 2, 1], bag(2, 2, 1)) But the following are failures: cmp_deeply([1, 2, 2], bag(2, 2, 1, 1)) # Not enough 1's in Got cmp_deeply([1, 2, 2, 1], bag(2, 2, 1) ) # Too many 1's in Got =head3 superbagof cmp_deeply( \@got, superbagof( @elements ) ); This function works much like L<< C<bag>|/bag >>, and performs a bag comparison of C<$got_v> with the elements of C<@elements>. C<superbagof> is however slightly relaxed, such that C<$got> may contain things not in C<@elements>, but must at least contain all C<@elements>. So: # pass cmp_deeply( [1, 1, 2], superbagof( 1 ) ); # fail: not enough 1's in superbag cmp_deeply( [1, 1, 2], superbagof( 1, 1, 1 )); =head3 subbagof cmp_deeply( \@got, subbagof(@elements) ); This function works much like L<< C<bag>|/bag >>, and performs a bag comparison of C<$got_v> with the elements of C<@elements>. This is the inverse of C<superbagof>, and expects all elements in C<$got> to be in C<@elements>, while allowing items to exist in C<@elements> that are not in C<$got> # pass cmp_deeply( [1], subbagof( 1, 1, 2 ) ); # fail: too many 1's in subbag cmp_deeply( [1, 1, 1], subbagof( 1, 1, 2 ) ); =head2 HASH COMPARISONS Typically, if you're doing simple hash comparisons, cmp_deeply( \%got, \%expected ) is sufficient. C<cmp_deeply> will ensure C<%got> and C<%hash> have identical keys, and each key from either has the same corresponding value. =head3 superhashof cmp_deeply( \%got, superhashof(\%hash) ); This will check that the hash C<%$got> is a "super-hash" of C<%hash>. That is that all the key and value pairs in C<%hash> appear in C<%$got> but C<%$got> can have extra ones also. For example cmp_deeply({a => 1, b => 2}, superhashof({a => 1})) will pass but cmp_deeply({a => 1, b => 2}, superhashof({a => 1, c => 3})) will fail. =head3 subhashof cmp_deeply( \%got, subhashof(\%hash) ); This will check that the hash C<%$got> is a "sub-hash" of C<%hash>. That is that all the key and value pairs in C<%$got> also appear in C<%hash>. For example cmp_deeply({a => 1}, subhashof({a => 1, b => 2})) will pass but cmp_deeply({a => 1, c => 3}, subhashof({a => 1, b => 2})) will fail. =head1 DIAGNOSTIC FUNCTIONS =head3 deep_diag my $reason = deep_diag($stack); C<$stack> is a value returned by cmp_details. Do not call this function if cmp_details returned a true value for C<$ok>. C<deep_diag()> returns a human readable string describing how the comparison failed. =head1 ANOTHER EXAMPLE You've written a module to handle people and their film interests. Say you have a function that returns an array of people from a query, each person is a hash with 2 keys: Name and Age and the array is sorted by Name. You can do cmp_deeply( $result, [ {Name => 'Anne', Age => 26}, {Name => "Bill", Age => 47} {Name => 'John', Age => 25}, ] ); Soon after, your query function changes and all the results now have an ID field. Now your test is failing again because you left out ID from each of the hashes. The problem is that the IDs are generated by the database and you have no way of knowing what each person's ID is. With Test::Deep you can change your query to cmp_deeply( $result, [ {Name => 'John', Age => 25, ID => ignore()}, {Name => 'Anne', Age => 26, ID => ignore()}, {Name => "Bill", Age => 47, ID => ignore()} ] ); But your test still fails. Now, because you're using a database, you no longer know what order the people will appear in. You could add a sort into the database query but that could slow down your application. Instead you can get Test::Deep to ignore the order of the array by doing a bag comparison instead. cmp_deeply( $result, bag( {Name => 'John', Age => 25, ID => ignore()}, {Name => 'Anne', Age => 26, ID => ignore()}, {Name => "Bill", Age => 47, ID => ignore()} ) ); Finally person gets even more complicated and includes a new field called Movies, this is a list of movies that the person has seen recently, again these movies could also come back in any order so we need a bag inside our other bag comparison, giving us something like cmp_deeply( $result, bag( {Name => 'John', Age => 25, ID => ignore(), Movies => bag(...)}, {Name => 'Anne', Age => 26, ID => ignore(), Movies => bag(...)}, {Name => "Bill", Age => 47, ID => ignore(), Movies => bag(...)} ) ); =head1 USING TEST::DEEP WITH TEST::BUILDER Combining C<cmp_details> and C<deep_diag> makes it possible to use Test::Deep in your own test classes. In a L<Test::Builder> subclass, create a test method in the following form: sub behaves_ok { my $self = shift; my $expected = shift; my $test_name = shift; my $got = do_the_important_work_here(); my ($ok, $stack) = cmp_details($got, $expected); unless ($Test->ok($ok, $test_name)) { my $diag = deep_diag($stack); $Test->diag($diag); } } As the subclass defines a test class, not tests themselves, make sure it uses L<Test::Deep::NoTest>, not C<Test::Deep> itself. =head1 LIMITATIONS Currently any CODE, GLOB or IO refs will be compared using shallow(), which means only their memory addresses are compared. =head1 BUGS There is a bug in set and bag compare to do with competing SCs. It only occurs when you put certain special comparisons inside bag or set comparisons you don't need to worry about it. The full details are in the C<bag()> docs. It will be fixed in an upcoming version. =head1 CAVEATS =head2 SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS If you use certain special comparisons within a bag or set comparison there is a danger that a test will fail when it should have passed. It can only happen if two or more special comparisons in the bag are competing to match elements. Consider this comparison cmp_deeply(['furry', 'furball'], bag(re("^fur"), re("furb"))) There are two things that could happen, hopefully C<re("^fur")> is paired with "furry" and C<re("^furb")> is paired with "furb" and everything is fine but it could happen that C<re("^fur")> is paired with "furball" and then C<re("^furb")> cannot find a match and so the test fails. Examples of other competing comparisons are C<bag(1, 2, 2)> vs C<set(1, 2)> and C<< methods(m1 => "v1", m2 => "v2") >> vs C<< methods(m1 => "v1") >> This problem is could be solved by using a slower and more complicated algorithm for set and bag matching. Something for the future... =head1 WHAT ARE SPECIAL COMPARISONS? A special comparison (SC) is simply an object that inherits from Test::Deep::Cmp. Whenever C<$expected_v> is an SC then instead of checking C<$got_v eq $expected_v>, we pass control over to the SC and let it do its thing. Test::Deep exports lots of SC constructors, to make it easy for you to use them in your test scripts. For example is C<re("hello")> is just a handy way of creating a Test::Deep::Regexp object that will match any string containing "hello". So cmp_deeply([ 'a', 'b', 'hello world'], ['a', 'b', re("^hello")]); will check C<'a' eq 'a'>, C<'b' eq 'b'> but when it comes to comparing C<'hello world'> and C<re("^hello")> it will see that $expected_v is an SC and so will pass control to the Test::Deep::Regexp class by do something like C<< $expected_v->descend($got_v) >>. The C<descend()> method should just return true or false. This gives you enough to write your own SCs but I haven't documented how diagnostics works because it's about to get an overhaul (theoretically). =head1 EXPORTS By default, Test::Deep will export everything in its C<v0> tag, as if you had written: use Test::Deep ':v0'; Those things are: all any array array_each arrayelementsonly arraylength arraylengthonly bag blessed bool cmp_bag cmp_deeply cmp_methods cmp_set code eq_deeply hash hash_each hashkeys hashkeysonly ignore Isa isa listmethods methods noclass none noneof num obj_isa re reftype regexpmatches regexponly regexpref regexprefonly scalarrefonly scalref set shallow str subbagof subhashof subsetof superbagof superhashof supersetof useclass A slightly better set of exports is the C<v1> set. It's all the same things, with the exception of C<Isa> and C<blessed>. If you want to import "everything", you probably want to C<< use Test::Deep ':V1'; >>. There's another magic export group: C<:preload>. If that is specified, all of the Test::Deep plugins will be loaded immediately instead of lazily. =head1 SEE ALSO L<Test::More> =head1 THANKS Thanks to Michael G Schwern for Test::More's is_deeply function which inspired this library. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 CONTRIBUTORS =for stopwords Alexander Karelas Belden Lyman Daniel Böhmer David Steinbrunner Denis Ibaev Ed Adjei Fabrice Gabolde Felipe Gasper Fergal Daly George Hartzell Graham Knop Ivan Bessarabov José Joaquín Atria Karen Etheridge Kent Fredric Lance Wicks Matthew Horsfall Michael Hamlin Mohammad S Anwar Peter Haworth Philip J. Ludlam Ricardo Signes Zoffix Znet =over 4 =item * Alexander Karelas <karjala@karjala.org> =item * Belden Lyman <blyman@shutterstock.com> =item * Daniel Böhmer <dboehmer@cpan.org> =item * David Steinbrunner <dsteinbrunner@pobox.com> =item * Denis Ibaev <dionys@gmail.com> =item * Ed Adjei <edmund@cpan.org> =item * Fabrice Gabolde <fabrice.gabolde@gmail.com> =item * Felipe Gasper <felipe@felipegasper.com> =item * Fergal Daly <fergal@esatclear.ie> =item * George Hartzell <hartzell@alerce.com> =item * Graham Knop <haarg@haarg.org> =item * Ivan Bessarabov <ivan@bessarabov.ru> =item * José Joaquín Atria <jjatria@cpan.org> =item * Karen Etheridge <ether@cpan.org> =item * Kent Fredric <kentfredric@gmail.com> =item * Lance Wicks <lancew@cpan.org> =item * Matthew Horsfall <wolfsage@gmail.com> =item * Michael Hamlin <myrrhlin@gmail.com> =item * Mohammad S Anwar <mohammad.anwar@yahoo.com> =item * Peter Haworth <peter.haworth@headforwards.com> =item * Philip J. Ludlam <p.ludlam@cv-library.co.uk> =item * Ricardo Signes <rjbs@semiotic.systems> =item * Zoffix Znet <cpan@zoffix.com> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut __END__ #pod =head1 SYNOPSIS #pod #pod use Test::More tests => $Num_Tests; #pod use Test::Deep; #pod #pod cmp_deeply( #pod $actual_horrible_nested_data_structure, #pod $expected_horrible_nested_data_structure, #pod "got the right horrible nested data structure" #pod ); #pod #pod cmp_deeply( #pod $object, #pod methods(name => "John", phone => "55378008"), #pod "object methods ok" #pod ); #pod #pod cmp_deeply( #pod \@array, #pod [$hash1, $hash2, ignore()], #pod "first 2 elements are as expected, ignoring 3" #pod ); #pod #pod cmp_deeply( #pod $object, #pod noclass({value => 5}), #pod "object looks ok, not checking its class" #pod ); #pod #pod cmp_deeply( #pod \@result, #pod bag('a', 'b', {key => [1, 2]}), #pod "array has the 3 things we wanted in some order" #pod ); #pod #pod =head1 DESCRIPTION #pod #pod If you don't know anything about automated testing in Perl then you should #pod probably read about L<Test::Simple> and L<Test::More> before preceding. #pod Test::Deep uses the L<Test::Builder> framework. #pod #pod Test::Deep gives you very flexible ways to check that the result you got is #pod the result you were expecting. At its simplest it compares two structures #pod by going through each level, ensuring that the values match, that arrays and #pod hashes have the same elements and that references are blessed into the #pod correct class. It also handles circular data structures without getting #pod caught in an infinite loop. #pod #pod Where it becomes more interesting is in allowing you to do something besides #pod simple exact comparisons. With strings, the C<eq> operator checks that 2 #pod strings are exactly equal but sometimes that's not what you want. When you #pod don't know exactly what the string should be but you do know some things #pod about how it should look, C<eq> is no good and you must use pattern matching #pod instead. Test::Deep provides pattern matching for complex data structures #pod #pod Test::Deep has B<I<a lot>> of exports. See L</EXPORTS> below. #pod #pod =head1 EXAMPLES #pod #pod How Test::Deep works is much easier to understand by seeing some examples. #pod #pod =head2 Without Test::Deep #pod #pod Say you want to test a function which returns a string. You know that your #pod string should be a 7 digit number beginning with 0, C<eq> is no good in this #pod situation, you need a regular expression. So you could use Test::More's #pod C<like()> function: #pod #pod like($string, qr/^0[0-9]{6}$/, "number looks good"); #pod #pod Similarly, to check that a string looks like a name, you could do: #pod #pod like($string, qr/^(Mr|Mrs|Miss) \w+ \w+$/, #pod "got title, first and last name"); #pod #pod Now imagine your function produces a hash with some personal details in it. #pod You want to make sure that there are 2 keys, Name and Phone and that the #pod name looks like a name and the phone number looks like a phone number. You #pod could do: #pod #pod $hash = make_person(); #pod like($hash->{Name}, qr/^(Mr|Mrs|Miss) \w+ \w+$/, "name ok"); #pod like($hash->{Phone}, qr/^0[0-9]{6}$/, "phone ok"); #pod is(scalar keys %$hash, 2, "correct number of keys"); #pod #pod But that's not quite right, what if make_person has a serious problem and #pod didn't even return a hash? We really need to write #pod #pod if (ref($hash) eq "HASH") #pod { #pod like($hash->{Name}, qr/^(Mr|Mrs|Miss) \w+ \w+$/, "name ok"); #pod like($hash->{Phone}, qr/^0[0-9]{6}$/, "phone ok"); #pod is(scalar keys %$hash, 2, "correct number of keys"); #pod } #pod else #pod { #pod fail("person not a hash"); #pod fail("person not a hash"); #pod fail("person not a hash"); # need 3 to keep the plan correct #pod } #pod #pod Already this is getting messy, now imagine another entry in the hash, an #pod array of children's names. This would require #pod #pod #pod if (ref($hash) eq "HASH") #pod { #pod like($hash->{Name}, $name_pat, "name ok"); #pod like($hash->{Phone}, '/^0d{6}$/', "phone ok"); #pod my $cn = $hash->{ChildNames}; #pod if (ref($cn) eq "ARRAY") #pod { #pod foreach my $child (@$cn) #pod { #pod like($child, $name_pat); #pod } #pod } #pod else #pod { #pod fail("child names not an array") #pod } #pod } #pod else #pod { #pod fail("person not a hash"); #pod } #pod #pod This is a horrible mess and because we don't know in advance how many #pod children's names there will be, we can't make a plan for our test anymore #pod (actually, we could but it would make things even more complicated). #pod #pod Test::Deep to the rescue. #pod #pod =head2 With Test::Deep #pod #pod my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); #pod cmp_deeply( #pod $person, #pod { #pod Name => $name_re, #pod Phone => re('^0d{6}$'), #pod ChildNames => array_each($name_re) #pod }, #pod "person ok" #pod ); #pod #pod This will do everything that the messy code above does and it will give a #pod sensible message telling you exactly what went wrong if it finds a part of #pod $person that doesn't match the pattern. C<re()> and C<array_each()> are #pod special function imported from Test::Deep. They create a marker that tells #pod Test::Deep that something different is happening here. Instead of just doing #pod a simple comparison and checking are two things exactly equal, it should do #pod something else. #pod #pod If a person was asked to check that 2 structures are equal, they could print #pod them both out and compare them line by line. The markers above are similar #pod to writing a note in red pen on one of the printouts telling the person that #pod for this piece of the structure, they should stop doing simple line by line #pod comparison and do something else. #pod #pod C<re($regex)> means that Test::Deep should check that the current piece of #pod data matches the regex in C<$regex>. C<array_each($struct)> means that #pod Test::Deep should expect the current piece of data to be an array and it #pod should check that every element of that array matches C<$struct>. #pod In this case, every element of C<< $person->{ChildNames} >> should look like a #pod name. If say the 3rd one didn't you would get an error message something #pod like #pod #pod Using Regexp on $data->{ChildNames}[3] #pod got : 'Queen John Paul Sartre' #pod expect : /^(Mr|Mrs|Miss) \w+ \w+$/ #pod #pod There are lots of other special comparisons available, see #pod L<SPECIAL COMPARISONS PROVIDED> below for the full list. #pod #pod =head2 Reusing structures #pod #pod Test::Deep is good for reusing test structures so you can do this #pod #pod my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); #pod my $person_cmp = { #pod Name => $name_re, #pod Phone => re('^0d{6}$'), #pod ChildNames => array_each($name_re) #pod }; #pod #pod cmp_deeply($person1, $person_cmp, "person ok"); #pod cmp_deeply($person2, $person_cmp, "person ok"); #pod cmp_deeply($person3, $person_cmp, "person ok"); #pod #pod You can even put $person_cmp in a module and let other people use it when #pod they are writing test scripts for modules that use your modules. #pod #pod To make things a little more difficult, lets change the person data #pod structure so that instead of a list of ChildNames, it contains a list of #pod hashes, one for each child. So in fact our person structure will contain #pod other person structures which may contain other person structures and so on. #pod This is easy to handle with Test::Deep because Test::Deep structures can #pod include themselves. Simply do #pod #pod my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); #pod my $person_cmp = { #pod Name => $name_re, #pod Phone => re('^0d{6}$'), #pod # note no mention of Children here #pod }; #pod #pod $person_cmp->{Children} = array_each($person_cmp); #pod #pod cmp_deeply($person, $person_cmp, "person ok"); #pod #pod This will now check that $person->{Children} is an array and that every #pod element of that array also matches C<$person_cmp>, this includes checking #pod that its children also match the same pattern and so on. #pod #pod =head2 Circular data structures #pod #pod A circular data structure is one which loops back on itself, you can make #pod one easily by doing #pod #pod my @b; #pod my @a = (1, 2, 3, \@b); #pod push(@b, \@a); #pod #pod now C<@a> contains a reference to be C<@b> and C<@b> contains a reference to #pod C<@a>. This causes problems if you have a program that wants to look inside #pod C<@a> and keep looking deeper and deeper at every level, it could get caught #pod in an infinite loop looking into C<@a> then C<@b> then C<@a> then C<@b> and #pod so on. #pod #pod Test::Deep avoids this problem so we can extend our example further by #pod saying that a person should also list their parents. #pod #pod my $name_re = re('^(Mr|Mrs|Miss) \w+ \w+$'); #pod my $person_cmp = { #pod Name => $name_re, #pod Phone => re('^0d{6}$'), #pod # note no mention of Children here #pod }; #pod #pod $person_cmp->{Children} = each_array($person_cmp); #pod $person_cmp->{Parents} = each_array($person_cmp); #pod #pod cmp_deeply($person, $person_cmp, "person ok"); #pod #pod So this will check that for each child C<$child> in C<< $person->{Children} >> #pod that the C<< $child->{Parents} >> matches C<$person_cmp> however it is smart #pod enough not to get caught in an infinite loop where it keeps bouncing between #pod the same Parent and Child. #pod #pod =head1 TERMINOLOGY #pod #pod C<cmp_deeply($got, $expected, $name)> takes 3 arguments. C<$got> is the #pod structure that you are checking, you must not include any special #pod comparisons in this structure or you will get a fatal error. C<$expected> #pod describes what Test::Deep will be looking for in $got. You can put special #pod comparisons in $expected if you want to. #pod #pod As Test::Deep descends through the 2 structures, it compares them one piece #pod at a time, so at any point in the process, Test::Deep is thinking about 2 #pod things - the current value from C<$got> and the current value from #pod C<$expected>. In the documentation, I call them C<$got_v> and C<exp_v> #pod respectively. #pod #pod =head1 COMPARISON FUNCTIONS #pod #pod =head3 cmp_deeply #pod #pod my $ok = cmp_deeply($got, $expected, $name) #pod #pod C<$got> is the result to be checked. C<$expected> is the structure against #pod which C<$got> will be check. C<$name> is the test name. #pod #pod This is the main comparison function, the others are just wrappers around #pod this. C<$got> and C<$expected> are compared recursively. Each value in #pod C<$expected> defines what's expected at the corresponding location in C<$got>. #pod Simple scalars are compared with C<eq>. References to structures like hashes #pod and arrays are compared recursively. #pod #pod Items in C<$expected>, though, can also represent complex tests that check for #pod numbers in a given range, hashes with at least a certain set of keys, a string #pod matching a regex, or many other things. #pod #pod See L</WHAT ARE SPECIAL COMPARISONS> for details. #pod #pod =head3 cmp_bag #pod #pod my $ok = cmp_bag(\@got, \@bag, $name) #pod #pod Is shorthand for cmp_deeply(\@got, bag(@bag), $name) #pod #pod I<n.b.>: Both arguments must be array refs. If they aren't an exception will be #pod thrown. #pod #pod =head3 cmp_set #pod #pod my $ok = cmp_set(\@got, \@set, $name) #pod #pod Is shorthand for cmp_deeply(\@got, set(@set), $name) #pod #pod =head3 cmp_methods #pod #pod my $ok = cmp_methods(\@got, \@methods, $name) #pod #pod Is shorthand for cmp_deeply(\@got, methods(@methods), $name) #pod #pod =head3 eq_deeply #pod #pod my $ok = eq_deeply($got, $expected) #pod #pod This is the same as cmp_deeply() except it just returns true or #pod false. It does not create diagnostics or talk to L<Test::Builder>, but #pod if you want to use it in a non-testing environment then you should #pod import it through L<Test::Deep::NoTest>. For example #pod #pod use Test::Deep::NoTest; #pod print "a equals b" unless eq_deeply($a, $b); #pod #pod otherwise the L<Test::Builder> framework will be loaded and testing messages #pod will be output when your program ends. #pod #pod =head3 cmp_details #pod #pod ($ok, $stack) = cmp_details($got, $expected) #pod #pod This behaves much like eq_deeply, but it additionally allows you to #pod produce diagnostics in case of failure by passing the value in C<$stack> #pod to C<deep_diag>. #pod #pod Do not make assumptions about the structure or content of C<$stack> and #pod do not use it if C<$ok> contains a true value. #pod #pod See L</USING TEST::DEEP WITH TEST::BUILDER> for example uses. #pod #pod =head1 SPECIAL COMPARISONS PROVIDED #pod #pod In the documentation below, C<$got_v> is used to indicate any given value #pod within the C<$got> structure. #pod #pod =head3 ignore #pod #pod cmp_deeply( $got, ignore() ); #pod #pod This makes Test::Deep skip tests on C<$got_v>. No matter what value C<$got_v> #pod has, Test::Deep will think it's correct. This is useful if some part of the #pod structure you are testing is very complicated and already tested elsewhere, #pod or if it is unpredictable. #pod #pod cmp_deeply( #pod $got, #pod { #pod name => 'John', #pod random => ignore(), #pod address => [ '5 A street', 'a town', 'a country' ], #pod } #pod ); #pod #pod is the equivalent of checking #pod #pod $got->{name} eq 'John'; #pod exists $got->{random}; #pod cmp_deeply($got->{address}, ['5 A street', 'a town', 'a country']); #pod #pod =head3 methods #pod #pod cmp_deeply( $got, methods(%hash) ); #pod #pod %hash is a hash of method call => expected value pairs. #pod #pod This lets you call methods on an object and check the result of each call. #pod The methods will be called in the order supplied. If you want to pass #pod arguments to the method you should wrap the method name and arguments in an #pod array reference. #pod #pod cmp_deeply( #pod $obj, #pod methods(name => "John", ["favourite", "food"] => "taco") #pod ); #pod #pod is roughly the equivalent of checking that #pod #pod $obj->name eq "John" #pod $obj->favourite("food") eq "taco" #pod #pod The methods will be called in the order you supply them and will be called #pod in scalar context. If you need to test methods called in list context then #pod you should use C<listmethods()>. #pod #pod B<NOTE> Just as in a normal test script, you need to be careful if the #pod methods you call have side effects like changing the object or other objects #pod in the structure. Although the order of the methods is fixed, the order of #pod some other tests is not so if C<$expected> is #pod #pod { #pod manager => methods(@manager_methods), #pod coder => methods(@coder_methods) #pod } #pod #pod there is no way to know which if manager and coder will be tested first. If #pod the methods you are testing depend on and alter global variables or if #pod manager and coder are the same object then you may run into problems. #pod #pod =head3 listmethods #pod #pod cmp_deeply( $got, listmethods(%hash) ); #pod #pod C<%hash> is a hash of pairs mapping method names to expected return values. #pod #pod This is almost identical to methods() except the methods are called in list #pod context instead of scalar context. This means that the expected return #pod values supplied must be in array references. #pod #pod cmp_deeply( #pod $obj, #pod listmethods( #pod name => [ "John" ], #pod ["favourites", "food"] => ["Mapo tofu", "Gongbao chicken"] #pod ) #pod ); #pod #pod is the equivalent of checking that #pod #pod cmp_deeply([$obj->name], ["John"]); #pod cmp_deeply([$obj->favourites("food")], ["Mapo tofu", "Gongbao chicken"]); #pod #pod The methods will be called in the order you supply them. #pod #pod B<NOTE> The same caveats apply as for methods(). #pod #pod =head3 shallow #pod #pod cmp_deeply( $got, shallow($thing) ); #pod #pod C<$thing> is a ref. #pod #pod This prevents Test::Deep from looking inside C<$thing>. It allows you to #pod check that C<$got_v> and C<$thing> are references to the same variable. So #pod #pod my @a = @b = (1, 2, 3); #pod cmp_deeply(\@a, \@b); #pod #pod will pass because C<@a> and C<@b> have the same elements however #pod #pod cmp_deeply(\@a, shallow(\@b)) #pod #pod will fail because although C<\@a> and C<\@b> both contain C<1, 2, 3> they are #pod references to different arrays. #pod #pod =head3 noclass #pod #pod cmp_deeply( $got, noclass($thing) ); #pod #pod C<$thing> is a structure to be compared against. #pod #pod This makes Test::Deep ignore the class of objects, so it just looks at the #pod data they contain. Class checking will be turned off until Test::Deep is #pod finished comparing C<$got_v> against C<$thing>. Once Test::Deep comes out of #pod C<$thing> it will go back to its previous setting for checking class. #pod #pod This can be useful when you want to check that objects have been #pod constructed correctly but you don't want to write lots of #pod C<bless>es. If C<@people> is an array of Person objects then #pod #pod cmp_deeply(\@people, [ #pod bless {name => 'John', phone => '555-5555'}, "Person", #pod bless {name => 'Anne', phone => '444-4444'}, "Person", #pod ]); #pod #pod can be replaced with #pod #pod cmp_deeply(\@people, noclass([ #pod {name => 'John', phone => '555-5555'}, #pod {name => 'Anne', phone => '444-4444'} #pod ])); #pod #pod However, this is testing so you should also check that the objects are #pod blessed correctly. You could use a map to bless all those hashes or you #pod could do a second test like #pod #pod cmp_deeply(\@people, array_each(isa("Person")); #pod #pod =head3 useclass #pod #pod cmp_deeply( $got, useclass($thing) ); #pod #pod This turns back on the class comparison while inside a C<noclass()>. #pod #pod cmp_deeply( #pod $got, #pod noclass( #pod [ #pod useclass( $object ) #pod ] #pod ) #pod ) #pod #pod In this example the class of the array reference in C<$got> is ignored but #pod the class of C<$object> is checked, as is the class of everything inside #pod C<$object>. #pod #pod =head3 re #pod #pod cmp_deeply( $got, re($regexp, $capture_data, $flags) ); #pod #pod C<$regexp> is either a regular expression reference produced with C<qr/.../> #pod or a string which will be used to construct a regular expression. #pod #pod C<$capture_data> is optional and is used to check the strings captured by an #pod regex. This should can be an array ref or a Test::Deep comparator that works #pod on array refs. #pod #pod C<$flags> is an optional string which controls whether the regex runs as a #pod global match. If C<$flags> is "g" then the regex will run as C<m/$regexp/g>. #pod #pod Without C<$capture_data>, this simply compares C<$got_v> with the regular #pod expression provided. So #pod #pod cmp_deeply($got, [ re("ferg") ]) #pod #pod is the equivalent of #pod #pod $got->[0] =~ /ferg/ #pod #pod With C<$capture_data>, #pod #pod cmp_deeply($got, [re($regex, $capture_data)]) #pod #pod is the equivalent of #pod #pod my @data = $got->[0] =~ /$regex/; #pod cmp_deeply(\@data, $capture_data); #pod #pod So you can do something simple like #pod #pod cmp_deeply($got, re(qr/(\d\d)(\w\w)/, [25, "ab" ])) #pod #pod to check that C<(\d\d)> was 25 and C<(\w\w)> was "ab" but you can also use #pod Test::Deep objects to do more complex testing of the captured values #pod #pod cmp_deeply( #pod "cat=2,dog=67,sheep=3,goat=2,dog=5", #pod re( #pod qr/(\D+)=\d+,?/, #pod set(qw( cat sheep dog )), #pod "g" #pod ), #pod ); #pod #pod here, the regex will match the string and will capture the animal names and #pod check that they match the specified set, in this case it will fail, #pod complaining that "goat" is not in the set. #pod #pod =head3 all #pod #pod cmp_deeply( $got, all(@expecteds) ); #pod #pod C<@expecteds> is an array of expected structures. #pod #pod This allows you to compare data against multiple expected results and make #pod sure each of them matches. #pod #pod cmp_deeply($got, all(isa("Person"), methods(name => 'John'))) #pod #pod is equivalent to #pod #pod $got->isa("Person") #pod $got->name eq 'John' #pod #pod If either test fails then the whole thing is considered a fail. This is a #pod short-circuit test, the testing is stopped after the first failure, although #pod in the future it may complete all tests so that diagnostics can be output #pod for all failures. When reporting failure, the parts are counted from 1. #pod #pod Thanks to the magic of overloading, you can write #pod #pod any( re("^wi"), all(isa("Person"), methods(name => 'John')) ) #pod #pod as #pod #pod re("^wi") | isa("Person") & methods(name => 'John') #pod #pod Note B<single> C<|> not double, as C<||> cannot be overloaded. This will #pod only work when there is a special comparison involved. If you write #pod #pod "john" | "anne" | "robert" #pod #pod Perl will turn this into #pod #pod "{onort" #pod #pod which is presumably not what you wanted. This is because perl ors them #pod together as strings before Test::Deep gets a chance to do any overload #pod tricks. #pod #pod =head3 any #pod #pod cmp_deeply( $got, any(@expecteds) ); #pod #pod C<@expecteds> is an array of expected structures. #pod #pod This can be used to compare data against multiple expected results and make #pod sure that at least one of them matches. This is a short-circuit test so if #pod a test passes then none of the tests after that will be attempted. #pod #pod You can also use overloading with C<|> similarly to all(). #pod #pod =head3 Isa #pod #pod cmp_deeply( $got, Isa($class) ); #pod #pod =head3 isa #pod #pod cmp_deeply( $got, isa($class) ); #pod #pod C<$class> is a class name. #pod #pod This uses C<UNIVERSAL::isa()> to check that C<$got_v> is blessed into the #pod class C<$class>. #pod #pod B<NOTE:> C<Isa()> does exactly as documented here, but C<isa()> is slightly #pod different. If C<isa()> is called with 1 argument it falls through to #pod C<Isa()>. If C<isa()> called with 2 arguments, it falls through to #pod C<UNIVERSAL::isa>. This is to prevent breakage when you import C<isa()> into #pod a package that is used as a class. Without this, anyone calling #pod C<Class-E<gt>isa($other_class)> would get the wrong answer. This is a hack #pod to patch over the fact that C<isa> is exported by default. #pod #pod =head3 obj_isa #pod #pod cmp_deeply( $got, obj_isa($class) ); #pod #pod This test accepts only objects that are instances of C<$class> or a subclass. #pod Unlike the C<Isa> test, this test will never accept class names. #pod #pod =head3 array_each #pod #pod cmp_deeply( \@got, array_each($thing) ); #pod #pod C<$thing> is a structure to be compared against. #pod #pod <$got_v> must be an array reference. Each element of it will be compared to #pod C<$thing>. This is useful when you have an array of similar things, for example #pod objects of a known type and you don't want to have to repeat the same test #pod for each one. #pod #pod my $common_tests = all( #pod isa("MyFile"), #pod methods( #pod handle => isa("IO::Handle") #pod filename => re("^/home/ted/tmp"), #pod ) #pod ); #pod #pod cmp_deeply($got, array_each($common_tests)); #pod #pod is similar to #pod #pod foreach my $got_v (@$got) { #pod cmp_deeply($got_v, $common_tests) #pod } #pod #pod Except it will not explode if C<$got> is not an array reference. It will #pod check that each of the objects in C<@$got> is a MyFile and that each one #pod gives the correct results for its methods. #pod #pod You could go further, if for example there were 3 files and you knew the #pod size of each one you could do this #pod #pod cmp_deeply( #pod $got, #pod all( #pod array_each($common_tests), #pod [ #pod methods(size => 1000), #pod methods(size => 200), #pod methods(size => 20) #pod ] #pod ) #pod ) #pod cmp_deeply($got, array_each($structure)); #pod #pod =head3 hash_each #pod #pod cmp_deeply( \%got, hash_each($thing) ); #pod #pod This test behaves like C<array_each> (see above) but tests that each hash #pod value passes its tests. #pod #pod =head3 str #pod #pod cmp_deeply( $got, str($string) ); #pod #pod $string is a string. #pod #pod This will stringify C<$got_v> and compare it to C<$string> using C<eq>, even #pod if C<$got_v> is a ref. It is useful for checking the stringified value of an #pod overloaded reference. #pod #pod =head3 num #pod #pod cmp_deeply( $got, num($number, $tolerance) ); #pod #pod C<$number> is a number. #pod #pod C<$tolerance> is an optional number. #pod #pod This will add 0 to C<$got_v> and check if it's numerically equal to #pod C<$number>, even if C<$got_v> is a ref. It is useful for checking the #pod numerical value of an overloaded reference. If C<$tolerance> is supplied #pod then this will check that C<$got_v> and C<$exp_v> are less than #pod C<$tolerance> apart. This is useful when comparing floating point numbers as #pod rounding errors can make it hard or impossible for C<$got_v> to be exactly #pod equal to C<$exp_v>. When C<$tolerance> is supplied, the test passes if #pod C<abs($got_v - $exp_v) <= $tolerance>. #pod #pod B<Note> in Perl, C<"12blah" == 12> because Perl will be smart and convert #pod "12blah" into 12. You may not want this. There was a strict mode but that is #pod now gone. A "looks like a number" test will replace it soon. Until then you #pod can usually just use the string() comparison to be more strict. This will #pod work fine for almost all situations, however it will not work when <$got_v> #pod is an overloaded value who's string and numerical values differ. #pod #pod =head3 bool, true, false #pod #pod cmp_deeply( $got, bool($value) ); #pod cmp_deeply( $got, true ); #pod cmp_deeply( $got, false ); #pod #pod C<$value> is anything you like but it's probably best to use 0 or 1 #pod #pod This will check that C<$got_v> and C<$value> have the same truth value, that #pod is they will give the same result when used in boolean context, like in an #pod C<if()> statement. #pod #pod B<Note:> C<true> and C<false> are only imported by special request. #pod #pod =head3 code #pod #pod cmp_deeply( $got, code(\&subref) ); #pod #pod C<\&subref> is a reference to a subroutine which will be passed a single #pod argument, it then should return a true or false and possibly a string #pod #pod This will pass C<$got_v> to the subroutine which returns true or false to #pod indicate a pass or fail. Fails can be accompanied by a diagnostic string #pod which gives an explanation of why it's a fail. #pod #pod sub check_name #pod { #pod my $name = shift; #pod if ($boss->likes($name)) #pod { #pod return 1; #pod } #pod else #pod { #pod return (0, "the boss doesn't like your name"); #pod } #pod } #pod #pod cmp_deeply("Brian", code(\&check_name)); #pod #pod =head2 SET COMPARISONS #pod #pod Set comparisons give special semantics to array comparisons: #pod #pod =over 4 #pod #pod =item * The order of items in a set is irrelevant #pod #pod =item * The presence of duplicate items in a set is ignored. #pod #pod =back #pod #pod As such, in any set comparison, the following arrays are equal: #pod #pod [ 1, 2 ] #pod [ 1, 1, 2 ] #pod [ 1, 2, 1 ] #pod [ 2, 1, 1 ] #pod [ 1, 1, 2 ] #pod #pod All are interpreted by C<set> semantics as if the set was only specified as: #pod #pod [ 1, 2 ] #pod #pod All C<set> functions return an object which can have additional items added to #pod it: #pod #pod my $set = set( 1, 2 ); #pod $set->add(1, 3, 1 ); # Set is now ( 1, 2, 3 ) #pod #pod Special care must be taken when using special comparisons within sets. See #pod L</SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS> for details. #pod #pod =head3 set #pod #pod cmp_deeply( \@got, set(@elements) ); #pod #pod This does a set comparison, that is, it compares two arrays but ignores the #pod order of the elements and it ignores duplicate elements, but ensures that all #pod items in C<@elements> will be in C<$got> and all items in C<$got> will be #pod in C<@elements>. #pod #pod So the following tests will be passes, and will be equivalent: #pod #pod cmp_deeply([1, 2, 2, 3], set(3, 2, 1, 1)); #pod cmp_deeply([1, 2, 3], set(3, 2, 1)); #pod #pod =head3 supersetof #pod #pod cmp_deeply( \@got, supersetof(@elements) ); #pod #pod This function works much like L<< C<set>|/set >>, and performs a set comparison #pod of C<$got_v> with the elements of C<@elements>. #pod #pod C<supersetof> is however slightly relaxed, such that C<$got> may contain things #pod not in C<@elements>, but must at least contain all C<@elements>. #pod #pod These two statements are equivalent, and will be passes: #pod #pod cmp_deeply([1,2,3,3,4,5], supersetof(2,2,3)); #pod cmp_deeply([1,2,3,4,5], supersetof(2,3)); #pod #pod But these will be failures: #pod #pod cmp_deeply([1,2,3,4,5], supersetof(2,3,6)); # 6 not in superset #pod cmp_deeply([1], supersetof(1,2)); # 2 not in superset #pod #pod =head3 subsetof #pod #pod cmp_deeply( \@got, subsetof(@elements) ); #pod #pod This function works much like L<< C<set>|/set >>, and performs a set comparison #pod of C<$got_v> with the elements of C<@elements>. #pod #pod This is the inverse of C<supersetof>, which expects all unique elements found #pod in C<$got_v> must be in C<@elements>. #pod #pod cmp_deeply([1,2,4,5], subsetof(2,3,3) ) # Fail: 1,4 & 5 extra #pod cmp_deeply([2,3,3], subsetof(1,2,4,5) ) # Fail: 3 extra #pod cmp_deeply([2,3,3], subsetof(1,2,4,5,3)) # Pass #pod #pod =head3 none #pod #pod cmp_deeply( $got, none(@elements) ); #pod #pod @elements is an array of elements, wherein no elements in C<@elements> may #pod be equal to C<$got_v>. #pod #pod =head3 noneof #pod #pod cmp_deeply( \@got, noneof(@elements) ); #pod #pod @elements is an array of elements, wherein no elements in C<@elements> may be #pod found in C<$got_v>. #pod #pod For example: #pod #pod # Got has no 1, no 2, and no 3 #pod cmp_deeply( [1], noneof( 1, 2, 3 ) ); # fail #pod cmp_deeply( [5], noneof( 1, 2, 3 ) ); # pass #pod #pod =head2 BAG COMPARISONS #pod #pod Bag comparisons give special semantics to array comparisons, that are similar #pod to L<< set comparisons|/SET COMPARISONS >>, but slightly different. #pod #pod =over 4 #pod #pod =item * The order of items in a bag is irrelevant #pod #pod =item * The presence of duplicate items in a bag is B<PRESERVED> #pod #pod =back #pod #pod As such, in any bag comparison, the following arrays are equal: #pod #pod [ 1, 1, 2 ] #pod [ 1, 2, 1 ] #pod [ 2, 1, 1 ] #pod [ 1, 1, 2 ] #pod #pod However, they are B<NOT> equal to any of the following: #pod #pod [ 1, 2 ] #pod [ 1, 2, 2 ] #pod [ 1, 1, 1, 2 ] #pod #pod All C<bag> functions return an object which can have additional items added to #pod it: #pod #pod my $bag = bag( 1, 2 ); #pod $bag->add(1, 3, 1 ); # Bag is now ( 1, 1, 1, 2, 3 ) #pod #pod Special care must be taken when using special comparisons within bags. See #pod L</SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS> for details. #pod #pod =head3 bag #pod #pod cmp_deeply( \@got, bag(@elements) ); #pod #pod This does an order-insensitive bag comparison between C<$got> and #pod C<@elements>, ensuring that: #pod #pod =over 4 #pod #pod =item each item in C<@elements> is found in C<$got> #pod #pod =item the number of times a C<$expected_v> is found in C<@elements> is #pod reflected in C<$got> #pod #pod =item no items are found in C<$got> other than those in C<@elements>. #pod #pod =back #pod #pod As such, the following are passes, and are equivalent to each other: #pod #pod cmp_deeply([1, 2, 2], bag(2, 2, 1)) #pod cmp_deeply([2, 1, 2], bag(2, 2, 1)) #pod cmp_deeply([2, 2, 1], bag(2, 2, 1)) #pod #pod But the following are failures: #pod #pod cmp_deeply([1, 2, 2], bag(2, 2, 1, 1)) # Not enough 1's in Got #pod cmp_deeply([1, 2, 2, 1], bag(2, 2, 1) ) # Too many 1's in Got #pod #pod =head3 superbagof #pod #pod cmp_deeply( \@got, superbagof( @elements ) ); #pod #pod This function works much like L<< C<bag>|/bag >>, and performs a bag comparison #pod of C<$got_v> with the elements of C<@elements>. #pod #pod C<superbagof> is however slightly relaxed, such that C<$got> may contain things #pod not in C<@elements>, but must at least contain all C<@elements>. #pod #pod So: #pod #pod # pass #pod cmp_deeply( [1, 1, 2], superbagof( 1 ) ); #pod #pod # fail: not enough 1's in superbag #pod cmp_deeply( [1, 1, 2], superbagof( 1, 1, 1 )); #pod #pod =head3 subbagof #pod #pod cmp_deeply( \@got, subbagof(@elements) ); #pod #pod This function works much like L<< C<bag>|/bag >>, and performs a bag comparison #pod of C<$got_v> with the elements of C<@elements>. #pod #pod This is the inverse of C<superbagof>, and expects all elements in C<$got> to #pod be in C<@elements>, while allowing items to exist in C<@elements> that are not #pod in C<$got> #pod #pod # pass #pod cmp_deeply( [1], subbagof( 1, 1, 2 ) ); #pod #pod # fail: too many 1's in subbag #pod cmp_deeply( [1, 1, 1], subbagof( 1, 1, 2 ) ); #pod #pod =head2 HASH COMPARISONS #pod #pod Typically, if you're doing simple hash comparisons, #pod #pod cmp_deeply( \%got, \%expected ) #pod #pod is sufficient. C<cmp_deeply> will ensure C<%got> and C<%hash> have identical #pod keys, and each key from either has the same corresponding value. #pod #pod =head3 superhashof #pod #pod cmp_deeply( \%got, superhashof(\%hash) ); #pod #pod This will check that the hash C<%$got> is a "super-hash" of C<%hash>. That #pod is that all the key and value pairs in C<%hash> appear in C<%$got> but #pod C<%$got> can have extra ones also. #pod #pod For example #pod #pod cmp_deeply({a => 1, b => 2}, superhashof({a => 1})) #pod #pod will pass but #pod #pod cmp_deeply({a => 1, b => 2}, superhashof({a => 1, c => 3})) #pod #pod will fail. #pod #pod =head3 subhashof #pod #pod cmp_deeply( \%got, subhashof(\%hash) ); #pod #pod This will check that the hash C<%$got> is a "sub-hash" of C<%hash>. That is #pod that all the key and value pairs in C<%$got> also appear in C<%hash>. #pod #pod For example #pod #pod cmp_deeply({a => 1}, subhashof({a => 1, b => 2})) #pod #pod will pass but #pod #pod cmp_deeply({a => 1, c => 3}, subhashof({a => 1, b => 2})) #pod #pod will fail. #pod #pod =head1 DIAGNOSTIC FUNCTIONS #pod #pod =head3 deep_diag #pod #pod my $reason = deep_diag($stack); #pod #pod C<$stack> is a value returned by cmp_details. Do not call this function #pod if cmp_details returned a true value for C<$ok>. #pod #pod C<deep_diag()> returns a human readable string describing how the #pod comparison failed. #pod #pod =head1 ANOTHER EXAMPLE #pod #pod You've written a module to handle people and their film interests. Say you #pod have a function that returns an array of people from a query, each person is #pod a hash with 2 keys: Name and Age and the array is sorted by Name. You can do #pod #pod cmp_deeply( #pod $result, #pod [ #pod {Name => 'Anne', Age => 26}, #pod {Name => "Bill", Age => 47} #pod {Name => 'John', Age => 25}, #pod ] #pod ); #pod #pod Soon after, your query function changes and all the results now have an ID #pod field. Now your test is failing again because you left out ID from each of #pod the hashes. The problem is that the IDs are generated by the database and #pod you have no way of knowing what each person's ID is. With Test::Deep you can #pod change your query to #pod #pod cmp_deeply( #pod $result, #pod [ #pod {Name => 'John', Age => 25, ID => ignore()}, #pod {Name => 'Anne', Age => 26, ID => ignore()}, #pod {Name => "Bill", Age => 47, ID => ignore()} #pod ] #pod ); #pod #pod But your test still fails. Now, because you're using a database, you no #pod longer know what order the people will appear in. You could add a sort into #pod the database query but that could slow down your application. Instead you #pod can get Test::Deep to ignore the order of the array by doing a bag #pod comparison instead. #pod #pod cmp_deeply( #pod $result, #pod bag( #pod {Name => 'John', Age => 25, ID => ignore()}, #pod {Name => 'Anne', Age => 26, ID => ignore()}, #pod {Name => "Bill", Age => 47, ID => ignore()} #pod ) #pod ); #pod #pod Finally person gets even more complicated and includes a new field called #pod Movies, this is a list of movies that the person has seen recently, again #pod these movies could also come back in any order so we need a bag inside our #pod other bag comparison, giving us something like #pod #pod cmp_deeply( #pod $result, #pod bag( #pod {Name => 'John', Age => 25, ID => ignore(), Movies => bag(...)}, #pod {Name => 'Anne', Age => 26, ID => ignore(), Movies => bag(...)}, #pod {Name => "Bill", Age => 47, ID => ignore(), Movies => bag(...)} #pod ) #pod ); #pod #pod =head1 USING TEST::DEEP WITH TEST::BUILDER #pod #pod Combining C<cmp_details> and C<deep_diag> makes it possible to use #pod Test::Deep in your own test classes. #pod #pod In a L<Test::Builder> subclass, create a test method in the following #pod form: #pod #pod sub behaves_ok { #pod my $self = shift; #pod my $expected = shift; #pod my $test_name = shift; #pod #pod my $got = do_the_important_work_here(); #pod #pod my ($ok, $stack) = cmp_details($got, $expected); #pod unless ($Test->ok($ok, $test_name)) { #pod my $diag = deep_diag($stack); #pod $Test->diag($diag); #pod } #pod } #pod #pod As the subclass defines a test class, not tests themselves, make sure it #pod uses L<Test::Deep::NoTest>, not C<Test::Deep> itself. #pod #pod =head1 LIMITATIONS #pod #pod Currently any CODE, GLOB or IO refs will be compared using shallow(), which #pod means only their memory addresses are compared. #pod #pod =head1 BUGS #pod #pod There is a bug in set and bag compare to do with competing SCs. It only #pod occurs when you put certain special comparisons inside bag or set #pod comparisons you don't need to worry about it. The full details are in the #pod C<bag()> docs. It will be fixed in an upcoming version. #pod #pod =head1 CAVEATS #pod #pod =head2 SPECIAL CARE WITH SPECIAL COMPARISONS IN SETS AND BAGS #pod #pod If you use certain special comparisons within a bag or set comparison there is #pod a danger that a test will fail when it should have passed. It can only happen #pod if two or more special comparisons in the bag are competing to match elements. #pod Consider this comparison #pod #pod cmp_deeply(['furry', 'furball'], bag(re("^fur"), re("furb"))) #pod #pod There are two things that could happen, hopefully C<re("^fur")> is paired with #pod "furry" and C<re("^furb")> is paired with "furb" and everything is fine but it #pod could happen that C<re("^fur")> is paired with "furball" and then C<re("^furb")> #pod cannot find a match and so the test fails. Examples of other competing #pod comparisons are C<bag(1, 2, 2)> vs C<set(1, 2)> and #pod C<< methods(m1 => "v1", m2 => "v2") >> vs C<< methods(m1 => "v1") >> #pod #pod This problem is could be solved by using a slower and more complicated #pod algorithm for set and bag matching. Something for the future... #pod #pod =head1 WHAT ARE SPECIAL COMPARISONS? #pod #pod A special comparison (SC) is simply an object that inherits from #pod Test::Deep::Cmp. Whenever C<$expected_v> is an SC then instead of checking #pod C<$got_v eq $expected_v>, we pass control over to the SC and let it do its #pod thing. #pod #pod Test::Deep exports lots of SC constructors, to make it easy for you to use #pod them in your test scripts. For example is C<re("hello")> is just a handy way #pod of creating a Test::Deep::Regexp object that will match any string containing #pod "hello". So #pod #pod cmp_deeply([ 'a', 'b', 'hello world'], ['a', 'b', re("^hello")]); #pod #pod will check C<'a' eq 'a'>, C<'b' eq 'b'> but when it comes to comparing #pod C<'hello world'> and C<re("^hello")> it will see that #pod $expected_v is an SC and so will pass control to the Test::Deep::Regexp class #pod by do something like C<< $expected_v->descend($got_v) >>. The C<descend()> #pod method should just return true or false. #pod #pod This gives you enough to write your own SCs but I haven't documented how #pod diagnostics works because it's about to get an overhaul (theoretically). #pod #pod =head1 EXPORTS #pod #pod By default, Test::Deep will export everything in its C<v0> tag, as if you had #pod written: #pod #pod use Test::Deep ':v0'; #pod #pod Those things are: #pod #pod all any array array_each arrayelementsonly arraylength arraylengthonly bag #pod blessed bool cmp_bag cmp_deeply cmp_methods cmp_set code eq_deeply hash #pod hash_each hashkeys hashkeysonly ignore Isa isa listmethods methods noclass #pod none noneof num obj_isa re reftype regexpmatches regexponly regexpref #pod regexprefonly scalarrefonly scalref set shallow str subbagof subhashof #pod subsetof superbagof superhashof supersetof useclass #pod #pod A slightly better set of exports is the C<v1> set. It's all the same things, #pod with the exception of C<Isa> and C<blessed>. If you want to import #pod "everything", you probably want to C<< use Test::Deep ':V1'; >>. #pod #pod There's another magic export group: C<:preload>. If that is specified, all of #pod the Test::Deep plugins will be loaded immediately instead of lazily. #pod #pod =head1 SEE ALSO #pod #pod L<Test::More> #pod #pod =head1 THANKS #pod #pod Thanks to Michael G Schwern for Test::More's is_deeply function which inspired #pod this library. #pod #pod =cut PK � �[� c�[ [ lib/Test/Deep/ArrayEach.pmnu ��6�$ use strict; use warnings; package Test::Deep::ArrayEach 1.204; use Test::Deep::Cmp; use Scalar::Util (); sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; return unless ref $got && Scalar::Util::reftype($got) eq 'ARRAY'; my $exp = [ ($self->{val}) x @$got ]; return Test::Deep::descend($got, $exp); } sub renderExp { my $self = shift; my $exp = shift; return '[ ' . $self->SUPER::renderExp($self->{val}) . ', ... ]'; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ArrayEach =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[O�ao` ` lib/Test/Deep/RegexpOnly.pmnu ��6�$ use strict; use warnings; package Test::Deep::RegexpOnly 1.204; use Test::Deep::Cmp; use Scalar::Util qw( blessed ); sub init { my $self = shift; my $val = shift; $val = ref $val ? $val : qr/$val/; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $re = $self->{val}; return $got =~ $self->{val} ? 1 : 0; } sub diag_message { my $self = shift; my $where = shift; return "Using Regexp on $where"; } sub renderExp { my $self = shift; return "$self->{val}"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::RegexpOnly =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[����� � lib/Test/Deep/Shallow.pmnu ��6�$ use strict; use warnings; package Test::Deep::Shallow 1.204; use Test::Deep::Cmp; use Scalar::Util qw( refaddr ); sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; my $ok; if (!defined $got and !defined $exp) { $ok = 1; } elsif (defined $got xor defined $exp) { $ok = 0; } elsif (ref $got and ref $exp) { $ok = refaddr($got) == refaddr($exp); } elsif (ref $got xor ref $exp) { $ok = 0; } else { $ok = $got eq $exp; } return $ok; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Shallow =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[o�v�� � lib/Test/Deep/Any.pmnu ��6�$ use strict; use warnings; package Test::Deep::Any 1.204; use Scalar::Util (); use Test::Deep::Cmp; sub init { my $self = shift; my @list = map { (Scalar::Util::blessed($_) && $_->isa('Test::Deep::Any')) ? @{ $_->{val} } : $_ } @_; $self->{val} = \@list; } sub descend { my $self = shift; my $got = shift; foreach my $cmp (@{$self->{val}}) { return 1 if Test::Deep::eq_deeply_cache($got, $cmp); } return 0; } sub renderExp { my $self = shift; my @expect = map {; Test::Deep::wrap($_) } @{ $self->{val} }; my $things = join(", ", map {$_->renderExp} @expect); return "Any of ( $things )"; } sub diagnostics { my $self = shift; my ($where, $last) = @_; my $got = $self->renderGot($last->{got}); my $exp = $self->renderExp; my $diag = <<EOM; Comparing $where with Any got : $got expected : $exp EOM $diag =~ s/\n+$/\n/; return $diag; } 4; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Any =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[E,]�j j lib/Test/Deep/HashKeysOnly.pmnu ��6�$ use strict; use warnings; package Test::Deep::HashKeysOnly 1.204; use Test::Deep::Ref; sub init { my $self = shift; my %keys; @keys{@_} = (); $self->{val} = \%keys; $self->{keys} = [sort @_]; } sub descend { my $self = shift; my $hash = shift; my $data = $self->data; my $exp = $self->{val}; my %got; @got{keys %$hash} = (); my @missing; my @extra; while (my ($key, $value) = each %$exp) { if (exists $got{$key}) { delete $got{$key}; } else { push(@missing, $key); } } my @diags; if (@missing and (not $self->ignoreMissing)) { push(@diags, "Missing: ".nice_list(\@missing)); } if (%got and (not $self->ignoreExtra)) { push(@diags, "Extra: ".nice_list([keys %got])); } if (@diags) { $data->{diag} = join("\n", @diags); return 0; } return 1; } sub diagnostics { my $self = shift; my ($where, $last) = @_; my $type = $self->{IgnoreDupes} ? "Set" : "Bag"; my $error = $last->{diag}; my $diag = <<EOM; Comparing hash keys of $where $error EOM return $diag; } sub nice_list { my $list = shift; return join(", ", (map {"'$_'"} sort @$list), ); } sub ignoreMissing { return 0; } sub ignoreExtra { return 0; } package Test::Deep::SuperHashKeysOnly 1.204; use base 'Test::Deep::HashKeysOnly'; sub ignoreMissing { return 0; } sub ignoreExtra { return 1; } package Test::Deep::SubHashKeysOnly 1.204; use base 'Test::Deep::HashKeysOnly'; sub ignoreMissing { return 1; } sub ignoreExtra { return 0; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::HashKeysOnly =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[��� � lib/Test/Deep/Hash.pmnu ��6�$ use strict; use warnings; package Test::Deep::Hash 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; my $data = $self->data; return 0 unless Test::Deep::descend($got, $self->hash_keys($exp)); return 0 unless $self->test_class($got); return Test::Deep::descend($got, $self->hash_elements($exp)); } sub hash_elements { require Test::Deep::HashElements; my $self = shift; return Test::Deep::HashElements->new(@_); } sub hash_keys { require Test::Deep::HashKeys; my $self = shift; my $exp = shift; return Test::Deep::HashKeys->new(keys %$exp); } sub reset_arrow { return 0; } package Test::Deep::SuperHash 1.204; use base 'Test::Deep::Hash'; sub hash_elements { require Test::Deep::HashElements; my $self = shift; return Test::Deep::SuperHashElements->new(@_); } sub hash_keys { require Test::Deep::HashKeys; my $self = shift; my $exp = shift; return Test::Deep::SuperHashKeys->new(keys %$exp); } package Test::Deep::SubHash 1.204; use base 'Test::Deep::Hash'; sub hash_elements { require Test::Deep::HashElements; my $self = shift; return Test::Deep::SubHashElements->new(@_); } sub hash_keys { require Test::Deep::HashKeys; my $self = shift; my $exp = shift; return Test::Deep::SubHashKeys->new(keys %$exp); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Hash =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[?�|� � lib/Test/Deep/Number.pmnu ��6�$ use strict; use warnings; package Test::Deep::Number 1.204; use Test::Deep::Cmp; use Scalar::Util; sub init { my $self = shift; $self->{val} = shift(@_) + 0; $self->{tolerance} = shift; } sub descend { my $self = shift; my $got = shift; $self->data->{got_string} = $got; { no warnings 'numeric'; $got += 0; } $self->data->{got} = $got; if (defined(my $tolerance = $self->{tolerance})) { return abs($got - $self->{val}) <= $tolerance; } else { return $got == $self->{val}; } } sub diag_message { my $self = shift; my $where = shift; return "Comparing $where as a number"; } sub renderGot { my $self = shift; my $val = shift; my $got_string = $self->data->{got_string}; if ("$val" ne "$got_string") { $got_string = $self->SUPER::renderGot($got_string); return "$val ($got_string)" } else { return $val; } } sub renderExp { my $self = shift; my $exp = $self->{val}; if (defined(my $tolerance = $self->{tolerance})) { return "$exp +/- $tolerance"; } else { return $exp; } } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Number =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[[�Ae� � lib/Test/Deep/MM.pmnu ��6�$ use strict; use warnings; package Test::Deep::MM 1.204; sub import { my $self = shift; my ($pkg) = caller(); my $mpkg = $pkg."::Methods"; foreach my $attr (@_) { if ($attr =~ /^[a-z]/) { no strict 'refs'; *{$mpkg."::$attr"} = \&{$attr}; } else { my $get_name = $mpkg."::get$attr"; my $set_name = $mpkg."::set$attr"; my $get_sub = sub { return $_[0]->{$attr}; }; my $set_sub = sub { return $_[0]->{$attr} = $_[1]; }; { no strict 'refs'; *$get_name = $get_sub; *$set_name = $set_sub; push(@{$pkg."::ISA"}, $mpkg); } } } } sub new { my $pkg = shift; my $self = bless {}, $pkg; $self->init(@_); return $self; } sub init { my $self = shift; while (@_) { my $name = shift || confess("No name"); my $method = "set$name"; $self->$method(shift); } } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::MM =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[��� � lib/Test/Deep/RegexpRef.pmnu ��6�$ use strict; use warnings; package Test::Deep::RegexpRef 1.204; use Test::Deep::Ref; use Test::Deep::RegexpVersion; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; if ($Test::Deep::RegexpVersion::OldStyle) { return 0 unless $self->test_class($got, "Regexp"); return 0 unless $self->test_reftype($got, "SCALAR"); } else { return 0 unless $self->test_reftype($got, "REGEXP"); } return Test::Deep::descend($got, Test::Deep::regexprefonly($exp)); } sub renderGot { my $self = shift; return shift().""; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::RegexpRef =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[ν� " lib/Test/Deep/ArrayElementsOnly.pmnu ��6�$ use strict; use warnings; package Test::Deep::ArrayElementsOnly 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; my $data = $self->data; for my $i (0..$#{$exp}) { $data->{index} = $i; my $got_elem = $got->[$i]; my $exp_elem = $exp->[$i]; return 0 unless Test::Deep::descend($got_elem, $exp_elem) } return 1; } sub render_stack { my $self = shift; my ($var, $data) = @_; $var .= "->" unless $Test::Deep::Stack->incArrow; $var .= "[$data->{index}]"; return $var; } sub reset_arrow { return 0; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ArrayElementsOnly =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�# כ � lib/Test/Deep/HashEach.pmnu ��6�$ use strict; use warnings; package Test::Deep::HashEach 1.204; use Test::Deep::Cmp; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my %exp; @exp{keys %$got} = ($self->{val}) x (keys %$got); return Test::Deep::descend($got, \%exp); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::HashEach =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[��n] ] lib/Test/Deep/HashElements.pmnu ��6�$ use strict; use warnings; package Test::Deep::HashElements 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; my $data = $self->data; my $master = $self->getMaster($got, $exp); foreach my $key (sort keys %$master) { $data->{index} = $key; my $got_elem = exists $got->{$key} ? $got->{$key} : $Test::Deep::DNE; my $exp_elem = exists $exp->{$key} ? $exp->{$key} : $Test::Deep::DNE; next if Test::Deep::descend($got_elem, $exp_elem); return 0; } return 1; } sub getMaster { my $self = shift; my ($got, $exp) = @_; return keys %$got > keys %$exp ? $got : $exp; } sub render_stack { my $self = shift; my ($var, $data) = @_; $var .= "->" unless $Test::Deep::Stack->incArrow; $var .= '{"'.quotemeta($data->{index}).'"}'; return $var; } sub reset_arrow { return 0; } package Test::Deep::SuperHashElements 1.204; use base 'Test::Deep::HashElements'; sub getMaster { my $self = shift; my ($got, $exp) = @_; return $exp; } package Test::Deep::SubHashElements 1.204; use base 'Test::Deep::HashElements'; sub getMaster { my $self = shift; my ($got, $exp) = @_; return $got; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::HashElements =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[e��,� � lib/Test/Deep/RegexpMatches.pmnu ��6�$ use strict; use warnings; package Test::Deep::RegexpMatches 1.204; use Test::Deep::Array; use base 'Test::Deep::Array'; use Scalar::Util qw( blessed ); sub init { my $self = shift; my $val = shift; $val = Test::Deep::array($val) unless blessed($val) and $val->isa("Test::Deep::Cmp"); $self->{val} = $val; $self->{regex} = shift; } sub descend { my $self = shift; my $got = shift; return Test::Deep::descend($got, $self->{val}); } sub render_stack { my $self = shift; my $stack = shift; $stack = "[$stack =~ $self->{regex}]"; return $stack; # return $self->SUPER::render_stack($stack); } sub reset_arrow { return 1; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::RegexpMatches =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[?5� lib/Test/Deep/All.pmnu ��6�$ use strict; use warnings; package Test::Deep::All 1.204; use Scalar::Util (); use Test::Deep::Cmp; sub init { my $self = shift; my @list = map { (Scalar::Util::blessed($_) && $_->isa('Test::Deep::All')) ? @{ $_->{val} } : $_ } @_; $self->{val} = \@list; } sub descend { my $self = shift; my $got = shift; my $data = $self->data; my $index = 1; foreach my $cmp (@{$self->{val}}) { $data->{index} = $index; $index++; next if Test::Deep::descend($got, $cmp); return 0 } return 1; } sub render_stack { my $self = shift; my $var = shift; my $data = shift; my $max = @{$self->{val}}; return "(Part $data->{index} of $max in $var)"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::All =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[>�H� � lib/Test/Deep/Class.pmnu ��6�$ use strict; use warnings; package Test::Deep::Class 1.204; use Test::Deep::Cmp; sub init { my $self = shift; my $snobby = shift; my $val = shift; $self->{snobby} = $snobby; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; local $Test::Deep::Snobby = $self->{snobby}; Test::Deep::wrap($self->{val})->descend($got); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Class =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �["�f�� � lib/Test/Deep/Set.pmnu ��6�$ use strict; use warnings; package Test::Deep::Set 1.204; use Test::Deep::Cmp; sub init { my $self = shift; $self->{IgnoreDupes} = shift; $self->{SubSup} = shift; $self->{val} = []; $self->add(@_); } sub descend { my $self = shift; my $d1 = shift; my $d2 = $self->{val}; my $IgnoreDupes = $self->{IgnoreDupes}; my $data = $self->data; my $SubSup = $self->{SubSup}; my $type = $IgnoreDupes ? "Set" : "Bag"; my $diag; if (ref $d1 ne 'ARRAY') { my $got = Test::Deep::render_val($d1); $diag = <<EOM; got : $got expect : An array to use as a $type EOM } if (not $diag) { my @got = @$d1; my @found; my @missing; foreach my $expect (@$d2) { my $found = 0; for (my $i = $#got; $i >= 0; $i--) { if (Test::Deep::eq_deeply_cache($got[$i], $expect)) { $found = 1; push(@found, $expect); splice(@got, $i, 1); last unless $IgnoreDupes; } } push(@missing, $expect) unless $found; } my @diags; if (@missing and $SubSup ne "sub" && $SubSup ne "none") { push(@diags, "Missing: ".nice_list(\@missing)); } if (@got and $SubSup ne "sup" && $SubSup ne "none") { my $got = __PACKAGE__->new($IgnoreDupes, "", @got); push(@diags, "Extra: ".nice_list($got->{val})); } if (@found and $SubSup eq "none") { my $found = __PACKAGE__->new($IgnoreDupes, "", @found); push(@diags, "Extra: ".nice_list($found->{val})); } $diag = join("\n", @diags); } if ($diag) { $data->{diag} = $diag; return 0; } else { return 1; } } sub diagnostics { my $self = shift; my ($where, $last) = @_; my $type = $self->{IgnoreDupes} ? "Set" : "Bag"; $type = "Sub$type" if $self->{SubSup} eq "sub"; $type = "Super$type" if $self->{SubSup} eq "sup"; $type = "NoneOf" if $self->{SubSup} eq "none"; my $error = $last->{diag}; my $diag = <<EOM; Comparing $where as a $type $error EOM return $diag; } sub add { # this takes an array. # For each element A of the array, it looks for an element, B, already in # the set which are deeply equal to A. If no matching B is found then A is # added to the set. If a B is found and IgnoreDupes is true, then A will # be discarded, if IgnoreDupes is false, then B will be added to the set # again. my $self = shift; my @array = @_; my $IgnoreDupes = $self->{IgnoreDupes}; my $already = $self->{val}; local $Test::Deep::Expects = 1; foreach my $new_elem (@array) { my $want_push = 1; my $push_this = $new_elem; foreach my $old_elem (@$already) { if (Test::Deep::eq_deeply($new_elem, $old_elem)) { $push_this = $old_elem; $want_push = ! $IgnoreDupes; last; } } push(@$already, $push_this) if $want_push; } # so we can compare 2 Test::Deep::Set objects using array comparison @$already = sort {(defined $a ? $a : "") cmp (defined $b ? $b : "")} @$already; } sub nice_list { my $list = shift; my @scalars = grep ! ref $_, @$list; my $refs = grep ref $_, @$list; my @ref_string = "$refs reference" if $refs; $ref_string[0] .= "s" if $refs > 1; # sort them so we can predict the diagnostic output return join(", ", (map {Test::Deep::render_val($_)} sort {(defined $a ? $a : "") cmp (defined $b ? $b : "")} @scalars), @ref_string ); } sub compare { my $self = shift; my $other = shift; return 0 if $self->{IgnoreDupes} != $other->{IgnoreDupes}; # this works (kind of) because the arrays are sorted return Test::Deep::descend($self->{val}, $other->{val}); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Set =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[� �j j lib/Test/Deep/Isa.pmnu ��6�$ use strict; use warnings; package Test::Deep::Isa 1.204; use Test::Deep::Cmp; use Scalar::Util; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; return Scalar::Util::blessed($got) ? $got->isa($self->{val}) : ref($got) eq $self->{val}; } sub diag_message { my $self = shift; my $where = shift; return "Checking class of $where with isa()"; } sub renderExp { my $self = shift; return "blessed into or ref of type '$self->{val}'"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Isa =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �["'V�/ / lib/Test/Deep/Array.pmnu ��6�$ use strict; use warnings; package Test::Deep::Array 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; return 0 unless Test::Deep::descend($got, Test::Deep::arraylength(scalar @$exp)); return 0 unless $self->test_class($got); return Test::Deep::descend($got, Test::Deep::arrayelementsonly($exp)); } sub reset_arrow { return 0; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Array =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�5�;� � lib/Test/Deep/NoTest.pmnu ��6�$ use strict; use warnings; # this is for people who don't want Test::Builder to be loaded but want to # use eq_deeply. It's a bit hacky... package Test::Deep::NoTest 1.204; # ABSTRACT: Use Test::Deep outside of the testing framework our $NoTest; { local $NoTest = 1; require Test::Deep; } sub import { my $import = Test::Deep->can("import"); # make the stack look like it should for use Test::Deep my $pkg = shift; unshift(@_, "Test::Deep"); push @_, '_notest'; goto &$import; } 1; #pod =head1 SYNOPSIS #pod #pod use Test::Deep::NoTest; #pod #pod if (eq_deeply($a, $b)) { #pod print "they were deeply equal\n"; #pod } #pod #pod =head1 DESCRIPTION #pod #pod This exports all the same things as Test::Deep but it does not load #pod Test::Builder so it can be used in ordinary non-test situations. __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::NoTest - Use Test::Deep outside of the testing framework =head1 VERSION version 1.204 =head1 SYNOPSIS use Test::Deep::NoTest; if (eq_deeply($a, $b)) { print "they were deeply equal\n"; } =head1 DESCRIPTION This exports all the same things as Test::Deep but it does not load Test::Builder so it can be used in ordinary non-test situations. =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[h� sr r lib/Test/Deep/RegexpVersion.pmnu ��6�$ use strict; use warnings; package Test::Deep::RegexpVersion 1.204; # Older versions of Perl treated Regexp refs as opaque scalars blessed # into the "Regexp" class. Several bits of code need this so we # centralise the test for that kind of version. our $OldStyle = ($] < 5.011); 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::RegexpVersion =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[��� � lib/Test/Deep/None.pmnu ��6�$ use strict; use warnings; package Test::Deep::None 1.204; use Test::Deep::Cmp; sub init { my $self = shift; my @list = map { eval { $_->isa('Test::Deep::None') } ? @{ $_->{val} } : $_ } @_; $self->{val} = \@list; } sub descend { my $self = shift; my $got = shift; foreach my $cmp (@{$self->{val}}) { return 0 if Test::Deep::eq_deeply_cache($got, $cmp); } return 1; } sub renderExp { my $self = shift; my @expect = map {; Test::Deep::wrap($_) } @{ $self->{val} }; my $things = join(", ", map {$_->renderExp} @expect); return "None of ( $things )"; } sub diagnostics { my $self = shift; my ($where, $last) = @_; my $got = $self->renderGot($last->{got}); my $exp = $self->renderExp; my $diag = <<EOM; Comparing $where with None got : $got expected : $exp EOM $diag =~ s/\n+$/\n/; return $diag; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::None =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�e�� lib/Test/Deep/Ignore.pmnu ��6�$ use strict; use warnings; package Test::Deep::Ignore 1.204; use Test::Deep::Cmp; my $Singleton = __PACKAGE__->SUPER::new; sub new { return $Singleton; } sub descend { return 1; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Ignore =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[� =�� � lib/Test/Deep/ArrayLengthOnly.pmnu ��6�$ use strict; use warnings; package Test::Deep::ArrayLengthOnly 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $len = $self->{val}; return @$got == $len; } sub render_stack { my $self = shift; my ($var, $data) = @_; return "array length of $var"; } sub renderVal { my $self = shift; my $val = shift; return "array with $val element(s)" } sub renderGot { my $self = shift; my $got = shift; return $self->renderVal(@$got + 0); } sub renderExp { my $self = shift; return $self->renderVal($self->{val}); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ArrayLengthOnly =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�TF � � lib/Test/Deep/Cmp.pmnu ��6�$ use strict; use warnings; package Test::Deep::Cmp 1.204; use overload '&' => \&make_all, '|' => \&make_any, '""' => \&string, fallback => 1, ; use Scalar::Util (); sub import { my $pkg = shift; my $callpkg = caller(); if ($callpkg =~ /^Test::Deep::/) { no strict 'refs'; push @{$callpkg."::ISA"}, $pkg; } } sub new { my $pkg = shift; my $self = bless {}, $pkg; $self->init(@_); return $self; } sub init { } sub make_all { my ($e1, $e2) = @_; return Test::Deep::all($e1, $e2); } sub make_any { my ($e1, $e2) = @_; return Test::Deep::any($e1, $e2); } sub cmp { my ($a1, $a2, $rev) = @_; ($a1, $a2) = ($a2, $a1) if $rev; return (overload::StrVal($a1) cmp overload::StrVal($a2)); } sub string { my $self = shift; return overload::StrVal($self); } sub render_stack { my $self = shift; my $var = shift; return $var; } sub renderExp { my $self = shift; return $self->renderGot($self->{val}); } sub renderGot { my $self = shift; return Test::Deep::render_val(@_); } sub reset_arrow { return 1; } sub data { my $self = shift; return $Test::Deep::Stack->getLast; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Cmp =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�g�Ն � lib/Test/Deep/Stack.pmnu ��6�$ use strict; use warnings; package Test::Deep::Stack 1.204; use Carp qw( confess ); use Scalar::Util; use Test::Deep::MM qw( new init Stack Arrow ); sub init { my $self = shift; $self->SUPER::init(@_); $self->setStack([]) unless $self->getStack; } sub push { my $self = shift; push(@{$self->getStack}, @_); } sub pop { my $self = shift; return pop @{$self->getStack}; } sub render { my $self = shift; my $var = shift; my $stack = $self->getStack; $self->setArrow(0); foreach my $data (@$stack) { my $exp = $data->{exp}; if (Scalar::Util::blessed($exp) and $exp->isa("Test::Deep::Cmp")) { $var = $exp->render_stack($var, $data); $self->setArrow(0) if $exp->reset_arrow; } else { confess "Don't know how to render '$exp'"; } } return $var; } sub getLast { my $self = shift; return $self->getStack->[-1]; } sub incArrow { my $self = shift; my $a = $self->getArrow; $self->setArrow($a + 1); return $a; } sub length { my $self = shift; return @{$self->getStack} + 0; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Stack =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�2�!� � lib/Test/Deep/Blessed.pmnu ��6�$ use strict; use warnings; package Test::Deep::Blessed 1.204; use Test::Deep::Cmp; use Scalar::Util qw( blessed ); sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; my $blessed = blessed($got); return Test::Deep::descend($blessed, Test::Deep::shallow($exp)); } sub render_stack { my $self = shift; my $var = shift; return "blessed($var)" } sub renderGot { my $self = shift; my $got = shift; $self->SUPER::renderGot(blessed($got)); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Blessed =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�� � lib/Test/Deep/ScalarRefOnly.pmnu ��6�$ use strict; use warnings; package Test::Deep::ScalarRefOnly 1.204; use Test::Deep::Cmp; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; return Test::Deep::descend($$got, $$exp); } sub render_stack { my $self = shift; my ($var, $data) = @_; return "\${$var}"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ScalarRefOnly =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�g lib/Test/Deep/Cache/Simple.pmnu ��6�$ use strict; use warnings; package Test::Deep::Cache::Simple 1.204; use Carp qw( confess ); use Scalar::Util qw( refaddr ); BEGIN { if (grep /^weaken$/, @Scalar::Util::EXPORT_FAIL) { # we're running on a version of perl that has no weak refs, so we # just install a no-op sub for weaken instead of importing it *weaken = sub {}; } else { Scalar::Util->import('weaken'); } } sub new { my $pkg = shift; my $self = bless {}, $pkg; return $self; } sub add { my $self = shift; my ($d1, $d2) = @_; { local $SIG{__DIE__}; local $@; # cannot weaken read only refs, no harm if we can't as they never # disappear eval{weaken($d1)}; eval{weaken($d2)}; } $self->{fn_get_key(@_)} = [$d1, $d2]; } sub cmp { my $self = shift; my $key = fn_get_key(@_); my $pair = $self->{$key}; # are both weakened refs still valid, if not delete this entry if (ref($pair->[0]) and ref($pair->[1])) { return 1; } else { delete $self->{$key}; return 0; } } sub absorb { my $self = shift; my $other = shift; @{$self}{keys %$other} = values %$other; } sub fn_get_key { return join(",", sort (map {refaddr($_)} @_)); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Cache::Simple =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�;, lib/Test/Deep/ScalarRef.pmnu ��6�$ use strict; use warnings; package Test::Deep::ScalarRef 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; return 0 unless $self->test_class($got); return 0 unless $self->test_reftype($got, Scalar::Util::reftype($exp)); return Test::Deep::descend($got, Test::Deep::scalarrefonly($exp)); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ScalarRef =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�6�ׂ � lib/Test/Deep/Boolean.pmnu ��6�$ use strict; use warnings; package Test::Deep::Boolean 1.204; use Test::Deep::Cmp; sub init { my $self = shift; $self->{val} = shift() ? 1 : 0; } sub descend { my $self = shift; my $got = shift; return !( $got xor $self->{val} ); } sub diag_message { my $self = shift; my $where = shift; return "Comparing $where as a boolean"; } sub renderExp { my $self = shift; $self->renderGot($self->{val}); } sub renderGot { my $self = shift; my $val = shift; return ($val ? "true" : "false")." (".Test::Deep::render_val($val).")"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Boolean =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[���V lib/Test/Deep/RegexpRefOnly.pmnu ��6�$ use strict; use warnings; package Test::Deep::RegexpRefOnly 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; return $got eq $exp; } sub render_stack { my $self = shift; my ($var, $data) = @_; return "m/$var/"; } sub renderGot { my $self = shift; return shift().""; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::RegexpRefOnly =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[���t t lib/Test/Deep/Methods.pmnu ��6�$ use strict; use warnings; package Test::Deep::Methods 1.204; use Test::Deep::Cmp; use Scalar::Util; sub init { my $self = shift; # get them all into [$name,@args] => $value format my @methods; while (@_) { my $name = shift; my $value = shift; push(@methods, [ ref($name) ? $name : [ $name ], $value ] ); } $self->{methods} = \@methods; } sub descend { my $self = shift; my $got = shift; my $data = $self->data; foreach my $method (@{$self->{methods}}) { $data->{method} = $method; my ($call, $exp_res) = @$method; my ($name, @args) = @$call; local $@; my $got_res; if (! eval { $got_res = $self->call_method($got, $call); 1 }) { die $@ unless $@ =~ /\ACan't locate object method "\Q$name"/; $got_res = $Test::Deep::DNE; } next if Test::Deep::descend($got_res, $exp_res); return 0; } return 1; } sub call_method { my $self = shift; my ($got, $call) = @_; my ($name, @args) = @$call; return $got->$name(@args); } sub render_stack { my $self = shift; my ($var, $data) = @_; my $method = $data->{method}; my ($call, $expect) = @$method; my ($name, @args) = @$call; my $args = @args ? "(".join(", ", @args).")" : ""; $var .= "->$name$args"; return $var; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Methods =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�k>&Z Z lib/Test/Deep/Cache.pmnu ��6�$ use strict; use warnings; package Test::Deep::Cache 1.204; use Test::Deep::Cache::Simple; sub new { my $pkg = shift; my $self = bless {}, $pkg; $self->{expects} = [Test::Deep::Cache::Simple->new]; $self->{normal} = [Test::Deep::Cache::Simple->new]; $self->local; return $self; } sub add { my $self = shift; my $type = $self->type; $self->{$type}->[-1]->add(@_); } sub cmp { # go through all the caches to see if we know this one my $self = shift; my $type = $self->type; foreach my $cache (@{$self->{$type}}) { return 1 if $cache->cmp(@_); } return 0 } sub local { my $self = shift; foreach my $type (qw( expects normal )) { push(@{$self->{$type}}, Test::Deep::Cache::Simple->new); } } sub finish { my $self = shift; my $keep = shift; foreach my $type (qw( expects normal )) { my $caches = $self->{$type}; my $last = pop @$caches; $caches->[-1]->absorb($last) if $keep; } } sub type { return $Test::Deep::Expects ? "expects" : "normal"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Cache =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[N��: : lib/Test/Deep/Ref.pmnu ��6�$ use strict; use warnings; package Test::Deep::Ref 1.204; use Test::Deep::Cmp; use Scalar::Util qw( blessed ); sub test_class { my $self = shift; my $got = shift; my $exp = $self->{val}; if ($Test::Deep::Snobby) { return Test::Deep::descend($got, Test::Deep::blessed(blessed($exp))); } else { return 1; } } sub test_reftype { my $self = shift; my $got = shift; my $reftype = shift; return Test::Deep::descend($got, Test::Deep::reftype($reftype)); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Ref =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�{�"� � lib/Test/Deep/Regexp.pmnu ��6�$ use strict; use warnings; package Test::Deep::Regexp 1.204; use Test::Deep::Cmp; use Test::Deep::RegexpMatches; sub init { my $self = shift; my $val = shift; $val = ref $val ? $val : qr/$val/; $self->{val} = $val; if (my $matches = shift) { $self->{matches} = Test::Deep::regexpmatches($matches, $val); $self->{flags} = shift || ""; } } sub descend { my $self = shift; my $got = shift; my $re = $self->{val}; if (my $match_exp = $self->{matches}) { my $flags = $self->{flags}; my @match_got; if ($flags eq "g") { @match_got = $got =~ /$re/g; } else { @match_got = $got =~ /$re/; } if (@match_got) { return Test::Deep::descend(\@match_got, $match_exp); } else { return 0; } } else { return ($got =~ $re) ? 1 : 0; } } sub diag_message { my $self = shift; my $where = shift; return "Using Regexp on $where"; } sub render_stack1 { my $self = shift; my $stack = shift; return "($stack =~ $self->{regex})"; } sub renderExp { my $self = shift; return "$self->{val}"; } sub renderGot { my $self = shift; my $got = shift; if (defined (my $class = Scalar::Util::blessed($got))) { my $ostr = qq{$got}; if ($ostr ne overload::StrVal($got)) { return qq{'$ostr' (instance of $class)}; } } return Test::Deep::render_val($got); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Regexp =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[3%D"w w lib/Test/Deep/RefType.pmnu ��6�$ use strict; use warnings; package Test::Deep::RefType 1.204; use Test::Deep::Cmp; use Scalar::Util qw( reftype ); sub init { my $self = shift; $self->{val} = shift; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; my $reftype = reftype($got); return Test::Deep::descend($reftype, Test::Deep::shallow($exp)); } sub render_stack { my $self = shift; my $var = shift; return "reftype($var)"; } sub renderGot { my $self = shift; my $got = shift; $self->SUPER::renderGot(reftype($got)); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::RefType =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�a� lib/Test/Deep/Code.pmnu ��6�$ use strict; use warnings; package Test::Deep::Code 1.204; use Test::Deep::Cmp; sub init { my $self = shift; my $code = shift || die "No coderef supplied"; $self->{code} = $code; } sub descend { my $self = shift; my $got = shift; my ($ok, $diag) = &{$self->{code}}($got); $self->data->{diag} = $diag; return $ok; } sub diagnostics { my $self = shift; my ($where, $last) = @_; my $error = $last->{diag}; my $data = Test::Deep::render_val($last->{got}); my $diag = <<EOM; Ran coderef at $where on $data EOM if (defined($error)) { $diag .= <<EOM; and it said $error EOM } else { $diag .= <<EOM; it failed but it didn't say why. EOM } return $diag; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Code =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[��M�� � lib/Test/Deep/String.pmnu ��6�$ use strict; use warnings; package Test::Deep::String 1.204; use Test::Deep::Cmp; sub init { my $self = shift; $self->{val} = shift; } sub descend { my $self = shift; my $got = shift().""; $self->data->{got} = $got; return $got eq $self->{val}; } sub diag_message { my $self = shift; my $where = shift; return "Comparing $where as a string"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::String =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[c��x x lib/Test/Deep/ListMethods.pmnu ��6�$ use strict; use warnings; package Test::Deep::ListMethods 1.204; use base 'Test::Deep::Methods'; sub call_method { my $self = shift; return [$self->SUPER::call_method(@_)]; } sub render_stack { my $self = shift; my $var = $self->SUPER::render_stack(@_); return "[$var]"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ListMethods =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[d WH H lib/Test/Deep/HashKeys.pmnu ��6�$ use strict; use warnings; package Test::Deep::HashKeys 1.204; use Test::Deep::Ref; sub init { my $self = shift; my %keys; @keys{@_} = (); $self->{val} = \%keys; $self->{keys} = [sort @_]; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; return 0 unless $self->test_reftype($got, "HASH"); return Test::Deep::descend($got, $self->hashkeysonly($exp)); } sub hashkeysonly { require Test::Deep::HashKeysOnly; my $self = shift; my $exp = shift; return Test::Deep::HashKeysOnly->new(keys %$exp) } package Test::Deep::SuperHashKeys 1.204; use base 'Test::Deep::HashKeys'; sub hashkeysonly { require Test::Deep::HashKeysOnly; my $self = shift; my $exp = shift; return Test::Deep::SuperHashKeysOnly->new(keys %$exp) } package Test::Deep::SubHashKeys 1.204; use base 'Test::Deep::HashKeys'; sub hashkeysonly { require Test::Deep::HashKeysOnly; my $self = shift; my $exp = shift; return Test::Deep::SubHashKeysOnly->new(keys %$exp) } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::HashKeys =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�d}�� � lib/Test/Deep/ArrayLength.pmnu ��6�$ use strict; use warnings; package Test::Deep::ArrayLength 1.204; use Test::Deep::Ref; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; my $exp = $self->{val}; return 0 unless $self->test_reftype($got, "ARRAY"); return Test::Deep::descend($got, Test::Deep::arraylengthonly($exp)); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::ArrayLength =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[�D"Z Z lib/Test/Deep/Obj.pmnu ��6�$ use strict; use warnings; package Test::Deep::Obj 1.204; use Test::Deep::Cmp; use Scalar::Util; sub init { my $self = shift; my $val = shift; $self->{val} = $val; } sub descend { my $self = shift; my $got = shift; return Scalar::Util::blessed($got) && $got->isa($self->{val}); } sub diag_message { my $self = shift; my $where = shift; return "Checking class of $where with isa()"; } sub renderExp { my $self = shift; return "blessed into '$self->{val}' or subclass of '$self->{val}'"; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Deep::Obj =head1 VERSION version 1.204 =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 AUTHORS =over 4 =item * Fergal Daly =item * Ricardo SIGNES <cpan@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2003 by Fergal Daly. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[ lib/auto/Test/Deep/.existsnu �[��� PK � �[�){o�9 �9 man3/Test::LeakTrace::JA.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::LeakTrace::JA 3" .TH Test::LeakTrace::JA 3 "2021-01-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::LeakTrace::JA \- メモリリークを追跡する .SH "VERSION" .IX Header "VERSION" This document describes Test::LeakTrace version 0.17. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Test::LeakTrace; \& \& # simple report \& leaktrace{ \& # ... \& }; \& \& # verbose output \& leaktrace{ \& # ... \& } \-verbose; \& \& # with callback \& leaktrace{ \& # ... \& } sub { \& my($ref, $file, $line) = @_; \& warn "leaked $ref from $file line\en"; \& }; \& \& my @refs = leaked_refs{ \& # ... \& }; \& my @info = leaked_info{ \& # ... \& }; \& \& my $count = leaked_count{ \& # ... \& }; \& \& # standard test interface \& use Test::LeakTrace; \& \& no_leaks_ok{ \& # ... \& } "description"; \& \& leaks_cmp_ok{ \& # ... \& } \*(Aq<\*(Aq, 10; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" PerlのGCはリファレンスカウンタを用いたものなので，オブジェクトが開放されるタイミングが明確であることや体感速度が高速であることなど数々の利点があります。 その一方で，循環参照を開放できないこと，Cレベルでの操作でミスしやすいなど，問題点がいくつかあります。それらの問題点のほとんどはメモリリークに関することですから，メモリリークを追跡することは非常に重要な課題です。 .PP \&\f(CW\*(C`Test::LeakTrce\*(C'\fRはメモリリークを追跡するためのいくつかのユーティリティと\f(CW\*(C`Test::Builder\*(C'\fRベースのテスト関数を提供します。このモジュールはPerlのメモリアロケーションシステムであるアリーナを走査するため，SVに関することであれば与えられたコードのどんなメモリリークでも検出できます。つまり，Perlレベルでの循環参照を始めとして，XSモジュールやPerl自身のバグによるメモリリークを追跡することができます。 .PP ここで\fBリーク\fRとは，特定のスコープ内で新たに作成されて，そのスコープ終了後にも残っている値を意味します。これは，新たに作成されたグローバルな値やPerlが暗黙のうちに作成するキャッシュの値も含みます。たとえば，リーク追跡を行っている最中に新たに名前つきサブルーチンを定義すれば，それはリークとみなされます。また，継承したメソッドを呼び出したり，オブジェクトを作成したりするだけで様々なキャッシュが生成され，リークが報告される可能性があります。 .SH "INTERFACE" .IX Header "INTERFACE" .SS "Exported functions" .IX Subsection "Exported functions" \fI\f(CI\*(C`leaked_info { BLOCK }\*(C'\fI\fR .IX Subsection "leaked_info { BLOCK }" .PP \&\fI\s-1BLOCK\s0\fRを実行し，追跡結果をリストで返します。 結果はリークした値のリファレンス，ファイル名，行番号の三要素を持つ配列，つまり\f(CW\*(C`[$ref, $file, $line]\*(C'\fRのリストとなっています。 .PP なお，この関数はPerl内部で使用する値を返す可能性があります。そのような内部用の値を変更するとPerl実行環境に致命的な影響を与える可能性があるので注意してください。また，配列やハッシュの要素として，リファレンスではない配列やハッシュそれ自体が含まれる可能性があります。そのような値は通常Perlレベルで操作することができません。たとえば\f(CW\*(C`Data::Dumper\*(C'\fRなどで出力することはできません。 .PP \fI\f(CI\*(C`leaked_refs { BLOCK }\*(C'\fI\fR .IX Subsection "leaked_refs { BLOCK }" .PP \&\fI\s-1BLOCK\s0\fRを実行し，リークしたSVのリファレンスのリストを返します。 .PP \&\f(CW\*(C`map{ $_\->[0] } leaked_info{ BLOCK }\*(C'\fRと同じですが，より高速です。 .PP \fI\f(CI\*(C`leaked_count { BLOCK }\*(C'\fI\fR .IX Subsection "leaked_count { BLOCK }" .PP \&\fI\s-1BLOCK\s0\fRを実行し，リークしたSVのリファレンスの個数を返します。 .PP \&\f(CW\*(C`leaked_info()\*(C'\fRと\f(CW\*(C`leaked_refs()\*(C'\fRもスカラコンテキストでは個数を返しますが， \&\f(CW\*(C`leaked_count()\*(C'\fRはコンテキストに依存しません。 .PP \fI\f(CI\*(C`leaktrace { BLOCK } ?($mode | \e&callback)\*(C'\fI\fR .IX Subsection "leaktrace { BLOCK } ?($mode | &callback)" .PP \&\fI\s-1BLOCK\s0\fRを実行し，その中で起きたメモリリークを\f(CW*STDERR\fRに報告します。 .PP メモリリークの報告は\fI\f(CI$mode\fI\fRで指定したモードに従います。 受け付ける\fI\f(CI$mode\fI\fRは以下の通りです： .IP "\-simple" 4 .IX Item "-simple" デフォルトのモードです。リークしたSVの型とアドレス，ファイル名，行番号を報告します。 .IP "\-sv_dump" 4 .IX Item "-sv_dump" \&\fB\-simple\fRに加えて，\f(CW\*(C`sv_dump()\*(C'\fRでSVの中身をダンプします。 これは，\f(CW\*(C`Devel::Peek::Dump()\*(C'\fRの出力とほぼ同じです。 .IP "\-lines" 4 .IX Item "-lines" \&\fB\-simple\fRに加えて，リークしていると見られる行の周辺を出力します。 .IP "\-verbose" 4 .IX Item "-verbose" \&\fB\-simple\fRと\fB\-sv_dump\fRと\fB\-lines\fRの全てを出力します。 .PP より細かな制御のためにコールバックを指定することもできます。 \&\fI\e&callback\fRはリークしたSV毎に呼び出され，その引数はリークしたSVのリファレンス，ファイル名，行番号の3つです。 .PP \fI\f(CI\*(C`no_leaks_ok { BLOCK } ?$description\*(C'\fI\fR .IX Subsection "no_leaks_ok { BLOCK } ?$description" .PP \&\fI\s-1BLOCK\s0\fRにメモリリークがないことテストします。 これは\f(CW\*(C`Test::Builder\*(C'\fRベースのテスト関数です。 .PP なお，\fI\s-1BLOCK\s0\fRは複数回実行されます。これは，初回の実行でキャッシュを用意する可能性を考慮するためです。 .PP \fI\f(CI\*(C`leaks_cmp_ok { BLOCK } $cmp_op, $count, ?$description\*(C'\fI\fR .IX Subsection "leaks_cmp_ok { BLOCK } $cmp_op, $count, ?$description" .PP \&\fI\s-1BLOCK\s0\fRのメモリリーク数と特定の数値を比較するテストを行います。 これは\f(CW\*(C`Test::Builder\*(C'\fRベースのテスト関数です。 .PP なお，\fI\s-1BLOCK\s0\fRは複数回実行されます。これは，初回の実行でキャッシュを用意する可能性を考慮するためです。 .SS "Script interface" .IX Subsection "Script interface" \&\f(CW\*(C`Devel::LeakTrace\*(C'\fRと同様に，スクリプトのリーク追跡のために\f(CW\*(C`Test::LeakTrace::Script\*(C'\fRが提供されます。\f(CW\*(C`use Test::LeakTrace::Script\*(C'\fR宣言の引数は\f(CW\*(C`leaktrace()\*(C'\fRと同じです。 .PP .Vb 2 \& $ TEST_LEAKTRACE=\-sv_dump perl \-MTest::LeakTrace::Script script.pl \& $ perl \-MTest::LeakTrace::Script=\-verbose script.pl \& \& #!perl \& # ... \& \& use Test::LeakTrace::Script sub{ \& my($ref, $file, $line) = @_; \& # ... \& }; \& \& # ... .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Testing modules" .IX Subsection "Testing modules" 以下はモジュールのメモリリークをチェックするテストスクリプトのテンプレートです。 .PP .Vb 5 \& #!perl \-w \& use strict; \& use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace }; \& use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => \*(Aqrequire Test::LeakTrace\*(Aq); \& use Test::LeakTrace; \& \& use Some::Module; \& \& leaks_cmp_ok{ \& my $o = Some::Module\->new(); \& $o\->something(); \& $o\->something_else(); \& } \*(Aq<\*(Aq, 1; .Ve .SH "GUTS" .IX Header "GUTS" \&\f(CW\*(C`Test::LeakTrace\*(C'\fRはアリーナを走査します。アリーナとは，Perlが作成するSVのためのメモリアロケーションシステムであり，\fIsv.c\fRで実装されています。 アリーナの走査には\fIsv.c\fRにある\f(CW\*(C`S_visit()\*(C'\fRのコードを元にしたマクロを用いています。 .PP さて，アリーナを走査すれば，メモリリークの検出そのものは簡単にできるように思えます。まず，コードブロックを実行する前に一度アリーナを走査し，全てのSVに「使用済み」の印を付けておきます。次に，コードブロック実行後にもう一度アリーナを走査し，使用済みの印がついていないSVがあれば，それはコードブロック内で作成され，開放されなかったSVだと考えます。あとはそれを報告するだけです。実際には，SVに対して使用済みの印を付けるスペースがないため，インサイドアウト法を応用して外部のコンテナに使用済みの印を保存します。 これを仮にPerlコードで書くと以下のようになります。 .PP .Vb 5 \& my %used_sv; \& foreach my $sv(@ARENA){ \& $used_sv{$sv}++; \& } \& $block\->(); \& \& my @leaked \& foreach my $sv(@ARENA){ \& if(not exists $used_sv{$sv}){ \& push @leaked, $sv; \& } \& } \& say \*(Aqleaked count: \*(Aq, scalar @leaked; .Ve .PP リークしたSVを得るだけならこの方法で十分です。実際，\f(CW\*(C`leaked_refs()\*(C'\fRと\f(CW\*(C`leaked_count()\*(C'\fRはこのような方法でリークしたSVやその個数を調べています。 .PP しかし，リークしたSVのステートメントの情報，つまりファイル名や行番号を得るためにはこれだけでは不十分です。Perl 5.10以降にはSVが作成されたときのステートメント情報を追跡する機能があるのですが，この機能を利用するためには，コンパイラオプションとしてに\f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fRを与えてPerlをビルドしなければなりません。 .PP そこで，\f(CW\*(C`Test::LeakTrace\*(C'\fRでは拡張可能な\f(CW\*(C`PL_runops\*(C'\fRを利用して，Perl VMがOPコードを実行する1ステートメント毎にアリーナを走査し，ステートメント情報を記録します。これは，1ステートメント毎にマーク＆スイープのような処理を行うのに等しく，非常に時間が掛かります。しかし，Perlを特殊な条件の下でビルドする必要もなく，バージョンに依存した機能もほとんど使用しないため，多くの環境で動かすことができます。 .PP また，\f(CW\*(C`no_leaks_ok()\*(C'\fRのようなテスト関数はまず\f(CW\*(C`leaked_count()\*(C'\fRでリークしたSVの個数を得てから，必要に応じてリークした位置を特定するために\f(CW\*(C`leaktrace()\*(C'\fRを実行するため，テストが成功する限りは時間の掛かる追跡処理はしません。 .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Perl 5.8.1 or later, and a C compiler. .SH "CAVEATS" .IX Header "CAVEATS" \&\f(CW\*(C`Test::LeakTrace\*(C'\fRは\f(CW\*(C`Devel::Cover\*(C'\fRと一緒に動かすことはできません。 したがって，\f(CW\*(C`Devel::Cover\*(C'\fRの元で動いていることが検出されると，テスト関数は何も行わずにテストをパスさせます。 .SH "BUGS" .IX Header "BUGS" No bugs have been reported. .PP Please report any bugs or feature requests to the author. .SH "SEE ALSO" .IX Header "SEE ALSO" Devel::LeakTrace. .PP Devel::LeakTrace::Fast. .PP Test::TraceObject. .PP Test::Weak. .PP For guts: .PP perlguts. .PP perlhack. .PP sv.c. .SH "AUTHOR" .IX Header "AUTHOR" Goro Fuji <gfuji(at)cpan.org>. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2009, Goro Fuji. Some rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[ Vm man3/Test::LeakTrace::Script.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::LeakTrace::Script 3" .TH Test::LeakTrace::Script 3 "2021-01-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::LeakTrace::Script \- A LeakTrace interface for whole scripts .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& #!perl \-w \& use Test::LeakTrace::Script sub{ \& my($svref, $file, $line) = @_; \& \& warn "leaked $svref from $file line $line.\en"; \& }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a interface to \f(CW\*(C`Test::LeakTrace\*(C'\fR for whole scripts. .SH "INTERFACE" .IX Header "INTERFACE" .SS "Command line interface" .IX Subsection "Command line interface" .Vb 1 \& $ perl \-MTest::LeakTrace::Script script.pl \& \& $ perl \-MTest::LeakTrace::Script=\-verbose script.pl \& \& $ TEST_LEAKTRACE=\-lines script.pl .Ve .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" .SS "TEST_LEAKTRACE=mode" .IX Subsection "TEST_LEAKTRACE=mode" \fI\-simple (\s-1DEFAULT\s0)\fR .IX Subsection "-simple (DEFAULT)" .PP \fI\-sv_dump\fR .IX Subsection "-sv_dump" .PP \fI\-lines\fR .IX Subsection "-lines" .PP \fI\-verbose\fR .IX Subsection "-verbose" .SH "SEE ALSO" .IX Header "SEE ALSO" Test::LeakTrace. PK � �[K��� man3/Test::LeakTrace.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::LeakTrace 3" .TH Test::LeakTrace 3 "2021-01-05" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::LeakTrace \- Traces memory leaks .SH "VERSION" .IX Header "VERSION" This document describes Test::LeakTrace version 0.17. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Test::LeakTrace; \& \& # simple report \& leaktrace{ \& # ... \& }; \& \& # verbose output \& leaktrace{ \& # ... \& } \-verbose; \& \& # with callback \& leaktrace{ \& # ... \& } sub { \& my($ref, $file, $line) = @_; \& warn "leaked $ref from $file line\en"; \& }; \& \& my @refs = leaked_refs{ \& # ... \& }; \& my @info = leaked_info{ \& # ... \& }; \& \& my $count = leaked_count{ \& # ... \& }; \& \& # standard test interface \& use Test::LeakTrace; \& \& no_leaks_ok{ \& # ... \& } \*(Aqno memory leaks\*(Aq; \& \& leaks_cmp_ok{ \& # ... \& } \*(Aq<\*(Aq, 10; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`Test::LeakTrace\*(C'\fR provides several functions that trace memory leaks. This module scans arenas, the memory allocation system, so it can detect any leaked SVs in given blocks. .PP \&\fBLeaked SVs\fR are SVs which are not released after the end of the scope they have been created. These SVs include global variables and internal caches. For example, if you call a method in a tracing block, perl might prepare a cache for the method. Thus, to trace true leaks, \f(CW\*(C`no_leaks_ok()\*(C'\fR and \f(CW\*(C`leaks_cmp_ok()\*(C'\fR executes a block more than once. .SH "INTERFACE" .IX Header "INTERFACE" .SS "Exported functions" .IX Subsection "Exported functions" \fI\f(CI\*(C`leaked_info { BLOCK }\*(C'\fI\fR .IX Subsection "leaked_info { BLOCK }" .PP Executes \fI\s-1BLOCK\s0\fR and returns a list of leaked SVs and places where the SVs come from, i.e. \f(CW\*(C`[$ref, $file, $line]\*(C'\fR. .PP \fI\f(CI\*(C`leaked_refs { BLOCK }\*(C'\fI\fR .IX Subsection "leaked_refs { BLOCK }" .PP Executes \fI\s-1BLOCK\s0\fR and returns a list of leaked SVs. .PP \fI\f(CI\*(C`leaked_count { BLOCK }\*(C'\fI\fR .IX Subsection "leaked_count { BLOCK }" .PP Executes \fI\s-1BLOCK\s0\fR and returns the number of leaked SVs. .PP \fI\f(CI\*(C`leaktrace { BLOCK } ?($mode | \e&callback)\*(C'\fI\fR .IX Subsection "leaktrace { BLOCK } ?($mode | &callback)" .PP Executes \fI\s-1BLOCK\s0\fR and reports leaked SVs to \f(CW*STDERR\fR. .PP Defined \fI\f(CI$mode\fI\fRs are: .IP "\-simple" 4 .IX Item "-simple" Default. Reports the leaked \s-1SV\s0 identity (type and address), file name and line number. .IP "\-sv_dump" 4 .IX Item "-sv_dump" In addition to \fB\-simple\fR, dumps the sv content using \f(CW\*(C`sv_dump()\*(C'\fR, which also implements \f(CW\*(C`Devel::Peek::Dump()\*(C'\fR. .IP "\-lines" 4 .IX Item "-lines" In addition to \fB\-simple\fR, prints suspicious source lines. .IP "\-verbose" 4 .IX Item "-verbose" Both \fB\-sv_dump\fR and \fB\-lines\fR. .PP \fI\f(CI\*(C`no_leaks_ok { BLOCK } ?$description\*(C'\fI\fR .IX Subsection "no_leaks_ok { BLOCK } ?$description" .PP Tests that \fI\s-1BLOCK\s0\fR does not leaks SVs. This is a test function using \f(CW\*(C`Test::Builder\*(C'\fR. .PP Note that \fI\s-1BLOCK\s0\fR is called more than once. This is because \&\fI\s-1BLOCK\s0\fR might prepare caches which are not memory leaks. .PP \fI\f(CI\*(C`leaks_cmp_ok { BLOCK } $cmp_op, $number, ?$description\*(C'\fI\fR .IX Subsection "leaks_cmp_ok { BLOCK } $cmp_op, $number, ?$description" .PP Tests that \fI\s-1BLOCK\s0\fR leaks a specific number of SVs. This is a test function using \f(CW\*(C`Test::Builder\*(C'\fR. .PP Note that \fI\s-1BLOCK\s0\fR is called more than once. This is because \&\fI\s-1BLOCK\s0\fR might prepare caches which are not memory leaks. .PP \fI\f(CI\*(C`count_sv()\*(C'\fI\fR .IX Subsection "count_sv()" .PP Counts all the SVs in the arena. .SS "Script interface" .IX Subsection "Script interface" Like \f(CW\*(C`Devel::LeakTrace\*(C'\fR \f(CW\*(C`Test::LeakTrace::Script\*(C'\fR is provided for whole scripts. .PP The arguments of \f(CW\*(C`use Test::LeakTrace::Script\*(C'\fR directive is the same as \f(CW\*(C`leaktrace()\*(C'\fR. .PP .Vb 2 \& $ TEST_LEAKTRACE=\-sv_dump perl \-MTest::LeakTrace::Script script.pl \& $ perl \-MTest::LeakTrace::Script=\-verbose script.pl \& \& #!perl \& # ... \& \& use Test::LeakTrace::Script sub{ \& my($ref, $file, $line) = @_; \& # ... \& }; \& \& # ... .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Testing modules" .IX Subsection "Testing modules" Here is a test script template that checks memory leaks. .PP .Vb 5 \& #!perl \-w \& use strict; \& use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace }; \& use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => \*(Aqrequire Test::LeakTrace\*(Aq); \& use Test::LeakTrace; \& \& use Some::Module; \& \& leaks_cmp_ok{ \& my $o = Some::Module\->new(); \& $o\->something(); \& $o\->something_else(); \& } \*(Aq<\*(Aq, 1; .Ve .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Perl 5.8.1 or later, and a C compiler. .SH "CAVEATS" .IX Header "CAVEATS" \&\f(CW\*(C`Test::LeakTrace\*(C'\fR does not work with \f(CW\*(C`Devel::Cover\*(C'\fR and modules which install their own \f(CW\*(C`runops\*(C'\fR routines, or the perl executor. So if the test functions of this module detect strange \f(CW\*(C`runops\*(C'\fR routines, they do nothing and report okay. .SH "BUGS" .IX Header "BUGS" No bugs have been reported. .PP Please report any bugs or feature requests to the author. .SH "SEE ALSO" .IX Header "SEE ALSO" Devel::LeakTrace. .PP Devel::LeakTrace::Fast. .PP Test::TraceObject. .PP Test::Weak. .PP For guts: .PP perlguts. .PP perlhack. .PP \&\fIsv.c\fR. .SH "AUTHOR" .IX Header "AUTHOR" Goro Fuji(gfx) <gfuji(at)cpan.org>. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2009\-2010, Goro Fuji(gfx). All rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK � �[� ��g �g % arch/auto/Test/LeakTrace/LeakTrace.sonu ȯ�� ELF > �& @ ^ @ 8 @ ' & � � � � @ @ @ � � L \ \ � � 0L 0\ 0\ � � � � � � � � $ $ S�td � � � P�td �A �A �A t t Q�td R�td L \ \ � � GNU � GNU B��We�R v�(%uw�Y_�� 9 9 !� � � � x � � h � " ' � � $ . y � � � � x j P q U � U � � � � C U � � @ � c � h , k B � � 6 ] F " � . �: � __gmon_start__ _ITM_deregisterTMCloneTable _ITM_registerTMCloneTable __cxa_finalize Perl_ptr_table_fetch memcpy Perl_safesyscalloc Perl_ptr_table_store Perl_safesysrealloc Perl_newSV Perl_safesysfree Perl_croak_xs_usage Perl_ptr_table_new Perl_mg_get Perl_sv_2bool_flags Perl_croak strcmp Perl_ptr_table_free __sigsetjmp Perl_PerlIO_stderr PerlIO_printf exit Perl_push_scope Perl_savetmps Perl_newRV Perl_sv_2mortal Perl_newSVpvn_flags Perl_sv_newmortal Perl_sv_setiv Perl_call_sv Perl_pop_scope Perl_free_tmps Perl_stack_grow Perl_markstack_grow Perl_warn Perl_sv_2pv_flags Perl_newSV_type Perl_av_push Perl_newSVpvn Perl_newSViv Perl_newRV_noinc Perl_sv_reftype PerlIO_open Perl_sv_gets Perl_PerlIO_close Perl_do_sv_dump Perl_save_sptr Perl_gv_add_by_type __stack_chk_fail __longjmp_chk Perl_sv_setuv_mg strlen boot_Test__LeakTrace Perl_xs_handshake Perl_newXS_deffile Perl_my_cxt_init Perl_xs_boot_epilog libperl.so.5.32 libc.so.6 GLIBC_2.11 GLIBC_2.14 GLIBC_2.4 GLIBC_2.2.5 � ��� � ��� � ii � ui � \ �' \ @' (\ (\ �_ �_ �_ 0 �_ 7 8^ @^ H^ P^ X^ `^ h^ p^ x^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ �^ _ _ _ _ _ (_ ! 0_ " 8_ # @_ $ H_ % P_ & X_ ' `_ ( h_ ) p_ * x_ + �_ , �_ - �_ . �_ / �_ 1 �_ 2 �_ 3 �_ 4 �_ 5 �_ 6 �_ 7 �_ 8 � �H��H��? H��t��H��� �5> �%> � �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h ������� �h ������ �h ������ �h ������ �h ������ �h ������ �h ��q����� �h ��a����� �h ��Q����� �h ��A����� �h ��1����� �h ��!����� �h ������� �h ������� �h ����� �h ������ �h! ������� �h" ������ �h# ������ �h$ ������ �h% ������ �h& ������ �h' ��q����� �h( ��a����� �h) ��Q����� �h* ��A����� �h+ ��1����� �h, ��!����� �h- ������� �h. ������� �h/ ����� �h0 ������ �h1 ������� �h2 ������ �h3 ������ �h4 ������ ��%�: D � ��%�: D � ��%�: D � ��%�: D � ��%�: D � ��%�: D � ��%}: D � ��%u: D � ��%m: D � ��%e: D � ��%]: D � ��%U: D � ��%M: D � ��%E: D � ��%=: D � ��%5: D � ��%-: D � ��%%: D � ��% : D � ��%: D � ��% : D � ��%: D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%�9 D � ��%}9 D � ��%u9 D � ��%m9 D � ��%e9 D � ��%]9 D � ��%U9 D � ��%M9 D � ��%E9 D � ��%=9 D � ��%59 D � ��%-9 D � ��%%9 D � ��% 9 D � ��%9 D � ��% 9 D H�=19 H�*9 H9�tH��8 H��t �� � � � H�=9 H�5�8 H)�H��H��?H��H�H�tH��8 H��t��f D � � � ��=�8 u+UH�=�8 H��t H�=�4 �I����d�����8 ]� � � � ��w��� � AWAVI��AUATI��USH��H�F H�x tQH�0H�Hf. � H��H��t1 � H�P�R ��� t�� t H�PH� H� H��u�H��s�M��$ M���� � A�EI�]H�@I�l� H9�w� D H��H9��� �C =� t� u�I�vH��L�����H��u�I�v H��L�����I��H��tkH�8 u�I� A�~ t�A�VI�A;WvI�v��H��Hc��.���A�FA�GA�FA�GH9��z��� D M�m M���;���H��[]A\A]A^A_þ � ����I�v H��L��H��I������r�����Hc��`���I�GH��A�V�o���� �U�' SH��H��H�GxH�P�H�Wx�(�����H��` f�Hc�H�@Hc �6 H��H�@ @H�CH�D�H�H��[]�f � � �ATUSH�GxH��H�P�H�WxHcB6 �(H��` L�$Ѓ�Hc�I�|$���I�D$ H�CH�D�H�[]A\�ff. � ATI��UH��Sf D I� �H��t- � H�CH�x�C���H�{�:���H�C H�H��u�H�E�H��t H��� @ []A\� � �H��H��H�PxH�pH�J�H�HxHcL�֍JH�L)�H����u7H��h H�0 H9� tHc�H�<�H�HH��H�� @ H��8 ��PH�5� ����f. � � �AWAVI��H��AUATUSH��I�FxI�NH�P�I�VxHc H�4��PI�H)�H������ I��` Hc5�4 L�<�Hc�H�,�L�,� H���) �E �< I��8 H��H)�H��H�� H9���A�? �_ A�L��A�G��L��I�G���I�G M�� M��tb @ A�D$I�\$H�@I�,�H9�w�< � H��H9�v,�C =� t� u�I�wH��H��L��H�����H9�w�M�$$M��u�I�FJ�D(�I�H��[]A\A]A^A_ËE ��tG��tIH�U 1�H���1���H�R� H��� ���1�H������H�E�80������f D 1������t!H�E H�x �����H��L����������t#H�U� �B�����H�H��B�����1�H��L��������H�5J L��1�� ���H�5 ��� @ � �AWH��AVAUATUSH��h H�<$H��H�1dH�%( H��$X 1�H�AxH�t$H�P�H�QxH�IHc H���XH��H)�H�����w H�<$Hc�Hc5�2 H��H)T$H��` H��H�T$H�WD�r"A��D�t$#u1H��� HcV(���W L�VH�<RH��I��D�rA��D�t$#H�D$` H�D$X ���� Hc�H�,�H�D$�8 �� �E 1��ts��tH�U�z � % = �� L�eH�5� L�� �I�����t4H�5� L�� �1�����t H�5� L�� �������w L�4$L�|$L��L�����E1�L��fE�M�� M���> E1�\$$E1�L��L�l$I��f D �CH�kH�@L�,�I9�w �Rf�H��I9�vG�E =� t� u�I�w H��L������H��t�H�8 t�H��L�`I��H�D$I9�w�f D H�H��u�L�l$�\$$L�|$L�4$L�d$hI�wL����I�G ���� H�D$`H��� I�� H�|$x1�L�4$H�D$p���� �L�4$��$@ A��H�D$pI�� A��� Ƅ$D f��$F E���( H�D$pH� $H�� H�D$L�@ I�x tI�pI�8� ���H�D$L�@ H� $L��H����H�D$H�@ H�� H�8 �� A���l H�<$����D��H�5 H��1��S���� ����|$#�� �|$#�� H�\$L�C I�x tI�pI�8�d���L�C H�<$L���d�H�D$H�@ H�D$XH���� H�$H�L$H�H��$X dH+%( �� H��h []A\A]A^A_�L�d$`H�\$hH��� L��� @ H�[H���� H�L�m �@ =� t� u�H����H����H�ExH��H�ExH;�� �: L��H+UH���H�E L)�H���� H�3H��M�u�M�H��H���� H��I�EHcSH�s� �H��I�ELc{��L��H��I�EH����L�u L��H�� �3�H�U ��t ��H��H��H�U H�EXH9EP<H����H�[H��������$F H� $f��� H�D$pH�� �;��� H���p��f D L��L�� H���U�I��H�E L)�H������L��L�� H���/�I����� � H���(����H�$H��P H�D$�8 �<���L�<$1�H�5O Hc�L���r�I�GH�D�H�D$����H�<$�" 1�H���\�I���'����~,A��A�V�T$#���H�l$`� �O���M���O H�$H�@ H�D$@H+D$H��L9��0 H�D$hH������L�l$H� $�H�D$hH��H�0�`�H��H�D$h�@��ts� H���T�H��H��H��I���S�H�T$hH�D$hH��HcRH�p���L��H��H���+�H�D$hH��Hcp�j�L��H��H��� �L��H����H��H��H��I���?�I�E H�D$hH�@H�D$hH�D$hH���?���L�l$�E���H�$H�l$H�@ H�D$8H)�H���� H� $H�EH�D$H���R�L��H��H�EH��� �������D$H���H�$L�|$hH��H H��t �x �z H�<$��H�ʼn��D$(�� M�������L�$$����R M�M���i E�GE��t�M�/E�O1�L��M�wL��D�L$L���D�L$LM��H��H��L��H�5' 1��x�|$(E�w��t�E��t�I�H�5# ���I��$� I��H�FL�M��� D�D$HM���[����\$,D��L�|$0E��M��1�L��L��L����H��t)��A�G�9�|�L���H�5� H��1����A�G9�|�L��L��\$,L�|$0�Z���E1�E1��K���H�5S L�� �����m���H�5@ L�� �j����Q���H�l$X�G���j 1�A� E1�j I�H��L����Y^����T$(������H�$H�HXH9HP�� H�<$�M����H�T$H�<$L��H���$�H�D$���L�4$L����L����I��� L����I��� L��H�p��H�5� � L��� ���I��� I��� L�fI�<$ �� H�<$��I�$M��������;���H�@H�@H���u���H� H�h(H���q����`���H�<$H��H�� �Y�H�����H�<$�H����1�L�����H�@L������H�<$1����L�`�f���H�$��, �U�H�T$XH�<$H�5� 1�� �H�xD����H�5* ���f D � �AUATUSH��H��H�GxH�P�H�WxH�Hc H�ǍhH�H)�H����� H�C�@#�� H�PH�� H�CL�$�H���� E1�f D �FH�VH�@H� �H9�v# @ �B =� t % ��I�� H��H9�w�H�6H��u�L��M��H��H��?A�D$ Hc�H����L�l/���������� @�ƃ�@��tV��tR��M�L$A�D$ M�eHkH�+H��[]A\A]�H����H�� H�{I��H���6���� E1�E1��{���L��L��H������I��H�5+ L���]�ff. � f�AVAUATI��USL�v0H��L����;CH�{D�hH��Mc�#L��L���H��kA�D$$�C[]A\A]A^� @ L�����H�CH����ff. � @ � �ATHc#& USH��` H��L��� H�,� @ H�CH��PH�CH��t=��4 ��uK�} t�L9�� t�H��H���a�L��� H��L��� ���� D �} u"ƃ� 1�[]A\� @ H���� � D H��H����ƃ� 1�[]A\� � � �ATL� H��1�UH� � H��H�� ���H�����H��H�d�H�5� A���e�H��H���H�5� �O�H��H���H�5� �9�H��H���H�5� �#�H��H�9�H�5R � �H��H�����H�5� ��H��( H�5�$ ��H��� H����H�]���D��H��H�� H��]A\���� �H��H��� need_stateinfo mode= &PL_sv_undef LeakTrace not started -simple -sv_dump -lines -verbose -silent panic: top_env, v=%d r %4d:%-p Invalid reporting mode: %-p 0.17 v5.32.0 LeakTrace.c Test::LeakTrace::CLONE Test::LeakTrace::END Test::LeakTrace::_start Test::LeakTrace::_finish Test::LeakTrace::count_sv Cannot start LeakTrace inside its scope leaked %s(0x%p) from %s line %d. Test::LeakTrace::_runops_installed ;p |��� ��� ��� �� ��@ \�l ��� <�� \�� L���\ ����� ,���� �� zR x � $ ���` FJ w� ?:*3$" D �P H \ �� B�B�E �B(�D0�A8�D@= 8A0A(B BBBA $ � l�g E�F�G RAA( � ��U F�A�A �IAB ( � ��] B�D�D �OAB ( �v j H @ �� F�B�H �B(�A0�A8�D@& 8A0A(B BBBA \ � X�� F�E�B �B(�A0�A8�G�� 8A0A(B BBBA >�M�O�A� 8 � ��c F�B�A �A(�G0� (A ABBA 8 ( ���a B�B�B �D(�A0�y (A BBBE 4 d P���� F�H�A �y ABE eAB $ � ���� F�M�Z �AB �' @' (\ � � �; \ \ ���o � � � ^ � � � ���o ���o � ���o �o \ ���o 0\ 0 @ P ` p � � � � � � � � ! ! ! 0! @! P! `! p! �! �! �! �! �! �! �! �! " " " 0" @" P" `" p" �" �" �" �" �" �" �" �" # # # 0# @# P# `# p# ����GCC: (GNU) 11.4.1 20231218 (Red Hat 11.4.1-3) AV:4g1231 RV:running gcc 11.4.1 20231218 BV:annobin gcc 11.4.1 20231218 GW:0x3d1056a lto SP:3 SC:-1 lto CF:8 lto FL:-2 lto GA:1 PI:2 SE:0 GA$3a1 �& �& GA$3a1 GA$3a1 �; �; GA$3a1 �& �' GA$3a1 �; �; GA$3a1 �; �; GA$3a1 GA$3a1 �; �; , �' � @ �' � � �' � �( � �� ; 3 9� �' �' X �� O� O� \ X C� i g [� �' Q \� q o g� { w r� �' : s� � � � � � � � � � � � � � *� ! +� � � � �( 1 �� B� 6� A ? *� L J �( / y( ( � U| Qs �( - � U1T ) 2 � U| Qs R ) 7 e( ( U| Qs /| | �{ �{ �� 0) g �[ �� [ U ˀ x t ׀ � � � � � � � � �� ̈́ 4) < � � ܄ � � � G K � � � � � � � u) \ h0 � � � � �� X) [ Us T' )� l *� Yw 8� �) U �" D� Q� : 6 ]� N L i� [ W u� o k �� ̈́ �) | � ܄ � � �� � �� � � �) " �� � �� �w ڃ * ] �� � � � � � �� * H �� � � � � * 6 � � � -* " 6* " ڃ � � �} `* v �� �} � � �} ~ A 9 ~ k c ~ � � %~ � � ̈́ g* � � ` ܄ W S 2~ � { 7~ j f E~ �* � F~ � � �* � T v@ �{ � �* �� � � � � � � � � . & � S K � � � ̈́ �* � U ܄ � � � � , ( � ? ; �� >+ � "� �� R N �� e a �, � U~ Tv �, U~ Tv Q0 � �+ n f � v t � �+ U � � ~ � � � , 2 U~ QshRsh �+ � ~ U~ �+ � � U~ �, U~ T 0A (� , � )� � � �, � T @ �w �w uw ly U~ - � �o a~ � � n~ R H z~ � | �~ M = �~ � � �~ � � ̈́ >- � > � ܄ � � �~ � �~ � � �~ � � �~ � � �~ 9 + �~ ��}�~ ��}�~ ��} s k m� �- �S ~� � � �� � � �� � � ( ' O - G. o � U| T 8@ _. o � U| T @@ w. o � U| T I@ 3 � U��|Tv Qs R" 6 o - U| T P@ &6 o U| T Y@ 0� �. 7 �* W� ( $ K� E A ?� ^ T 7 c� � � n� � � y� G z� � � �� �. h �� � � �� �� W �� % # / ( U~ Qv ; g 5 @ ��}M 9 - ڃ �/ �/ �� � i g � u q 0 ' ߁ 1 � �� � � � �� � � � � � � � � � � � $ !� � / "� 9 5 �2 � Uv E1 � G Uv M1 � _ Uv �1 � w Uv �1 � � Uv �1 � � Uv R@?$ �1 � � Uv �1 � � Uv Q �1 � Uv T| Q1 2 � Uv P2 � 7 Uv k2 � ` Uv T} Q} R3 �2 � Uv T} Q} R1 �/ y � U��}T0 0 t � Us I0 ~ � U��| ]0 � � T a@ Q| g0 � U1 �7 � �7 T| ڃ �0 �0 �� � J H � T R �0 ' � � ` ^ 9� �4 � � � _� o i R� � � E� � � � l� z� I5 � @ �� < 6 �� T R �� a ] �� t p � �� � � ǁ Ӂ � � Y5 � � T w@ �5 � � U| T~ Q} R0 �5 � � Uv T y@ Qs R~ �5 � � U| T} �7 U| Q0 �4 ~ 1 U��| 5 � T U| T} Q0 85 � � Uv T XA R} X~ Y��}� U6 � U| T0Qv X0Y4 �6 � � U��| �6 � � U~ �6 � U~ �6 $ U~ T~� �6 < U~ �6 � m U~ T u@ Q1R@?$ 7 � � U��| x7 � � U��| �7 U��|Q0 �. . � U~ T [/ t � U~ �0 t U��| �2 � 3 U T "@ n4 � K Us �4 � i Us Q} �6 � � U��|T��|Q��|R} g7 � � U��|Tv Qv R1 �7 U��|T �@ [ p3 � F \ � � h �3 s i � � u � h v � � �3 � Us T; �3 � � Us T| Qv �3 � � Us �3 � � Us T| �3 � � Us �3 � � Us T| �3 � Us T| �3 � + Us 4 � Us Tv �7 : �7 � T @ ({ { �z �z �z �z Zy Hy 2z �y y �{ Nz �x �x �x jz 1y i{ C{ z �y �y �y �y mx x �w �w 8x �x �x �z E} �7 c �� Q} � � ^} " j} c ] v} � z �} � � �} 2 & ̈́ �7 � � � ܄ � � �} � �} � � �} � � "� N8 P 1� =� , & H� & I� H D T� `8 7 U� Y W `� c a �} @ � �} o k ?9 � Us T| 9 � Us �} �8 � �} � ~ S9 � U�TT v@ �{ �� `9 a �� �� � � �� � � à � � � � �� � �9 ~� B� & $ 6� 8 6 *� B @ �9 / T~ Q} z9 � � U~ �9 7 T} �� � �� Bw �� �9 � ��  U K ς � ڂ � � : : Us /: . X Us Tv A: � ~ Uv T| � s i: � Us {: . Us Tv �| �: � � �| � � �| � � �| � � �| } $ " } / - #} �@ �0} Z � 1} O M ]; k Uv T ` Q( l; � � v �: � U ��Tv Q �@ R �@ X �@ �: � Uv T �@ Q 0) �: . Uv T �@ Q �) ; ` Uv T �@ Q �* ; � Uv T �@ Q - 3; � Uv T �A Q `* I; � Uv T A Q �7 �; U�U �| �| g| P| �v ` � � � � j t >�! } ( � l % 2 �1 � � & �' � ( % ?int e \! *1 � �4 �8 � �1 G �1 \ �8 �8 �1 ?$ �8 � �} - �e 1! �} �* �} @ � � R � } � � } �) �} %7 �!} = � = I @� � O� �) l �* � W �8 !� � �5 � 8 � 8 �. � 2 � R. � � , �1 = � 8 � 1 � � ! D � e � � � � D � � � � � ' " � h #� pa& $� xp( '� � � � 8 � u , l � � 8 D � P *!� \ R � � F � Y ^! q �/ 6 } F 8 _ � { �4 * � ! e @� "� H F � 8 �& F { ;� � � e �8 � 89 � !8� �2 :� �# ;� !? � A e &! B e � C� !GM �2 I� �# J� � K� ! O� �2 Q� �# R� 8 S e �8 T� �' U� !a� � c � 9& d � ^� � e� [ gq ! Y 2 [ � ; ]R �( h � !l3 �9 n} i$ o e !td v � B1 w e R x1 p3� Z 5� � <� f0 D� ,_rt L �0 VM �, i� D: p �5 y3 e � 8 !�$ ) M( & e G ( e * e W 0 e . { d |� : &E e 8 Y J J A � % o* �� �- �a �8 � � m = � 8 m � �+ � � � ~ � � � �- � � � � � � � �/ �F m2 �a �+ �� &0 �� � �_ K 2$ � G a �4 � � 68 D � U U � � � � �% � � � �& � � � �1 � � � 5 � ' � 1 � ; � E � O � Y F c � m � w � � � � � � � " � B '0 � !� � { � � � 6 � $ �6 � 4 $ 8 4 8 D 8 78 �_ � � � o 8 �7 �@ �6 � - $ � r ,� �6 -� � / � �$ 0 � W 2 e $� 4 � ( 9 � 0�. = 8�! ? @� J� H�* K� X� L� h#* Y@ x , P 8 'tm 8� w e p e � e � e � e Y. e �/ e S e �& e U5 } (e � 0 K. - �3 8 �5 E 6 e �3 � b| � d 8 � e E L fe S ge $' h E � �� n5 8 �7 E � e �* 8 D� �4 F 8 �+ G E ^8 He = 8 � (DIR 0 "IV o} "UV p8 , "NV �G ! � f y U "OP h r 'op (�D � ��/ L ��/ / �ZF ��D �% �=/ � �=/ �. �=/ �7 �=/ G% �=/ #5 �=/ � �=/ �, �=/ x/ �2/ "( �2/ # "COP i P 5cop X�� � ��/ L ��/ / �ZF ��D �% �=/ � �=/ �. �=/ �7 �=/ G% �=/ #5 �=/ � �=/ �, �=/ x/ �2/ "( �2/ #� �u/ $ ��D (�5 � 8 0} � _/ 8� � _/ <�! ��K @,) � �K H- � _/ P t o � � `�� � ��/ L ��/ / �ZF ��D �% �=/ � �=/ �. �=/ �7 �=/ G% �=/ #5 �=/ � �=/ �, �=/ x/ �2/ "( �2/ #\ � �/ (3- � �/ 0�$ �D 8�. _/ @f dF H� �F P�' �/ X � s � �7 P� � ��/ L ��/ / �ZF ��D �% �=/ � �=/ �. �=/ �7 �=/ G% �=/ #5 �=/ � �=/ �, �=/ x/ �2/ "( �2/ #\ � �/ (3- � �/ 0? � �/ 8 � �/ @Z � �/ H ; ~ <h �r�" �) #�/ -Iop $�/ �* %�/ � '�/ �6 (�/ *�W (u ,I/ 0� -I/ 4�7 /�W 8� 0I/ @� 1I/ D� 3�/ H53 4a P� 5a Xi% 6a `q 8_/ hI :�W p95 <�W x� =�W �� A2/ � C, �0, E�/ �6 H_F ��. KI= �� LI= ��) N�/ �D6 O�/ �-5 ^=/ �� h2/ �%9 i2/ �/ j�/ ��$ v2/ ��( }'/ �:6 ��/ �� ��/ ��) ��N � ��/ �%+ ��W ��. ��/ � (6 � � ��/ � ��/ � �I= 0 ��W � ��W ( # ��D 0 � ��" 8 � ��" P � ��" h � ��" � & ��. � o ��. �6ISv ϟ/ � O ��W ]+ ��/ 6Ina �U � �o �! ��/ � � ��/ �6Irs ��/ � � ��/ � ��/ � � ��/ � F �� � �7 ��/ � M6 ��/ � �2 ��/ �d �/ �� .M 7 .M 3+ �K � �/ �t1 >2 �� �/ d2 �/ : �/ �$ �/ � �/ �3 8 (q U 0�' =/ 8^4 ?2/ :� A�/ ;y B�/ <�, C�/ =_: D�/ >� H� ? K�/ @4 N�W H� e'W xO }'W �� �VW �/ �E �U8 �8 �) �_/ �x2 �_/ �� �e �3 �e �= �E �` ��/ �u ��/ ��/ ��/ �g! �8 ��0 �� �� ��/ �4: ��/ �� ��/ �� ��W ��1 �� � ��/ � ��/ ��/ � ��/ � ��/ { ��/ e ��/ ��/ G �8 I ��/ = �m � �I/ (m �I/ ,� �I/ 0>3 �e 4s ��W 8E ��/ @� ��/ H� ��/ P/ ��/ X ��/ `�8 ��/ h�2 ��/ pV( ��/ xw ��/ �D7 ��/ �z ��/ �� ��/ ��/ ��/ �� ��/ �t ��W �1 ��/ �6 ��/ �6 ��/ � ��/ �� ��/ �� ��/ �4 ��/ � ��/ w3 ��/ G �8 �: !8 � �/ 2 �/ (�$ �/ 0� �/ 8�# �N @�4 e H� e L�' 8 Ph �/ X- �/ `E �/ h�* e p( I/ t�9 �/ x�0 �/ y' =/ z� e |$ I/ � 5 #I/ �K1 $�W ��+ 3�/ �j. 6�W �� 8D � :!8 �� ;�D � <�D : =�D L& E!8 , Fe ? I_/ $� K�/ ( L�/ )� M�/ *� N�/ +$: QU ,f RU 0 SI 4�- TI 8BIan U_/ <9 X_/ @�! `_/ D} c_/ HX* d_/ L�- eE P. i8 XP km0 `d n60 h� oB0 p� q�W xx* sp/ �� u_/ �k )V c1 ��/ �. �I/ C ��D � ��D �( ��D ( �7 ��D 0 ��D 8 �4 � X @ �3 �8 � d �y � D �y � � �_/ � m0 �2/ � ��/ � �2 �2/ � * ��/ � U1 �8 � �/ �y � �9 �8 � � �y � �/ ��/ � �4 ��/ � � ��V � �& ��/ � ! �? � �e � %& ��/ � % ��/ � �- �8 � �1 ��/ , �� �0 ��/ �8 ��/ 1. ��/ � ��/ �4 �X ( N! ��/ 0 &2 �� 8 � �/ @ 40 �/ H H #X P = �D X y �D ` S/ (X h ;) �/ p � �/ x g 0 � �) -X � � -X � F �/ � �' �/ � 7 } � � #JV � W& $JV � � -JV � �% 1lV � �! 4yV � j 7�V � � :�/ � �# @�/ � � C�/ � l E�/ � /0 G2X �9 K7X T M�V �4 PcW X 8 Y<X ` � Ze h b�U p : oAX � �9 z�D � T |U � � ��D � *4 �QX � '( ��/ � � ��/ � #, ��/ � � ��/ � �0 ��/ � \ ��/ � ��/ � ) ��/ - ��/ � ��/ �# ��/ � ��/ � ��/ ( P7 ��/ 0 � ��/ 8 �% ��/ @ 8 ��/ H �6 ��/ P �( ��/ X 77 �aX ` 8 �aX � a9 ��/ ` ��/ h�* ��/ p ��/ x� ��/ ��/ ��/ �0' ��/ �4( ��/ ��5 ��/ �o ��/ ��4 ��/ �� �P �1 �P ��2 �P � "SV � # �" 'sv �N# x( �� ($ �_/ = �_/ c ��1 "AV � Y# 'av ��# x( ��3 ($ �_/ = �_/ c �H3 "HV � �# 'hv ��# x( �94 ($ �_/ = �_/ c ��3 "CV � �# �# 'cv �4$ x( �C3 ($ �_/ = �_/ c ��2 *. � A$ � �$ x( �6 ($ _/ = _/ c �4 "GP � �$ 'gp P ?% �5 �/ 0 �D ;. !8 T# _/ � _/ �0 �/ �- �/ (K/ !8 0� �/ 8�. _/ �# _/ $ D7 H "GV � J% 'gv �% x( ��2 ($ �_/ = �_/ c �R2 5io �% x( �4 ($ _/ = _/ c >4 � �% � hn�% @& r�O H5 h��& � � 2/ � � 2/ a. � =/ $ � I/ � I/ �% I/ + �N : I= � a � I/ (( �N 0 Q% � �& � 0 %' �$ o7 > *Q �2 =/ �9 = � 2/ a < �/ �- 8 ( "XPV � 1' 5xpv �w' N* ��/ B# �I7 � �U � �t7 � � �' � ( �' N* �/ B# I7 � U � �7 n6 7 � � �' � 0 I( N* �/ B# I7 � U � �7 n6 7 � �6 ( � V( �8 ( �( N* �/ B# I7 �- a f6 a _$ �/ � � �( � !��( N* !� �/ B# !�I7 ( !�U !�U � � ) � 0 ;d) N* <�/ B# <I7 � <U � <�7 n6 =7 � >�6 ( � � q) �9 h" 5* N* "�/ B# "I7 � "U � "GE ) "�/ �+ "iE (� "�E 0# "�E 8]# "8 @� "�E H� "!8 P�1 "_/ X�1 "8 \�0 "I/ ` � � B* � � eM+ N* f�/ B# fI7 � fU � f08 n6 g7 � iH2 (U: vT8 0�& x 8� y @�& z H�4 { 8 P�* | �/ Xh } 8 `�5 ~ �/ h;/ 8 p� � �/ xh- � = �� � 2/ � /% � Z+ 1 @ �+ � �P 26 �P u �P 3 �P �1 �P �8 Q (�1 %Q 0N �P 8 "ANY � �+ Cany ��, � � � � ��/ S3 ��/ ��/ � ��/ � ��/ ��/ � �8 � �E l1 � I/ C � _/ 6 � � � , 4 � } �) � �/ � � �/ �3 � �/ 2 � �, �. y- h z�U 4 {J � | � � - �- 0~- I$ ��U � � , [ � , � ��U ^ ��U g ��U ( � � �- ( ��- U+ ��/ � �, J- ��/ � ��/ ] ��/ } � �- # /. ~ # a B #&�D $ #' _/ 8, #( _/ "PAD � N# � H. \ (#+�. � #, a 9 #-E � #. a K #/�D v #0 _/ � � �. � 0#L'/ : #M8 �. #M�/ s #M%E D, #M_/ l) #M_/ w$ #M_/ �5 #Me $f' #M2/ (� #M2/ ) (I8 $�? (U8 $� (U16 $�% (I32 $�e I/ 0I/ (U32 $�1 _/ 0_/ $� _/ ] � ) &�/ � �/ �" �/ 0�/ �/ �/ ?% N# �/ �# g � &�/ �/ � �/ = 0 8 � %<0 � � %> 0 0 z %Q 10 l � &45 &5N0 S0 &h0 e h0 � �/ &;60 ; ) '��0 �3 '� I/ �# '� 8 �# '� �/ �( '� �/ ) '�y0 71 �41 ;! 0 � H2 � m# &. l � � � � � A �6 ��0 41 (HE �P1 'he ! �1 e/ !$ >2 A !% D7 !)LK (HEK ��1 'hek !-�1 �) !._/ � !/I/ !/ !5�/ �92 �8 � � � �, : �< � ��/ �5 ��/ $ �92 � �C2 �H2 >2 E1 �$ 0 H2 ��2 �8 � � � �, : �< � ��/ �5 ��/ $ �92 � �C2 �H2 �( �C3 �8 � � � �, : �< � ��/ �5 ��/ $ �92 � �C2 �H2 d) ��3 �8 � � � �, : �< � ��/ �5 ��/ $ �92 � �C2 �H2 I( �94 �8 � � � �, : �< � ��/ �5 ��/ $ �92 � �C2 �H2 �( �4 8 � � , : < � �/ �5 �/ $ 92 � C2 H2 5* A5 8 � � , : < � �/ �5 �/ $ 92 � C2 H2 & �(n�6 N* (o�/ B# (oI7 � (oU � (o�9 � (p!n: �5 (q �9 (�# (r �/ 0�5 (x _/ 8o$ (y _/ <� (z a @ ({ a H� (| U PK3 ( s: Xy, (� � `[3 (� _/ h1 (� _/ l� (�x: p� (� E x�' (� _/ � (�_/ �& (�_/ $� (� 8 �� (��/ ��% (� a �.9 (� a � (� a � (� a �> (� !8 � A5 8|& �7 � � < A. � �/ i+ � u/ �8 � �/ 8�6 �D7 �% � �+ � , 8 � D7 f � �/ �1 8>: �o7 � � o7 u! � U �& ��7 � �U � ��6 �7 � U � �6 �7 � U � �6 <8 � <U � <�6 �, A _/ &!8 �/ !8 �# 8 �- fT8 � fU � f�6 sx8 �# tx8 !4 u � (�8 � (2/ ^ ( 2/ �+ ( =/ ( }8 d ((( 9 � () a �! (* a � (+ �/ � (, �/ (- a d �(/59 o/ (0 2/ 9 (1 59 �8 E9 8 \, (<z9 �, (= a -end (> a ^ (E a \, (FE9 4$ �9 (o�9 � (oU � (o�6 � h(�i: �5 (��: � (�; � (�S; 32 (�l; � (��; �9 (��; (] (��; 0k7 (��; 84 (�< @�$ (�7< HQ (�l; P�2 (�Z< X�5 (��< ` �9 i: 9 z9 & (�A5 � (��: �- (� E � (��: a w) (��: �9 �: �/ �/ _/ �: I/ ; �/ �9 8 8 8 a �/ � _/ �: 8 N; �/ �9 �/ � 8 8 k/ N; �: ; �/ l; �/ �9 X; &�; �/ �9 q; &�; �/ �9 U/ �/ �; &�; �/ �9 U/ �; # �; �; I/ �; �/ �9 �; U/ �; �/ < �/ �9 �/ �/ k/ �; �/ 7< �/ �9 �; k/ < � U< �/ �9 U< ~- << �9 �< �/ �/ e �/ n: �9 �< _/ _/ �/ _< X(� D= rex (� D= �. (�I= � (��/ � (�8 �% (� U .9 (� U ( (� U 0 sv (��/ 8$ (�o7 @ pos (� a H� (� 2/ P }: � �+ (��< (� �= �+ (� �= � (� �= J (� 7> � (� 8 N= � �(��= - (� e � (� 8 � (� 8 sr0 (� �? u (w�C �= <1 x(�7> � (�zD 7 (�7> hh (�"7> p �= �) (�[= � (� I/ (�o> _5 (� �= (� �> _5 (� �= 1 (� _/ �' (� _/ cp (�I> (�? _5 (� �= 1 (� _/ �' (� _/ cp ( I> � (? �8 @(�? _5 ( �= 1 ( _/ �' ( _/ cp ( I> �( ( _/ � ( �/ � (�? me (? (� ( �? 0~ ( _/ 8 ( =/ <; ( =/ > =/ 2/ @(G@ _5 ( �= . ( �= �( ( $�= � ( �9 cp ( I> �7 ( I> $� ( _/ ( B (!? 0� ("8 8 0(%�@ _5 (' �= X0 (( I/ �* () I/ � (*2/ �, (+8 end (,8 me (-? ( (0�@ _5 (2 �= � (3 �= 3 (4 �/ �8 (5 8 (8A val (9 e 8(>�A _5 (@ �= . (A �= me (B? B (C? cp (DI> � (E �/ $ (F e (� (I e , (J 8 0 ((M B _5 (O �= # (P �= cp (QI> �7 (RI> (S 8 K0 (T I/ s (U I/ $ `(X�B _5 (Z �= c1 ([ e c2 ([e cp (\I> 1 (] _/ �' (^ _/ ]* (_ I/ � (` I/ � (a �/ $ A (b? ( B (b? 0 me (c? 8j4 (d�B @� (e�B N 2/ �B 8 h(h�C � (i _/ cp (jI> 1 (k _/ �' (l _/ c1 (m e c2 (me �- (n 8 ] (o 8 � (p e ( min (q e , max (qe 0 A (r? 8 B (r? @j4 (s�B H� (t�B V h(�mD �) (�<> �+ (� N= 1yes (�V> (� o> � (�> R& (? � (#�? �' (.G@ :( (6�@ P (:�@ # (KA �5 (V�A � (f B (u�B � (x�= mD �D 8 1 (��= )D8 �% � #a !#!�D #"�D = ## �D C #$ �D ;. /. # E ~3 # E _ #%E �D �D E �. #MGE �, #M�/ X #M!8 "iE � "U � "�6 "�E �( "�/ � "�+ "�E "�/ � "&8 "�E %) "�/ �1 "D7 "�E { "+8 9 "� � ?F �7 ��D ,sv ��/ ,iv � ,uv �, ,pv �8 � �a �1 ��E �/ ZF �/ KF ?F �F � �/ �3 �D �! �/ �F � �/ �$ �D � 0*1"G � *3 8 �# *4 8 _0 *6 � N5 *7 � � *8 8 E *9 8 1 *: 8 ( � +*dG �% +, 8 � +- 8 � +. � �0 +/ E =n, �,H�G E& ,M�G � ,V�G � � ,[�G +* ,b�G � ,i= � � ,n�G = �G 28 = �G 28 � = �G 28 � = H 28 �w K7 H-+�H � -- 8 � -. 8 � -/} � -0} � -1} X -2} (x- -4} 0� -6} 8�8 -88 @ D�.� K .�8 � .� y � .�K ~ .�8 K .� y � .�"G (� .�8 H<2 .� y PJ .� K XN .�- `� .�8 �� .� y �g .�!K ��. .�e �U .�8 � .� y ��+ .�� �) .�8 �q .� y ��% .�&K ��) .�e �u5 .�� �t6 .�8 .� y � .�+K � .��F � .�8 H4 .� y P# .�0K X7 .�| `�# .�8 �?( .� y �C9 .�5K �& .� H �& .�8 �m .� y � .�:K �� . P ��( . P 0p' ."8 hW .# y p�) .'8 x(8 .( y ��' ., e � dG "G - � � �F | H & .-�H !&nK �- !'�/ � !( y � �K 7 !�K �2 "� & # e �^7 $ �/ �C %=/ ��0 &a � nK + )nK � � �K * U �K �K $ 0S]L � T �/ �9 UI/ = W �D cv X !8 �( Z I/ �6 [ �/ ( 5 0`�L � a �/ �9 bI/ = d �D cv e !8 gv g �/ �0 h �/ ( � 8�.M � � �/ �9 �I/ ` � �/ �$ � �/ v: � �/ cv � !8 (�, �.M 0 �K �VM 1svp � �/ 1gv � �/ �|M ary � �/ ix � ��M , � I/ ix � ��M cur � end � ��M cur � �/ end � �/ �.N 1ary �VM x �|M . ��M �2 ��M �7 0��N � � �N v# �3M ( ��/ �, ��M W � �D ( � N, ��N �6 ��/ �( � �/ 8�N H �K 0 ]L � �L A0 .N �% �N D �N 6 X.�O �2 / 2/ � 0 2/ � 1 =/ 2 I/ � 4 a b* 5 a . 6 8 b 7 �/ �* 8 �/ ( # 9 8 0# : 8 8� ; 8 @b < � Ht =�9 P ho�O � p�% 6 qO )+ 8 �P u �/ F �P � �P (1 �P 6 I/ � I/ $K I/ (+ I/ ,� I/ 0 �% �O '% !�O e �P �/ �/ o7 �P _/ �P �/ �/ o7 �P e Q �/ �/ o7 �/ � I/ �P e %Q �/ o7 U< Q M+ !/ mQ -val / �0 4 / R v / I/ / !8 " //Q � (/�Q � /�Q � / �/ D! / 8 �6 / 8 � / �/ yQ / yQ =�7 �/"�U /&�U q- /'�0 �$ /(e Q /+e x /-�U l /.�U -ps //�U (� /0e 03 /4 I/ 4�* /5 I/ 8A /6 I/ <N /7 8 @L /8 8 HD* /9 2/ P7# /: 2/ QV /< 2/ R�' /= �/ S(# />�/ T� /? 2/ UV /@ �/ X- /A �/ `) /B �/ h~ /C =/ p�! /D =/ r� /E I/ t� /F �/ x� /G I/ �b /H I/ �� /I , ��7 /J , �P9 /K�/ �t /L 2/ �� /M =/ ��# /N I/ �J+ /O �/ �L) /P �/ �� /Q�U �� /R �/ �G! /S 8 �\6 /V 8 �Y6 /W 8 �w /X 8 �o9 /Y 8 �� /Z 8 �` /[ 8 �� /` u/ ��+ /a =/ ��! /b 2/ �� /c 2/ � H' /d �/ I /e H2 9 /f �/ /h �U � /i �U @ ,3 /j 2/ T �! /k 2/ U >+ /l 2/ V x /m 2/ W � /n �N X /o � ` �7 /p u/ ` & /q u/ d �0 /t, h y9 /u, p � /v= x /w�/ y � /y�/ z /{=/ �� /|=/ �� /}=/ �(- /~=/ � �Q mQ �Q �0 �U 8 I/ �U 8 �7 /�Q �, �U � �U �$V h ��/ 7 �$$V h �$$V �U � &6V ;V e JV �/ � 'WV \V &lV �/ �/ ~ (6V d3 *�V �V �/ �V �/ �/ � +�V �V &�V �/ E� 1 y�V � " 3 �9 �, * �6 H W pad W �" 'W 8 � &4W 9W &IW �/ �/ � :&8 e >4W �1 B�V I�W fn J �/ ptr K � )/ LpW �+ I/ �P �D mD �U 8 �W 8 � e �W 8 �W _/ � X 8 8 X 8 - X �/ ?K $0 %' � � �/ QX 8 " = aX 8 �/ qX 8 71 0>DY � � � � � � � , s �& ? v8 � �( T2 01 T s% |+ . T' U- �% @ � 7 4* �& �* � �3 71 1[ U �3 � � �3 3 - � 5 M � ' \ � 5 N: Z) � " � � M: Y) � ! � � 7 �' � !s+ "� #' $� %� &�4 '�& (� )S4 * +�$ ,� -B .R$ /A 0Q$ 1x. 2y 3w. 4x 5� 6( 7� 8( 9� :�$ ;�. <�. =� >� ?� @�8 Ak B�# C|4 DW Em F G� H�- I�8 J� K !(2 ~[ � 2! �/ 2" �/ 6 2$ 8 � 2% I/ z 2& I/ a) 2(X r4 2)X �8 2+[ ! ,e 2.�[ 2/�[ -sv 20 �/ 6 22 8 � 23 I/ z 24 I/ h 26�[ �[ 0�[ �[ �8 3�y \ � �& 4P �/ 1\ �/ b \( 4� �/ R\ �/ �/ I/ �' 4�e n\ �/ �/ � 4� X �\ �/ #C l �\ � � 4�e �\ �/ H2 * 4} 8 �\ �/ �/ M2 I/ 3� %�H2 �\ � � # �)] �/ I/ H2 �/ I/ I/ �/ U �5 4-� J] �/ �; l S 4��/ k] �/ �/ 41 #D4 �] �/ �/ #a � �] �/ #;- N�] �/ � 4dI/ �] �/ �/ Z/ | 4� �/ �] �/ � b k/ � 4��W ^ �/ #� 0 ^ �/ #( � (^ �/ 92 4�A^ �/ � 4 f8 4� �/ ]^ �/ �/ + 4< �/ y^ �/ �/ ) 4k �/ �^ �/ ' & 4� �/ �^ �/ � b #� �^ �/ �/ �/ S 4^ �/ �^ �/ @1 q& 47 �/ _ �/ �/ #^ H&_ �/ �/ ' 4} �/ L_ �/ �/ �/ a 3i %�e h_ H2 � 4 I 4�H2 _ �/ 9� 5n �_ e F0 9 �6 �_ �_ e F 31 ) e �_ �_ e #u � �_ �/ X 3� 3� e �_ � � �2 4� 8 %` �/ �/ �K U/ # �=` �/ � 4 # �Y` �/ �/ 7 W% 4� �/ p` �/ 9�3 4��` �` � �# �` ! 4s � �` � y #� � �` �/ X O � � 4g � �` y y @8 4� � a �/ X O #~ &#a �/ U/ �/ 4c� Da �/ �W y 4 4� !8 ea �/ � IW � 4(I/ �a k/ � � 4 G� 6��a $X 6��/ )cv 6�!8 ax 6� I/ :( 6� �/ sp 6� �/ _ 6� I/ 6 6�� L# 2_�a ~[ *� 6��b $X 6��/ )cv 6�!8 sp 6� �/ ax 6� I/ :( 6� �/ _ 6� I/ +�b � 6�, 6��/ 6� , � 6�' *� 6�c $X 6��/ )cv 6�!8 sp 6� �/ ax 6� I/ :( 6� �/ _ 6� I/ +c � 6��/ � 6�' * 6<Cd $X 6<�/ )cv 6<!8 sp 6> �/ ax 6> I/ :( 6> �/ _ 6> I/ L# 2��a � 2�U/ �2 2� e � 2� : 2��[ � 2��/ d 2��/ l 6N�/ +�c � 2� ' +�c Y 2� � +d W 2� �K �% 2� e sv 2��/ av 2��/ p_ 2� � *�, 6�d $X 6�/ )cv 6!8 sp 6 �/ ax 6 I/ :( 6 �/ _ 6 I/ +�d L# 2w�a 6"�/ sva 2��/ � 2��; sv 2��/ � 67' *f 6ne $X 6�/ )cv 6!8 sp 6 �/ ax 6 I/ :( 6 �/ _ 6 I/ +^e L# 2n�a � 6' *� 6��e $X 6��/ )cv 6�!8 sp 6� �/ ax 6� I/ :( 6� �/ _ 6� I/ +�e L# 2g�a H# 2g� � 6' *� 2$6f $X 2$�/ $: 2$%�[ $�2 2$7l � 2%M2 *J 2�f $X 2�/ )ofp 2(M2 $6 2?� $� 2OU/ ifp 2M2 sv 2�/ i 2 e ., ��f X 2��/ : 2�'�[ � 2�9�/ %sp � �/ %n � I/ � �W /� 2��[ fg X 2��/ L# 2��a f# 2�-kg : ��[ � � %sva ��/ � ��; %sv ��/ %si ��[ fg /6% 2�e �g X 2��/ L# ��a � � �N .�2 ��g X 2� �/ L# 2��a %sva ��/ � ��; %sv ��/ %si ��[ .�2 �=h X 2� �/ L# 2��a �5 �Bh �7 �, %pte �Gh Lh =h �, Gh .� s�h X 2s�/ L# 2s�a :cop 2s)O 6 t� � u I/ .w i�h X 2i�/ :tbl 2i/ X �5 jBh �7 j, %pte jGh /�/ 2_, )i X 2_�/ � `, %sva a�/ � a�; %sv a�/ H� 7 2/ bi $X 7 �/ 9 7" I/ � 7# 2/ /` 7��/ �i X 7� �/ :sv 7��/ /� 7�I/ �i X 7��/ I 89� �i �* 89� ] 89e � 89y J� 8� �* 8 3 8T � 8y I ~ 4 1�B H} 1�B . 1 H} 1U 1R�BUX YW .1@z H } 1U 1 1 4 1 1 U 4 1 4 1 ! .1 1R�BX!YW H} I �~ % 1R�BX Y W 1R�BUX Y W 1X Y W H}� . ?<n: ; . ?<n : ; 9 I8 : ;9 I8 : ;9 I8 I !I ( : ; 9 I : ;9 I : ; 9 I : ; 9 I8 4 : ;9 I : ;9 I8 & I : ;9 I : ; 9 I 7 I ! I/ .?: ;9 'I< : ;9 : ; 9 I k : ; 9 I 4 : ;9 I : ; 9 : ;9 < : ;9!I k 'I 4 :!2; 9 I : ;9! $ > ! : ; 9 " :!;9 I #.?:!4;9 '< $ : ;9 I %4 :!2; 9 I &' ' : ; 9! ( : ; 9 I ) : ;9 I *.: ;9!' + , : ; 9 I - : ; 9 I8 ..:!2; 9!' /.: ; 9!'I 05 I 1 : ;9 I 2! I/ 3.?: ; 9 'I< 4 5 : ;9! 6 :! ; 9!I8 7>! !I: ; 9 8 !:! ;9! 9.?: ;9 '�< : : ; 9 I ; !: ; 9! < : ;9 = : ; 9 >% ?$ > @ A& B : ;9 I8 C : ;9 D : ;9 E> I: ;9 F.?: ; 9 n'�< G.?: ;9 ' H.: ;9 'I I.?: ; 9 'I J.?: ; 9 'I $ F � 5 G ] j } � � �' �wt��J � t � � Jv8XJ. � � X � J � � u � Y) "Y f >u2JJg�~ �J<kJ �~<X�% JK% JiJ�J��..r<��=X2 ^ !��K �}#��~ X� �}� J� �X�~X �}t�J<�~J��} ��� �|�tJ�X �K �}#�. �}.�J �}<� ��~ �t�~.t �J<�~�<�~XY��� .�|��uJ ����8XJ� �tK =�{#� �{< �J �{J �< �t <uM�~� t � < J J J < X �z#tX �* �~K u�}#�<. �}� �J �}J �< �J< <u�~�� <�}J ��}��� ��� K ;K Y ;K XLt � X � J X � v� LVXJX���J. �} O vWfX Y( ��X�� - t u;/ �| �JX�|# �� �|J< �t<u��~J��~<t��~��� JZJv tK��%J��r���� <�~J� t< . Y X J �( � L � W XM �WXM �WX�>�~<�<M�~t�;���XJJX� u+ � X g O K< f�<XXJ � �Z�� � X � X<��� ��}�.���"� � � � � ��|�.�J��X �� ��f�~ X�~X J a � 9K < t y�����J�iG�Z�L�;K�L �KJ �L��J a���� � �~�r�XJ�X��X� J�~t ��<��X( � � � � B�� �r WY >X � �. Y 0Xu � �<Y(�� �� �Xs p � � � f ��~ �J�~Xt�� �b�f , � gJ � �*? G*� U$ J J�O�=J� Yt= K > JKZ!J O�X��=�� �WX� �WX� � � $ �!� � ��~���0 �s u�� Mo�& � ��~����� �|X< � � " ^f �� tX �7 �K �{#�. �{� J �� �{J< �t <u� � �{J t � �~� �| �����YsJX<X �<��{� X< J. X� J � L t X < y< < �{X �t F �~< �| ��� � � .y<t<X `9 �{ �zJ <<Y"<�"=< �.�� >� <.."S�6tK0r0r ?sK J� J Y� f �� u$ju< . hX��u< .��N 2�* $p @� N X m< YYYYY�|X=s<Y�t�|f�tX,X f ^ �� u 5 � 7 � B G :} { { � � � � R T � � � � � � ` � ) � � � � � � � � � 2 v � � � � � � 3 � � ! < � n � � ( ] � l } � j H GNU GIMPLE 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -mtune=generic -march=x86-64-v2 -g -O2 -fno-openmp -fno-openacc -fcf-protection=full -fPIC -fstack-protector-strong -fltrans -fplugin=annobin __stack_chk_fail __builtin_memcpy Ilaststatval long long int Perl_av_push old_parser subtr_ass_amg blku_oldsaveix Iorigargc Iorigargv si_errno keeper __pad0 tbl_arena_next _spent_size Iin_utf8_CTYPE_locale hostent ls_prev close_paren lex_stuff xpvgv Istatcache Icompiling Idbargs new_perl blku_oldsp sub_error_count xpvhv PERL_CONTEXT _asctime_buffer Inumeric_standard Perl_croak prevcomppad Ie_script Perl_newSV_type sv_u Ipreambleav IDBcontrol memset xpvio xpviv tbl_max Perl_ptr_table_new si_tid Imy_cxt_size blku_old_tmpsfloor Imain_root xcv_outside blku_type _PerlIO __locales TARGu_uv he_valu Iutf8_totitle _spent_struct named_buff want_vtbl_hintselem h_length op_first Idoswitches _netent_size thrhook_proc_t next_branch Perl_POPMARK block_eval s_port __in6_u in_port_t gp_refcnt prev_mark Idef_layerlist saw_infix_sigil Irestartjmpenv save_lastloc Iwarn_locale _spent_buffer Icolors mg_obj je_old_delaymagic fallback_amg multi_end PerlIO_list_s PerlIO_list_t COPHH scream_pos xpvmg Iargvgv despatch_signals_proc_t rshift_ass_amg xio_flags Isharehook tm_mday old_regmatch_state xcv_xsub nextword Iminus_E XS_Test__LeakTrace__finish Icheckav pad_1 pad_2 Imarkstack Idump_re_max_len tm_zone Istatusvalue IDBsingle utf8_substr __u6_addr8 min_offset pmop st_atim sival_int Ilast_in_gv Ireg_curpm share_proc_t Ihash_rand_bits_enabled pw_gecos need_stateinfo _call_addr long double op_private lex_formbrack SVt_LAST print_lines_around __ch sbu_dstr Irunops Ipsig_pend _ctime_buffer Icomppad_name Imarkstack_max sbu_iters internal Ireentrant_retint saved_curcop max_amg_code strcmp __blkcnt_t context PTR_TBL_t sig_seen xhv_max _protoent_size callback_each_leaked hent_hek _grent_ptr _getlogin_buffer xivu_eval_seen __locale_data pos_flags Istack_base exec Imax_intro_pending poscache op_pmstashstartu to_gv_amg group sbu_strend smart_amg re_scream_pos_data_s cop_stashoff s_addr st_size sge_amg Iperldb lastparen si_addr_lsb Iinplace __locale_t _pkey Perl_pop_scope tm_min IDBline want_vtbl_nkeys sin_amg Isv_arenaroot jump gp_egv newval padname states xio_bottom_gv Iphase yylen subbeg cos_amg _asctime_size Iblockhooks end_shift sbu_oldsaveix _pwent_ptr Iosname n_addrtype lex_casemods lex_brackstack numbered_buff_STORE Iefloatsize PADLIST Ipeepp exit PADNAME Iregex_pad retop xcv_padlist_u minmod Perl_PerlIO_close sp_pwdp Iutf8_foldclosures Ilocale_utf8ness Isv_yes parenfloor Perl_do_sv_dump branchlike JMPENV Imain_start qr_anoncv Istashpad _arch my_perl Ienvgv Iperlio Ipadname_const Perl_xs_boot_epilog __wchb pow_ass_amg mult_ass_amg Iregmatch_state prev_rex Iisarev Iutf8locale tm_mon op_opt c2_utf8 sa_family_t sockaddr_inarp subcoffset svu_fp yy_stack_frame Idebstash topword Perl_safesysfree want_vtbl_ovrld reg_substr_datum si_stack xpadl_max Inomemok __uint8_t tm_hour firstpos want_vtbl_debugvar Imbrlen_ps Idiehook prev_recurse_locinput any_ptr Sighandler1_t CLONE_PARAMS Icompcv padnl concat_ass_amg lex_repl timespec PerlInterpreter xpadnl_max_named ILatin1 Isighandler1p st_nlink Iminus_F re_eval_str Iscopestack_ix filelen sp_max Iscopestack_max iter_amg Iminus_a any_pvp Iminus_c want_vtbl_arylen_p Iminus_l Iminus_n Iminus_p Iargvout_stack Iinitav Perl_newSVpvn Perl_newXS_deffile sin6_family tm_yday tbl_items Perl_ophook_t cache_mask firstchars xpvlenu_rx logfp Imaxsysfd Ilocalizing Isighandler3p lex_shared servent _crypt_struct_buffer rxfree ncmp_amg pw_name sp_lstchg curly _getlogin_size nomethod_amg Perl_sv_gets add_amg Iunicode blku_sub qr_package neg_amg Irestartop ICCC_non0_non230 gofs __mask_was_saved PERL_PHASE_CONSTRUCT Ilastgotoprobe cop_line Isecondgv __locale_struct Isavebegin want_vtbl_vec initialized XPVAV to_av_amg STRLEN exitlistentry abs_amg op_ppaddr xpadnl_alloc Icheckav_save Idebug_pad __jmp_buf_tag concat_amg lex_flags set_stateinfo Iendav blku_oldscopesp Iutf8_idcont Icomppad_name_fill my_op IHasMultiCharFold __mbstate_t tmpXSoff XPVCV Perl_savetmps mark_stack_entry regnode Iperl_destruct_level si_cxix mg_virtual Perl_PerlIO_stderr padnamelist interpreter PMOP Istashpadix Perl_xs_handshake st_uid longfold sp_min xcv_xsubany PADOFFSET sbxor_amg sbu_rflags xpv_cur xpadn_flags Istderrgv xio_page_len perl_memory_debug_header Iin_clean_all si_type mark_name Istashpadmax old_regmatch_slab __ino_t reg_substr_data lex_super_state _grent_struct xcv_root_u curlym setting boot_Test__LeakTrace Icustom_op_descs si_prev XPVGV _addr_bnd sp_namp lex_starts svend Isavestack Sighandler3_t si_code Imodcount prev_curlyx Isortstash Istdingv svt_local sp_warn Perl_SvTRUE Icustom_ops sbor_ass_amg CHECKPOINT XPVHV any_av _grent_buffer sne_amg XS_Test__LeakTrace__runops_installed last_uni XPVIO sp_expire XPVIV __uint16_t minlenret Iofsgv Idelaymagic_gid xcv_gv_u Iunderlying_numeric_obj Icollxfrm_mult Perl_gv_add_by_type tbl_arena_end Isavestack_ix want_vtbl_defelem sockaddr_x25 SVt_PVAV sin6_flowinfo xmg_magic svu_gp any_dptr intuit Ibody_roots si_sigval hek_len Icollation_ix tokenbuf op_nextop line_t Perl_sv_setuv_mg mgvtbl Iutf8_xidcont si_cxstack yyerrstatus Siginfo_t _hostent_ptr sbu_rx xcv_padlist svt_get _Bool svu_iv XPVMG sbu_rxtainted seq_amg div_ass_amg op_moresib xpv_len_u Ipatchlevel Perl_call_sv _pwent_struct nextval svu_pv any_gv not_amg Ihash_rand_bits sbu_orig _servent_struct __gid_t Iparser cur_env xpadlarr_dbg stack_max1 my_ptr_table_free_val runops_proc_t any_hv Ipadlist_generation SVt_PVFM xpadnl_max Idefoutgv _lower Istatusvalue_posix _pwent_buffer Iutf8_tosimplefold __ctype_tolower siginfo_t Perl_newSViv any_iv sv_flags Ichopset Irpeepp oldcomppad sbu_rxres SVt_PVGV Iincgv Perl_newSVpvn_flags si_markoff xpadnl_fill want_vtbl_arylen tv_nsec nexttype PerlIO_open sig_slurpy want_vtbl_backref Icurpm_under SVt_PVHV lshift_ass_amg Sighandler_t svu_hash ISCX_invlist svu_nv sband_amg si_cxsubix lex_inpat last_lop PerlIO_printf tm_sec sockaddr_ax25 ptr_tbl_arena SVt_PVIO SVt_PVIV filtered Ilastfd want_vtbl_collxfrm Ieval_start XS_Test__LeakTrace_count_sv ls_linestr Perl_warn PADNAMELIST SVt_PVCV PERL_PHASE_START __src xcv_hscxt any_u32 _ctime_size repeat_ass_amg op_pmreplrootu Perl_ptr_table_free Isavestack_max Ilocalpatches report_each_leaked Isv_root SVt_PVLV p5rx op_next __saved_mask svu_rv copline sockaddr_eon any_op Icurstack SVt_PVMG Ipadix_floor Perl_push_scope si_status xpadl_arr h_addrtype _strerror_size Idelaymagic_euid bufend lex_inwhat any_pv atan2_amg xnv_nv sin_zero Iopfreehook ssize _protoent_ptr Iunitcheckav svu_uv PerlIOl sgt_amg to_hv_amg Isetlocale_bufsize protoent mg_len Imemory_debug_header SVt_IV Itop_env want_vtbl_sigelem __blksize_t Perl_sv_setiv short unsigned int _spent_ptr bool__amg Itmps_stack Perl_safesyscalloc yy_lexshared offs any_sv want_vtbl_substr lineno last_cop Isv_undef Ipsig_name LEXSHARED clone_params perl_drand48_t Igensym Iregmatch_slab op_redoop rsfp _hostent_struct start_tmp xio_fmt_name svt_len cop_hints __len h_name Ierrors xpvlenu_len h_aliases _hostent_size op_pmreplstart hent_refcount saved_copy lex_sub_inwhat any_uv Itmps_floor Istrxfrm_is_behaved __wch xpadl_id dec_amg int_amg Ibasetime Iop_mask Isighandlerp unreferenced Isignalhook xpadnl_refcnt XS_Test__LeakTrace_CLONE loceol IUpperLatin1 xio_ofp __value _hostent_buffer cop_seq multi_start op_pmreplroot SVt_NV IDBtrace maxlen pre_prefix op_targ Ibeginav je_ret resume_state Isv_consts pw_dir lex_casestack op_lastop invalid_mode Isub_generation blku_eval float want_vtbl_isaelem __count unsigned char Perl_ptr_table_store si_cxmax multi_open Perl_gimme_V _kill st_rdev LOOP ILB_invlist SVt_PV want_vtbl_dbline REENTR Imess_sv Iglobalstash Imin_intro_pending expect oldloc Icollxfrm_base want_vtbl_envelem copy_amg Iutf8_perl_idcont cx_blk Istatname RETVAL modulo_amg xnv_u __uid_t sin6_scope_id blku_gimme XSUBADDR_t st_ctim recheck_utf8_validity Iutf8_tofold xcv_root ISB_invlist block_format in_addr_t op_sibparent modepv old_namesv log_amg xpadn_type_u IAssigned_invlist peep_t make_leakedsv_list Iinternal_random_state Isv_no minlen callback __off_t perl_phase Iin_clean_objs Isv_zero PERL_PHASE_DESTRUCT in_pod Perl_stack_grow gp_io Imultideref_pc Iors_sv string_amg xpadn_protocv XS_Test__LeakTrace_END Ievalseq Iunlockhook regexp_engine mg_flags subtr_amg Icurstash gr_passwd Perl_markstack_grow _gmtime_struct gr_gid want_vtbl_checkcall my_cxt_index Perl_safesysrealloc si_overrun __clock_t SVt_NULL ls_bufptr Ibeginav_save __uint32_t Iorigfilename xmg_hash_index last_lop_op cop_warnings Icop_seqmax op_pmtargetgv form_lex_state Istatgv Idestroyhook st_blocks max_offset GNU C17 11.4.1 20231218 (Red Hat 11.4.1-3) -m64 -march=x86-64-v2 -mtune=generic -g -g -O2 -flto -ffat-lto-objects -fexceptions -fstack-protector-strong -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection=full -fwrapv -fno-strict-aliasing -fPIC -fplugin=annobin sbu_m sbu_s save_curlyx Icomppad sub_no_recover lex_dojoin xmg_u old_my_cxtp gp_cvgen xcv_file countp SVt_PVNV itervar_u gp_flags xiou_dirp _servent_buffer paren_names Iregistered_mros si_uid pw_passwd Iin_some_fold sqrt_amg lex_allbrackets opval Icurcopdb block_sub pos_magic gp_file_hek sv_refcnt sockaddr_in6 __nlink_t tbl_ary sband_ass_amg xav_alloc si_fd nparens xpadn_refcnt scmp_amg Ieval_root old_eval_root named_buff_iter st_gid Idowarn yychar Ifirstgv rshift_amg mg_moremagic op_pmoffset op_pmstashoff Inumeric_underlying_is_standard PERL_SI MGVTBL leaktrace_runops op_static MAGIC Perl_sv_newmortal Itmps_max want_vtbl_pack sockaddr_ipx Ithreadhook blku_givwhen gr_name op_type Iutf8_perl_idstart sublen blku_oldmarksp rEtV xivu_iv _netent_ptr want_vtbl_regexp Ipadname_undef preambling Inumeric_underlying _upper cx_u output IDBcv trie Ilockhook __ctype_toupper Perl_newRV _xnvu xio_lines_left compflags sockaddr_iso want_vtbl_utf8 Iin_load_module xio_page Perl_newSV sigjmp_buf pow_amg want_vtbl_hints tm_isdst div_amg Ilaststype __ctype_b h_addr_list Iutf8_charname_continue in_my_stash want_vtbl_regdata xpadn_len _strerror_buffer add_ass_amg dummy Iunitcheckav_save si_stime lastcloseparen short int ifmatch Perl_mg_get Idumpindent Ioldname preambled op_code_list xhv_keys itersave sbxor_ass_amg IAboveLatin1 Iutf8_mark _servent_size si_signo IDBgv Perl_sv_2bool_flags __names sv_any blk_u xcv_start accepted gvval IWB_invlist olddepth Iutf8cache _localtime_struct _bounds prev_eval Ipadix defsv_save want_vtbl_lvref _netent_buffer xcv_stash YYSTYPE xcv_gv cop_hints_hash Icustom_op_names lex_sub_repl sle_amg usedsv_reg xpadn_high re_scream_pos_data hek_hash _ttyname_buffer Iknown_layers _netent_errno Itainting Icurcop Istack_sp __ssize_t any_bool regmatch_info_aux PERL_PHASE_END Icollation_standard __glibc_reserved want_vtbl_taint lex_defer xmg_stash Iorigalen sbu_maxiters sockaddr Idebug refcounted_he Icurpad __time_t st_mtim want_vtbl_uvar s_proto sbu_targ __dest logical Iforkprocess lex_brackets xio_top_gv Iutf8_tolower Perl_newRV_noinc blku_oldcop Icurstackinfo Istart_env lex_fakeeof lex_sub_op stashes Istashcache xnv_lines mult_amg want_vtbl_packelem p_aliases _netent_struct in_my next_off xivu_uv sin_port Imodglobal sockaddr_at regmatch_info_aux_eval xcv_start_u want_vtbl_env basesp Igeneration IGCB_invlist Istrtab xpadl_outid xpadn_low block_givwhen regexp_paren_pair crypt_data pprivate cv_flags_t cur_top_env xpadn_typestash Iin_utf8_COLLATE_locale XS_Test__LeakTrace__start state_u PERL_PHASE_RUN _sigfault op_spare lex_op st_ino cop_features __pid_t parsed_sub op_last Perl_free_tmps proto_perl want_vtbl_regdatum xio_type yylval sp_inact sockaddr_dl xav_fill hent_val Iorigenviron Idelaymagic_egid gp_av ftest_amg scream_olds mg_ptr maxpos sa_family ptr_tbl Inumeric_name lazyiv _sifields want_vtbl_pos SVt_REGEXP Ipsig_ptr gp_cv xgv_stash netent tv_sec tm_year blku_u16 Iprofiledata sbor_amg __sigset_t gp_line Imainstack Icurpm op_pmflags st_blksize xpadn_ourstash ptr_tbl_ent _hostent_errno op_slabbed scompl_amg Isubline Iargvoutgv Iwatchaddr Idefgv hek_key PerlExitListEntry xio_bottom_name gp_form Ireentrant_buffer hent_next check_ix op_flags Iunsafe tm_wday Ihintgv Perl_my_cxt_init sockaddr_in count_sv_in_arena __jmp_buf IDBsignal Iutf8_charname_begin Ilanginfo_bufsize siglongjmp blku_format __dirstream sin_addr IXpv Iregex_padav blku_loop cache_offset wanted pw_uid _timer Istrxfrm_NUL_replacement IInMultiCharFold je_old_stack_hwm sig_elems gr_mem Ixsubfilename gp_hv Ipad_reset_pending dfoutgv _sigchld xcv_depth Itaint_warn __sigsetjmp Imbrtowc_ps pw_shell si_next want_vtbl_nonelem _syscall Iexitlist Ilanginfo_buf Isubname any_i32 Ihv_fetch_ent_mh UNOP_AUX_item svt_dup xcv_flags Inumeric_radix_sv globhook_t xcv_outside_seq Isplitstr xcv_hek svt_free sockaddr_ns long long unsigned int si_addr PTR_TBL_ENT_t Ibody_arenas checkstr _grent_size SVt_INVLIST want_vtbl_mglob Isortcop sin_family Isignals sbu_type unmark_all si_pid mg_private dupe je_buf lazysv Iwcrtomb_ps Itoptarget Istrxfrm_max_cp Ierrgv reporting_mode Perl_sv_2pv_flags inc_amg svt_clear PERL_PHASE_CHECK nexttoke Itmps_ix Isig_pending substrs any_svp intflags destroyable_proc_t Ifdpid xpadlarr_alloc ival any_dxptr n_net to_sv_amg Perl_croak_xs_usage op_pmtargetoff Icollation_name Iefloatbuf to_cv_amg magic_vtable_max _pwent_size oldval any_long xiou_any ITR_SPECIAL_HANDLING_UTF8 Perl_save_sptr lshift_amg Iexit_flags c1_utf8 newsv_reg repeat_amg Icurlocales Iglobhook sin6_port xio_top_name IPrivate_Use modulo_ass_amg Iptr_table Icolorset __jmpbuf Ifilemode __dev_t Iexitlistlen sockaddr_un numer_amg op_folded Idelaymagic Imarkstack_ptr block pw_gid tm_gmtoff prev_yes_state s_name _protoent_struct op_comp gp_sv svu_array whilem IInBitmap mother_re __val n_aliases _sigsys extflags xio_fmt_gv xpadn_gen Perl_sv_reftype cop_file Icurstname cx_subst __u6_addr16 Isv_count svt_set Idefstash Itainted Ibodytarget oldoldbufptr xav_max xiv_u _protoent_buffer st_mode savearray _xivu leave_op Iutf8_xidstart __longjmp_chk re_eval_start perl_debug_pad Istack_max svtype st_dev __u6_addr32 je_prev want_vtbl_sv Iclocktick __syscall_slong_t IXPosix_ptrs IDBsub spwd Iutf8_idstart je_mustcatch numbered_buff_LENGTH yy_parser block_loop op_savefree Iscopestack Iformtarget pad_offset s_aliases lastcp Iconstpadix multi_close riter stat herelines Imy_cxt_list IPosix_ptrs xivu_namehek _ttyname_size sin6_addr Perl_ptr_table_fetch Iwatchok p_proto Perl_sv_2mortal want_vtbl_isa svt_copy xnv_bm_tail sival_ptr mark_loc si_utime xpvav Isrand_called strlen regexp_amg __mode_t sp_flag my_cxt_t Ireplgv sa_data Ibreakable_sub_gen rsfp_filters Iin_eval suboffset __sigval_t _servent_ptr lex_re_reparsing Iutf8_toupper linestart sig_optelems PERL_PHASE_INIT old_cxsubix Icv_has_eval mg_type xpvcv Isetlocale_buf numbered_buff_FETCH Irandom_state Iscopestack_name si_band xpadn_pv Icomppad_name_floor Idelaymagic_uid Iwarnhook _xmgu _sigpoll slt_amg xio_dirpu Iin_utf8_turkic_locale cur_text blku_oldpm Imain_cv <artificial> /home/.cpan/build/Test-LeakTrace-0.17-0 /usr/include/bits /usr/lib64/perl5/CORE LeakTrace.xs string_fortified.h LeakTrace.c inline.h <built-in> __sigset_t.h intrpvar.h av.h __locale_t.h iperlsys.h string.h handy.h sockaddr.h grp.h struct___jmp_buf_tag.h dirent.h __sigval_t.h util.h overload.h perlio.h pwd.h /usr/lib/gcc/x86_64-redhat-linux/11/include crypt.h gv.h types.h mg.h /usr/include struct_timespec.h time_t.h regexp.h cv.h cop.h hv.h netdb.h stdint-uintn.h pad.h parser.h /usr/include/netinet reentr.h proto.h perly.h mg_vtable.h socket.h sv.h /usr/include/sys setjmp2.h __mbstate_t.h siginfo_t.h stdlib.h /usr/include/bits/types stddef.h struct_tm.h perl.h setjmp.h shadow.h in.h struct_stat.h S �U��\���U���\ "T"�^���T���^ "T"p^ pU "pT &nRnpr� 4pP x�]��] ��V��V ��S��sh���S��S ��P��_��P��_��P��_ �� q $ &��� q $ &���Q ��~ �� ��U��S���U� ��T���T� ��u ��p ��V ��p � $ &3$u"� ��U ��P �� ` � $ &3$q " ��(� ��0� ��P ��U��S���U� ��T���T� ��u ��p ��V ��u� #� $ &3$u"���s� #� $ &3$s"� ��U ��\ ���� � ��V��P ��S ��U��P���U� ��T��U���T���U���T� ��u ��p ��p ���U ��Q��R��Q��R ��q $ &3$t "���r $ &3$t "���q $ &3$t "���r $ &3$t "� ��p q $ &3$ t 8���p r $ &3$ t 8���p r $ &3$ t 8����Ur $ &3$ t 8� ��U��P ��p��9 )���p��9 )� ��1� ��U�� ^� � �U�� � ^ ��T��U�� �T�� � U� � �T�� � U� � �T� ��u ��~ ��P��Q� � Q� � Q ��p $ &3$r "���q $ &3$r "�� � q $ &3$r "�� � q $ &3$r "� ��~ p $ &3$ r 8���~ q $ &3$ r 8�� � ~ q $ &3$ r 8�� � ~ q $ &3$ r 8� ��U��^ �� _� � _ ��P� � P ��V� � V ��^� � ^ �� \ ��V ��S��Q��sh���S �� 0� � � U� � R� ���|���U�����|���U�����|��U�� ��|� � �U�� � ��|� � �U�� � ��| � � T� � U� � �T�� � U� � �T� � � T� � ��|����|����|����|����|����|��u ����|����|��]��V��P����|� � ��|� � T� � ��|� � ��| � � P� � S� � ��|#x#�#���S����|#x#�#���S����|#x#�#�� � S � � p $ &3$r "�� � s $ &3$r "�� � ��|#x#� $ &3$r "���s $ &3$r "�����|#x#� $ &3$r "��� ��|#x#� $ &3$��|#"���s $ &3$r "�����|#x#� $ &3$r "�� � s $ &3$r "� � � P� � ��|��|#x#� $ &3$ r 3&���P�� ��|��|#x#� $ &3$ r 3&��� ��|��|#x#� $ &3$ r 3&���$��|��|#x#� $ &3$ ��|# 3&���P�� ��|��|#x#� $ &3$ r 3&�� � P � � R� � ��| � � Q� � t 3$��|#�"� � ` � $ &3$��|#�"� ���|�� ` � $ &3$��|#�"����|�� ` � $ &3$��|#�"����|�� ` � $ &3$u�"�� ` � $ &3$��|#�"�� ��|� � S� � ��| � � ��}����� ��}��� � � 0�� �S����}��0���0���1�� � S� � 0�� � 8� ��]��]��]��]� � ]� � ]� � ] � �V��V��V� � V � � ��|��U � � Q� � t(��Q��t( � � ~ 3�� � q"�3�� � ��|##"�3��� u#"�3� � � \� � \ ���� � � �� ��_� � _ ��^��P��^����|� � P ��0���\��P��\� � 0� ��0�����|����|� � 0� ��^��S� � ^ ��] ��V��vh���V ��P ��0���\��\����� � \� � \ ��X ��R��^ ��\��\ ��S��S ����|����| ��]��]��}���}���^��Q��]��P��]��] ��P��p� ��P��P ��X ����| ��0� ��S� � S� � S ��_�� _� � ��}� � _� � _� � _� � _ ��P�� ��|� � ��|� � ��|� � ��|� � ��| �� V� � V� � V� � V� � V �� ^� � _� � ^ �� �� V� � V �� \� � \ ��P�� ]� � ] �� 0�� � S ��P��V ��P��\ ��P��\ � �!U�!�"S�"�"�U��"�#S � �!T�!�"�T��"�"T�"�#�T��#�#T�#�#X�#�#�T� � � u �"�"]�#�#] �!�!P�!�"V�"�#V�#�#V �!�!p $ &3$u "��!�!v $ &3$u "��"�"v $ &3$u "��"�"v $ &3$s"��#�#v $ &3$u "��#�#v $ &3$s"� �!�!s p $ &3$ u 8��!�!s v $ &3$ u 8��"�"s v $ &3$ u 8��"�"s v $ &3$ s 8��#�#s v $ &3$ u 8��#�#s v $ &3$ s 8� � �!U�!�!S �"�"X�#�#X �!�"\�#�#P�#�#\ �!�"S�#�#S �!�!0��!�"X�#�#0� �!�"T�#�#T �!�"R �!�"Q �"�"X�#�#X �"�"1� �#�#U�#�$S�$�$�U��$�$S �#�#T�#�$\�$�$�T��$�$\ �#�$^�$�$^ �#�#P�#�$}��$�$P�$�$}� �#�$�� � �#�$ v $ &� �#�$^ �#�$s �$�$U�$�%S�%�%�U��%�%S�%�%�U� �$�%V�%�%V �$�%\�%�%\ �&�&U�&�&T�&�'V�'�'U�'�'�U� �&�&T�&�'�T� �&�&P�&�'\�'�'T �&�&p $ &3$v"8 � �&�&v �&�&v p $ &3$ v #8� �'�'P a p��� ���� ������ ���� ���� �������� ������ ������ ������ �������� ���� ������ ���� ������ ��� � ����� � � � � � � � � � � � � ��� � � � � �� � � ��� � ����� � ������ ������ ������� � � � ���� ������ ���� ������ ���� ���� � � � � � � � � ���� � � � � � � �!�! �!�"�"�# �!�!�!�"�"�"�"�#�#�# �!�!�!�!�!�"�"�#�#�# �"�"�"�"�"�"�"�"�#�# �'�'�'�' � � � � \ � � �# �& �; @ �A B \ \ (\ 0\ ^ ` ` � ! " # � �& ' ! @' 7 ` C \ j �' v \ � � �' � � 0) g � ` � �) U � * ] � `* v $ �9 � 5 �* O - � j �7 c � `9 a � � �D � D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D D � � �; � (\ � 0\ � �A � ` � ^ � � D # 7 L ] m � � � � � � � �: � - 7 I ] p � � � � � � � � � ' 3 F V b s � � � � � � � � , = M g t � � � � � " � crtstuff.c deregister_tm_clones __do_global_dtors_aux completed.0 __do_global_dtors_aux_fini_array_entry frame_dummy __frame_dummy_init_array_entry mark_all XS_Test__LeakTrace_CLONE my_cxt_index XS_Test__LeakTrace_END my_ptr_table_free_val.part.0.isra.0 XS_Test__LeakTrace__runops_installed leaktrace_runops XS_Test__LeakTrace__start XS_Test__LeakTrace__finish XS_Test__LeakTrace_count_sv set_stateinfo.constprop.0 __FRAME_END__ _fini __dso_handle _DYNAMIC __GNU_EH_FRAME_HDR __TMC_END__ _GLOBAL_OFFSET_TABLE_ LeakTrace.c.9bc60d48 Perl_save_sptr Perl_sv_2bool_flags Perl_ptr_table_store Perl_newRV_noinc Perl_stack_grow _ITM_deregisterTMCloneTable Perl_pop_scope Perl_sv_reftype Perl_my_cxt_init Perl_newSV Perl_ptr_table_free strlen@GLIBC_2.2.5 __stack_chk_fail@GLIBC_2.4 boot_Test__LeakTrace Perl_PerlIO_close Perl_warn Perl_sv_2pv_flags Perl_xs_boot_epilog Perl_ptr_table_new strcmp@GLIBC_2.2.5 Perl_sv_gets __gmon_start__ Perl_croak_xs_usage Perl_newSVpvn_flags Perl_savetmps memcpy@GLIBC_2.14 Perl_croak Perl_av_push Perl_safesyscalloc Perl_ptr_table_fetch PerlIO_open Perl_newXS_deffile Perl_sv_2mortal Perl_mg_get Perl_safesysfree Perl_safesysrealloc __longjmp_chk@GLIBC_2.11 Perl_xs_handshake PerlIO_printf Perl_free_tmps Perl_markstack_grow Perl_newRV Perl_newSV_type Perl_do_sv_dump exit@GLIBC_2.2.5 Perl_call_sv Perl_sv_setuv_mg Perl_push_scope _ITM_registerTMCloneTable Perl_newSViv Perl_PerlIO_stderr Perl_gv_add_by_type Perl_sv_setiv __sigsetjmp@GLIBC_2.2.5 Perl_newSVpvn __cxa_finalize@GLIBC_2.2.5 Perl_sv_newmortal .symtab .strtab .shstrtab .note.gnu.property .note.gnu.build-id .gnu.hash .dynsym .dynstr .gnu.version .gnu.version_r .rela.dyn .rela.plt .init .plt.sec .text .fini .rodata .eh_frame_hdr .eh_frame .init_array .fini_array .data.rel.ro .dynamic .got .data .bss .comment .annobin.notes .gnu.build.attributes .debug_aranges .debug_info .debug_abbrev .debug_line .debug_str .debug_line_str .debug_loclists .debug_rnglists � � . � � $ A ���o � � $ K p S � � � [ ���o \ \ t h ���o � � P w � � B � � � � � ` � �# �# P � �& �& � � �; �; � 2 @ @ � � �A �A t � B B � � \ L � \ L � (\ (L � 0\ 0L � � ^ N � � ` P � ` P 0 P . 0 2P � � �P 2 �Q 0 A R P� M \� � [ 1� � g 0 �� �: r 0 V( � � $+ W � {@ e �B � % � xV � t\ � PK � �[ arch/auto/Test/LeakTrace/.existsnu �[��� PK � �[{ �H� � lib/Test/LeakTrace/Script.pmnu �7��m package Test::LeakTrace::Script; use strict; use warnings; use Test::LeakTrace (); my $Mode = $ENV{TEST_LEAKTRACE}; sub import{ shift; $Mode = shift if @_; } no warnings 'void'; INIT{ Test::LeakTrace::_start(1); } END{ $Mode = -simple unless defined $Mode; Test::LeakTrace::_finish($Mode); return; } 1; __END__ =head1 NAME Test::LeakTrace::Script - A LeakTrace interface for whole scripts =head1 SYNOPSIS #!perl -w use Test::LeakTrace::Script sub{ my($svref, $file, $line) = @_; warn "leaked $svref from $file line $line.\n"; }; =head1 DESCRIPTION This is a interface to C<Test::LeakTrace> for whole scripts. =head1 INTERFACE =head2 Command line interface $ perl -MTest::LeakTrace::Script script.pl $ perl -MTest::LeakTrace::Script=-verbose script.pl $ TEST_LEAKTRACE=-lines script.pl =head1 ENVIRONMENT VARIABLES =head2 TEST_LEAKTRACE=mode =head3 -simple (DEFAULT) =head3 -sv_dump =head3 -lines =head3 -verbose =head1 SEE ALSO L<Test::LeakTrace>. =cut PK � �[���( ( lib/Test/LeakTrace/JA.podnu ��6�$ =encoding utf-8 =head1 NAME Test::LeakTrace::JA - メモリリークを追跡する =head1 VERSION This document describes Test::LeakTrace version 0.17. =head1 SYNOPSIS use Test::LeakTrace; # simple report leaktrace{ # ... }; # verbose output leaktrace{ # ... } -verbose; # with callback leaktrace{ # ... } sub { my($ref, $file, $line) = @_; warn "leaked $ref from $file line\n"; }; my @refs = leaked_refs{ # ... }; my @info = leaked_info{ # ... }; my $count = leaked_count{ # ... }; # standard test interface use Test::LeakTrace; no_leaks_ok{ # ... } "description"; leaks_cmp_ok{ # ... } '<', 10; =head1 DESCRIPTION PerlのGCはリファレンスカウンタを用いたものなので，オブジェクトが開放されるタイミングが明確であることや体感速度が高速であることなど数々の利点があります。 その一方で，循環参照を開放できないこと，Cレベルでの操作でミスしやすいなど，問題点がいくつかあります。それらの問題点のほとんどはメモリリークに関することですから，メモリリークを追跡することは非常に重要な課題です。 C<Test::LeakTrce>はメモリリークを追跡するためのいくつかのユーティリティとC<Test::Builder>ベースのテスト関数を提供します。このモジュールはPerlのメモリアロケーションシステムであるアリーナを走査するため，SVに関することであれば与えられたコードのどんなメモリリークでも検出できます。つまり，Perlレベルでの循環参照を始めとして，XSモジュールやPerl自身のバグによるメモリリークを追跡することができます。 ここでB<リーク>とは，特定のスコープ内で新たに作成されて，そのスコープ終了後にも残っている値を意味します。これは，新たに作成されたグローバルな値やPerlが暗黙のうちに作成するキャッシュの値も含みます。たとえば，リーク追跡を行っている最中に新たに名前つきサブルーチンを定義すれば，それはリークとみなされます。また，継承したメソッドを呼び出したり，オブジェクトを作成したりするだけで様々なキャッシュが生成され，リークが報告される可能性があります。 =head1 INTERFACE =head2 Exported functions =head3 C<< leaked_info { BLOCK } >> I<BLOCK>を実行し，追跡結果をリストで返します。 結果はリークした値のリファレンス，ファイル名，行番号の三要素を持つ配列，つまりC<< [$ref, $file, $line] >>のリストとなっています。 なお，この関数はPerl内部で使用する値を返す可能性があります。そのような内部用の値を変更するとPerl実行環境に致命的な影響を与える可能性があるので注意してください。また，配列やハッシュの要素として，リファレンスではない配列やハッシュそれ自体が含まれる可能性があります。そのような値は通常Perlレベルで操作することができません。たとえばC<Data::Dumper>などで出力することはできません。 =head3 C<< leaked_refs { BLOCK } >> I<BLOCK>を実行し，リークしたSVのリファレンスのリストを返します。 C<< map{ $_->[0] } leaked_info{ BLOCK } >>と同じですが，より高速です。 =head3 C<< leaked_count { BLOCK } >> I<BLOCK>を実行し，リークしたSVのリファレンスの個数を返します。 C<leaked_info()>とC<leaked_refs()>もスカラコンテキストでは個数を返しますが， C<leaked_count()>はコンテキストに依存しません。 =head3 C<< leaktrace { BLOCK } ?($mode | \&callback) >> I<BLOCK>を実行し，その中で起きたメモリリークをC<*STDERR>に報告します。 メモリリークの報告はI<$mode>で指定したモードに従います。 受け付けるI<$mode>は以下の通りです： =over 4 =item -simple デフォルトのモードです。リークしたSVの型とアドレス，ファイル名，行番号を報告します。 =item -sv_dump B<-simple>に加えて，C<sv_dump()>でSVの中身をダンプします。 これは，C<Devel::Peek::Dump()>の出力とほぼ同じです。 =item -lines B<-simple>に加えて，リークしていると見られる行の周辺を出力します。 =item -verbose B<-simple>とB<-sv_dump>とB<-lines>の全てを出力します。 =back より細かな制御のためにコールバックを指定することもできます。 I<\&callback>はリークしたSV毎に呼び出され，その引数はリークしたSVのリファレンス，ファイル名，行番号の3つです。 =head3 C<< no_leaks_ok { BLOCK } ?$description >> I<BLOCK>にメモリリークがないことテストします。 これはC<Test::Builder>ベースのテスト関数です。 なお，I<BLOCK>は複数回実行されます。これは，初回の実行でキャッシュを用意する可能性を考慮するためです。 =head3 C<< leaks_cmp_ok { BLOCK } $cmp_op, $count, ?$description >> I<BLOCK>のメモリリーク数と特定の数値を比較するテストを行います。 これはC<Test::Builder>ベースのテスト関数です。 なお，I<BLOCK>は複数回実行されます。これは，初回の実行でキャッシュを用意する可能性を考慮するためです。 =head2 Script interface C<Devel::LeakTrace>と同様に，スクリプトのリーク追跡のためにC<Test::LeakTrace::Script>が提供されます。C<use Test::LeakTrace::Script>宣言の引数はC<leaktrace()>と同じです。 $ TEST_LEAKTRACE=-sv_dump perl -MTest::LeakTrace::Script script.pl $ perl -MTest::LeakTrace::Script=-verbose script.pl #!perl # ... use Test::LeakTrace::Script sub{ my($ref, $file, $line) = @_; # ... }; # ... =head1 EXAMPLES =head2 Testing modules 以下はモジュールのメモリリークをチェックするテストスクリプトのテンプレートです。 #!perl -w use strict; use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace }; use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => 'require Test::LeakTrace'); use Test::LeakTrace; use Some::Module; leaks_cmp_ok{ my $o = Some::Module->new(); $o->something(); $o->something_else(); } '<', 1; =head1 GUTS C<Test::LeakTrace>はアリーナを走査します。アリーナとは，Perlが作成するSVのためのメモリアロケーションシステムであり，F<sv.c>で実装されています。 アリーナの走査にはF<sv.c>にあるC<S_visit()>のコードを元にしたマクロを用いています。 さて，アリーナを走査すれば，メモリリークの検出そのものは簡単にできるように思えます。まず，コードブロックを実行する前に一度アリーナを走査し，全てのSVに「使用済み」の印を付けておきます。次に，コードブロック実行後にもう一度アリーナを走査し，使用済みの印がついていないSVがあれば，それはコードブロック内で作成され，開放されなかったSVだと考えます。あとはそれを報告するだけです。実際には，SVに対して使用済みの印を付けるスペースがないため，インサイドアウト法を応用して外部のコンテナに使用済みの印を保存します。 これを仮にPerlコードで書くと以下のようになります。 my %used_sv; foreach my $sv(@ARENA){ $used_sv{$sv}++; } $block->(); my @leaked foreach my $sv(@ARENA){ if(not exists $used_sv{$sv}){ push @leaked, $sv; } } say 'leaked count: ', scalar @leaked; リークしたSVを得るだけならこの方法で十分です。実際，C<leaked_refs()>とC<leaked_count()>はこのような方法でリークしたSVやその個数を調べています。 しかし，リークしたSVのステートメントの情報，つまりファイル名や行番号を得るためにはこれだけでは不十分です。Perl 5.10以降にはSVが作成されたときのステートメント情報を追跡する機能があるのですが，この機能を利用するためには，コンパイラオプションとしてにC<-DDEBUG_LEAKING_SCALARS>を与えてPerlをビルドしなければなりません。 そこで，C<Test::LeakTrace>では拡張可能なC<PL_runops>を利用して，Perl VMがOPコードを実行する1ステートメント毎にアリーナを走査し，ステートメント情報を記録します。これは，1ステートメント毎にマーク＆スイープのような処理を行うのに等しく，非常に時間が掛かります。しかし，Perlを特殊な条件の下でビルドする必要もなく，バージョンに依存した機能もほとんど使用しないため，多くの環境で動かすことができます。 また，C<no_leaks_ok()>のようなテスト関数はまずC<leaked_count()>でリークしたSVの個数を得てから，必要に応じてリークした位置を特定するためにC<leaktrace()>を実行するため，テストが成功する限りは時間の掛かる追跡処理はしません。 =head1 DEPENDENCIES Perl 5.8.1 or later, and a C compiler. =head1 CAVEATS C<Test::LeakTrace>はC<Devel::Cover>と一緒に動かすことはできません。 したがって，C<Devel::Cover>の元で動いていることが検出されると，テスト関数は何も行わずにテストをパスさせます。 =head1 BUGS No bugs have been reported. Please report any bugs or feature requests to the author. =head1 SEE ALSO L<Devel::LeakTrace>. L<Devel::LeakTrace::Fast>. L<Test::TraceObject>. L<Test::Weak>. For guts: L<perlguts>. L<perlhack>. L<sv.c>. =head1 AUTHOR Goro Fuji E<lt>gfuji(at)cpan.orgE<gt>. =head1 LICENSE AND COPYRIGHT Copyright (c) 2009, Goro Fuji. Some rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �["#v^ ^ lib/Test/LeakTrace.pmnu ��6�$ package Test::LeakTrace; use 5.008_001; use strict; use warnings; our $VERSION = '0.17'; use XSLoader; XSLoader::load(__PACKAGE__, $VERSION); use Test::Builder::Module; our @ISA = qw(Test::Builder::Module); use Exporter qw(import); # use Exporter::import for backward compatibility our @EXPORT = qw( leaktrace leaked_refs leaked_info leaked_count no_leaks_ok leaks_cmp_ok count_sv ); our %EXPORT_TAGS = ( all => \@EXPORT, test => [qw(no_leaks_ok leaks_cmp_ok)], util => [qw(leaktrace leaked_refs leaked_info leaked_count count_sv)], ); sub _do_leaktrace{ my($block, $name, $need_stateinfo, $mode) = @_; if(!defined($mode) && !defined wantarray){ warnings::warnif void => "Useless use of $name() in void context"; } if($name eq 'leaked_count') { my $start; $start = count_sv(); $block->(); return count_sv() - $start; } local $SIG{__DIE__} = 'DEFAULT'; _start($need_stateinfo); eval{ $block->(); }; if($@){ _finish(-silent); die $@; } return _finish($mode); } sub leaked_refs(&){ my($block) = @_; return _do_leaktrace($block, 'leaked_refs', 0); } sub leaked_info(&){ my($block) = @_; return _do_leaktrace($block, 'leaked_refs', 1); } sub leaked_count(&){ my($block) = @_; return scalar _do_leaktrace($block, 'leaked_count', 0); } sub leaktrace(&;$){ my($block, $mode) = @_; _do_leaktrace($block, 'leaktrace', 1, defined($mode) ? $mode : -simple); return; } sub leaks_cmp_ok(&$$;$){ my($block, $cmp_op, $expected, $description) = @_; my $Test = __PACKAGE__->builder; if(!_runops_installed()){ my $mod = exists $INC{'Devel/Cover.pm'} ? 'Devel::Cover' : 'strange runops routines'; return $Test->ok(1, "skipped (under $mod)"); } # calls to prepare cache in $block $block->(); my $got = _do_leaktrace($block, 'leaked_count', 0); my $desc = sprintf 'leaks %s %-2s %s', $got, $cmp_op, $expected; if(defined $description){ $description .= " ($desc)"; } else{ $description = $desc; } my $result = $Test->cmp_ok($got, $cmp_op, $expected, $description); if(!$result){ open local(*STDERR), '>', \(my $content = ''); $block->(); # calls it again because opening *STDERR changes the run-time environment _do_leaktrace($block, 'leaktrace', 1, -verbose); $Test->diag($content); } return $result; } sub no_leaks_ok(&;$){ # ($block, $description) splice @_, 1, 0, ('<=', 0); # ($block, '<=', 0, $description); goto &leaks_cmp_ok; } 1; __END__ =for stopwords sv gfx =head1 NAME Test::LeakTrace - Traces memory leaks =head1 VERSION This document describes Test::LeakTrace version 0.17. =head1 SYNOPSIS use Test::LeakTrace; # simple report leaktrace{ # ... }; # verbose output leaktrace{ # ... } -verbose; # with callback leaktrace{ # ... } sub { my($ref, $file, $line) = @_; warn "leaked $ref from $file line\n"; }; my @refs = leaked_refs{ # ... }; my @info = leaked_info{ # ... }; my $count = leaked_count{ # ... }; # standard test interface use Test::LeakTrace; no_leaks_ok{ # ... } 'no memory leaks'; leaks_cmp_ok{ # ... } '<', 10; =head1 DESCRIPTION C<Test::LeakTrace> provides several functions that trace memory leaks. This module scans arenas, the memory allocation system, so it can detect any leaked SVs in given blocks. B<Leaked SVs> are SVs which are not released after the end of the scope they have been created. These SVs include global variables and internal caches. For example, if you call a method in a tracing block, perl might prepare a cache for the method. Thus, to trace true leaks, C<no_leaks_ok()> and C<leaks_cmp_ok()> executes a block more than once. =head1 INTERFACE =head2 Exported functions =head3 C<< leaked_info { BLOCK } >> Executes I<BLOCK> and returns a list of leaked SVs and places where the SVs come from, i.e. C<< [$ref, $file, $line] >>. =head3 C<< leaked_refs { BLOCK } >> Executes I<BLOCK> and returns a list of leaked SVs. =head3 C<< leaked_count { BLOCK } >> Executes I<BLOCK> and returns the number of leaked SVs. =head3 C<< leaktrace { BLOCK } ?($mode | \&callback) >> Executes I<BLOCK> and reports leaked SVs to C<*STDERR>. Defined I<$mode>s are: =over 4 =item -simple Default. Reports the leaked SV identity (type and address), file name and line number. =item -sv_dump In addition to B<-simple>, dumps the sv content using C<sv_dump()>, which also implements C<Devel::Peek::Dump()>. =item -lines In addition to B<-simple>, prints suspicious source lines. =item -verbose Both B<-sv_dump> and B<-lines>. =back =head3 C<< no_leaks_ok { BLOCK } ?$description >> Tests that I<BLOCK> does not leaks SVs. This is a test function using C<Test::Builder>. Note that I<BLOCK> is called more than once. This is because I<BLOCK> might prepare caches which are not memory leaks. =head3 C<< leaks_cmp_ok { BLOCK } $cmp_op, $number, ?$description >> Tests that I<BLOCK> leaks a specific number of SVs. This is a test function using C<Test::Builder>. Note that I<BLOCK> is called more than once. This is because I<BLOCK> might prepare caches which are not memory leaks. =head3 C<< count_sv() >> Counts all the SVs in the arena. =head2 Script interface Like C<Devel::LeakTrace> C<Test::LeakTrace::Script> is provided for whole scripts. The arguments of C<use Test::LeakTrace::Script> directive is the same as C<leaktrace()>. $ TEST_LEAKTRACE=-sv_dump perl -MTest::LeakTrace::Script script.pl $ perl -MTest::LeakTrace::Script=-verbose script.pl #!perl # ... use Test::LeakTrace::Script sub{ my($ref, $file, $line) = @_; # ... }; # ... =head1 EXAMPLES =head2 Testing modules Here is a test script template that checks memory leaks. #!perl -w use strict; use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace }; use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => 'require Test::LeakTrace'); use Test::LeakTrace; use Some::Module; leaks_cmp_ok{ my $o = Some::Module->new(); $o->something(); $o->something_else(); } '<', 1; =head1 DEPENDENCIES Perl 5.8.1 or later, and a C compiler. =head1 CAVEATS C<Test::LeakTrace> does not work with C<Devel::Cover> and modules which install their own C<runops> routines, or the perl executor. So if the test functions of this module detect strange C<runops> routines, they do nothing and report okay. =head1 BUGS No bugs have been reported. Please report any bugs or feature requests to the author. =head1 SEE ALSO L<Devel::LeakTrace>. L<Devel::LeakTrace::Fast>. L<Test::TraceObject>. L<Test::Weak>. For guts: L<perlguts>. L<perlhack>. F<sv.c>. =head1 AUTHOR Goro Fuji(gfx) E<lt>gfuji(at)cpan.orgE<gt>. =head1 LICENSE AND COPYRIGHT Copyright (c) 2009-2010, Goro Fuji(gfx). All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut PK � �[ lib/auto/Test/LeakTrace/.existsnu �[��� PK � �[5P�% �% man3/Test::Fatal.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Fatal 3" .TH Test::Fatal 3 "2022-12-31" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Fatal \- incredibly simple helpers for testing code with exceptions .SH "VERSION" .IX Header "VERSION" version 0.017 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Test::More; \& use Test::Fatal; \& \& use System::Under::Test qw(might_die); \& \& is( \& exception { might_die; }, \& undef, \& "the code lived", \& ); \& \& like( \& exception { might_die; }, \& qr/turns out it died/, \& "the code died as expected", \& ); \& \& isa_ok( \& exception { might_die; }, \& \*(AqException::Whatever\*(Aq, \& \*(Aqthe thrown exception\*(Aq, \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Test::Fatal is an alternative to the popular Test::Exception. It does much less, but should allow greater flexibility in testing exception-throwing code with about the same amount of typing. .PP It exports one routine by default: \f(CW\*(C`exception\*(C'\fR. .PP \&\fBAchtung!\fR \f(CW\*(C`exception\*(C'\fR intentionally does not manipulate the call stack. User-written test functions that use \f(CW\*(C`exception\*(C'\fR must be careful to avoid false positives if exceptions use stack traces that show arguments. For a more magical approach involving globally overriding \f(CW\*(C`caller\*(C'\fR, see Test::Exception. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "exception" .IX Subsection "exception" .Vb 1 \& my $exception = exception { ... }; .Ve .PP \&\f(CW\*(C`exception\*(C'\fR takes a bare block of code and returns the exception thrown by that block. If no exception was thrown, it returns undef. .PP \&\fBAchtung!\fR If the block results in a \fIfalse\fR exception, such as 0 or the empty string, Test::Fatal itself will die. Since either of these cases indicates a serious problem with the system under testing, this behavior is considered a \fIfeature\fR. If you must test for these conditions, you should use Try::Tiny's try/catch mechanism. (Try::Tiny is the underlying exception handling system of Test::Fatal.) .PP Note that there is no \s-1TAP\s0 assert being performed. In other words, no \*(L"ok\*(R" or \&\*(L"not ok\*(R" line is emitted. It's up to you to use the rest of \f(CW\*(C`exception\*(C'\fR in an existing test like \f(CW\*(C`ok\*(C'\fR, \f(CW\*(C`isa_ok\*(C'\fR, \f(CW\*(C`is\*(C'\fR, et cetera. Or you may wish to use the \f(CW\*(C`dies_ok\*(C'\fR and \f(CW\*(C`lives_ok\*(C'\fR wrappers, which do provide \s-1TAP\s0 output. .PP \&\f(CW\*(C`exception\*(C'\fR does \fInot\fR alter the stack presented to the called block, meaning that if the exception returned has a stack trace, it will include some frames between the code calling \f(CW\*(C`exception\*(C'\fR and the thing throwing the exception. This is considered a \fIfeature\fR because it avoids the occasionally twitchy \&\f(CW\*(C`Sub::Uplevel\*(C'\fR mechanism. .PP \&\fBAchtung!\fR This is not a great idea: .PP .Vb 4 \& sub exception_like(&$;$) { \& my ($code, $pattern, $name) = @_; \& like( &exception($code), $pattern, $name ); \& } \& \& exception_like(sub { }, qr/foo/, \*(Aqfoo appears in the exception\*(Aq); .Ve .PP If the code in the \f(CW\*(C`...\*(C'\fR is going to throw a stack trace with the arguments to each subroutine in its call stack (for example via \f(CW\*(C`Carp::confess\*(C'\fR, the test name, \*(L"foo appears in the exception\*(R" will itself be matched by the regex. Instead, write this: .PP .Vb 1 \& like( exception { ... }, qr/foo/, \*(Aqfoo appears in the exception\*(Aq ); .Ve .PP If you really want a test function that passes the test name, wrap the arguments in an array reference to hide the literal text from a stack trace: .PP .Vb 5 \& sub exception_like(&$) { \& my ($code, $args) = @_; \& my ($pattern, $name) = @$args; \& like( &exception($code), $pattern, $name ); \& } \& \& exception_like(sub { }, [ qr/foo/, \*(Aqfoo appears in the exception\*(Aq ] ); .Ve .PP To aid in avoiding the problem where the pattern is seen in the exception because of the call stack, \f(CW$Carp::MaxArgNums\fR is locally set to \-1 when the code block is called. If you really don't want that, set it back to whatever value you like at the beginning of the code block. Obviously, this solution doens't affect all possible ways that args of subroutines in the call stack might taint the test. The intention here is to prevent some false passes from people who didn't read the documentation. Your punishment for reading it is that you must consider whether to do anything about this. .PP \&\fBAchtung\fR: One final bad idea: .PP .Vb 1 \& isnt( exception { ... }, undef, "my code died!"); .Ve .PP It's true that this tests that your code died, but you should really test that it died \fIfor the right reason\fR. For example, if you make an unrelated mistake in the block, like using the wrong dereference, your test will pass even though the code to be tested isn't really run at all. If you're expecting an inspectable exception with an identifier or class, test that. If you're expecting a string exception, consider using \f(CW\*(C`like\*(C'\fR. .SS "success" .IX Subsection "success" .Vb 7 \& try { \& should_live; \& } catch { \& fail("boo, we died"); \& } success { \& pass("hooray, we lived"); \& }; .Ve .PP \&\f(CW\*(C`success\*(C'\fR, exported only by request, is a Try::Tiny helper with semantics identical to \f(CW\*(C`finally\*(C'\fR, but the body of the block will only be run if the \f(CW\*(C`try\*(C'\fR block ran without error. .PP Although almost any needed exception tests can be performed with \f(CW\*(C`exception\*(C'\fR, success blocks may sometimes help organize complex testing. .SS "dies_ok" .IX Subsection "dies_ok" .SS "lives_ok" .IX Subsection "lives_ok" Exported only by request, these two functions run a given block of code, and provide \s-1TAP\s0 output indicating if it did, or did not throw an exception. These provide an easy upgrade path for replacing existing unit tests based on \&\f(CW\*(C`Test::Exception\*(C'\fR. .PP \&\s-1RJBS\s0 does not suggest using this except as a convenience while porting tests to use Test::Fatal's \f(CW\*(C`exception\*(C'\fR routine. .PP .Vb 2 \& use Test::More tests => 2; \& use Test::Fatal qw(dies_ok lives_ok); \& \& dies_ok { die "I failed" } \*(Aqcode that fails\*(Aq; \& \& lives_ok { return "I\*(Aqm still alive" } \*(Aqcode that does not fail\*(Aq; .Ve .SH "AUTHOR" .IX Header "AUTHOR" Ricardo Signes <cpan@semiotic.systems> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 David Golden <dagolden@cpan.org> .IP "\(bu" 4 Graham Knop <haarg@haarg.org> .IP "\(bu" 4 Jesse Luehrs <doy@tozt.net> .IP "\(bu" 4 Joel Bernstein <joel@fysh.org> .IP "\(bu" 4 Karen Etheridge <ether@cpan.org> .IP "\(bu" 4 Ricardo Signes <rjbs@semiotic.systems> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by Ricardo Signes. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK � �[ arch/auto/Test/Fatal/.existsnu �[��� PK � �[��x��; �; lib/Test/Fatal.pmnu ��6�$ use strict; use warnings; package Test::Fatal; # ABSTRACT: incredibly simple helpers for testing code with exceptions $Test::Fatal::VERSION = '0.017'; #pod =head1 SYNOPSIS #pod #pod use Test::More; #pod use Test::Fatal; #pod #pod use System::Under::Test qw(might_die); #pod #pod is( #pod exception { might_die; }, #pod undef, #pod "the code lived", #pod ); #pod #pod like( #pod exception { might_die; }, #pod qr/turns out it died/, #pod "the code died as expected", #pod ); #pod #pod isa_ok( #pod exception { might_die; }, #pod 'Exception::Whatever', #pod 'the thrown exception', #pod ); #pod #pod =head1 DESCRIPTION #pod #pod Test::Fatal is an alternative to the popular L<Test::Exception>. It does much #pod less, but should allow greater flexibility in testing exception-throwing code #pod with about the same amount of typing. #pod #pod It exports one routine by default: C<exception>. #pod #pod B<Achtung!> C<exception> intentionally does not manipulate the call stack. #pod User-written test functions that use C<exception> must be careful to avoid #pod false positives if exceptions use stack traces that show arguments. For a more #pod magical approach involving globally overriding C<caller>, see #pod L<Test::Exception>. #pod #pod =cut use Carp (); use Try::Tiny 0.07; use Exporter 5.57 'import'; our @EXPORT = qw(exception); our @EXPORT_OK = qw(exception success dies_ok lives_ok); #pod =func exception #pod #pod my $exception = exception { ... }; #pod #pod C<exception> takes a bare block of code and returns the exception thrown by #pod that block. If no exception was thrown, it returns undef. #pod #pod B<Achtung!> If the block results in a I<false> exception, such as 0 or the #pod empty string, Test::Fatal itself will die. Since either of these cases #pod indicates a serious problem with the system under testing, this behavior is #pod considered a I<feature>. If you must test for these conditions, you should use #pod L<Try::Tiny>'s try/catch mechanism. (Try::Tiny is the underlying exception #pod handling system of Test::Fatal.) #pod #pod Note that there is no TAP assert being performed. In other words, no "ok" or #pod "not ok" line is emitted. It's up to you to use the rest of C<exception> in an #pod existing test like C<ok>, C<isa_ok>, C<is>, et cetera. Or you may wish to use #pod the C<dies_ok> and C<lives_ok> wrappers, which do provide TAP output. #pod #pod C<exception> does I<not> alter the stack presented to the called block, meaning #pod that if the exception returned has a stack trace, it will include some frames #pod between the code calling C<exception> and the thing throwing the exception. #pod This is considered a I<feature> because it avoids the occasionally twitchy #pod C<Sub::Uplevel> mechanism. #pod #pod B<Achtung!> This is not a great idea: #pod #pod sub exception_like(&$;$) { #pod my ($code, $pattern, $name) = @_; #pod like( &exception($code), $pattern, $name ); #pod } #pod #pod exception_like(sub { }, qr/foo/, 'foo appears in the exception'); #pod #pod If the code in the C<...> is going to throw a stack trace with the arguments to #pod each subroutine in its call stack (for example via C<Carp::confess>, #pod the test name, "foo appears in the exception" will itself be matched by the #pod regex. Instead, write this: #pod #pod like( exception { ... }, qr/foo/, 'foo appears in the exception' ); #pod #pod If you really want a test function that passes the test name, wrap the #pod arguments in an array reference to hide the literal text from a stack trace: #pod #pod sub exception_like(&$) { #pod my ($code, $args) = @_; #pod my ($pattern, $name) = @$args; #pod like( &exception($code), $pattern, $name ); #pod } #pod #pod exception_like(sub { }, [ qr/foo/, 'foo appears in the exception' ] ); #pod #pod To aid in avoiding the problem where the pattern is seen in the exception #pod because of the call stack, C<$Carp::MaxArgNums> is locally set to -1 when the #pod code block is called. If you really don't want that, set it back to whatever #pod value you like at the beginning of the code block. Obviously, this solution #pod doens't affect all possible ways that args of subroutines in the call stack #pod might taint the test. The intention here is to prevent some false passes from #pod people who didn't read the documentation. Your punishment for reading it is #pod that you must consider whether to do anything about this. #pod #pod B<Achtung>: One final bad idea: #pod #pod isnt( exception { ... }, undef, "my code died!"); #pod #pod It's true that this tests that your code died, but you should really test that #pod it died I<for the right reason>. For example, if you make an unrelated mistake #pod in the block, like using the wrong dereference, your test will pass even though #pod the code to be tested isn't really run at all. If you're expecting an #pod inspectable exception with an identifier or class, test that. If you're #pod expecting a string exception, consider using C<like>. #pod #pod =cut our ($REAL_TBL, $REAL_CALCULATED_TBL) = (1, 1); sub exception (&) { my $code = shift; return try { my $incremented = defined $Test::Builder::Level ? $Test::Builder::Level - $REAL_CALCULATED_TBL : 0; local $Test::Builder::Level = $REAL_CALCULATED_TBL; if ($incremented) { # each call to exception adds 5 stack frames $Test::Builder::Level += 5; for my $i (1..$incremented) { # -2 because we want to see it from the perspective of the call to # is() within the call to $code->() my $caller = caller($Test::Builder::Level - 2); if ($caller eq __PACKAGE__) { # each call to exception adds 5 stack frames $Test::Builder::Level = $Test::Builder::Level + 5; } else { $Test::Builder::Level = $Test::Builder::Level + 1; } } } local $REAL_CALCULATED_TBL = $Test::Builder::Level; local $Carp::MaxArgNums = -1; $code->(); return undef; } catch { return $_ if $_; my $problem = defined $_ ? 'false' : 'undef'; Carp::confess("$problem exception caught by Test::Fatal::exception"); }; } #pod =func success #pod #pod try { #pod should_live; #pod } catch { #pod fail("boo, we died"); #pod } success { #pod pass("hooray, we lived"); #pod }; #pod #pod C<success>, exported only by request, is a L<Try::Tiny> helper with semantics #pod identical to L<C<finally>|Try::Tiny/finally>, but the body of the block will #pod only be run if the C<try> block ran without error. #pod #pod Although almost any needed exception tests can be performed with C<exception>, #pod success blocks may sometimes help organize complex testing. #pod #pod =cut sub success (&;@) { my $code = shift; return finally( sub { return if @_; # <-- only run on success $code->(); }, @_ ); } #pod =func dies_ok #pod #pod =func lives_ok #pod #pod Exported only by request, these two functions run a given block of code, and #pod provide TAP output indicating if it did, or did not throw an exception. #pod These provide an easy upgrade path for replacing existing unit tests based on #pod C<Test::Exception>. #pod #pod RJBS does not suggest using this except as a convenience while porting tests to #pod use Test::Fatal's C<exception> routine. #pod #pod use Test::More tests => 2; #pod use Test::Fatal qw(dies_ok lives_ok); #pod #pod dies_ok { die "I failed" } 'code that fails'; #pod #pod lives_ok { return "I'm still alive" } 'code that does not fail'; #pod #pod =cut my $Tester; # Signature should match that of Test::Exception sub dies_ok (&;$) { my $code = shift; my $name = shift; require Test::Builder; $Tester ||= Test::Builder->new; my $tap_pos = $Tester->current_test; my $exception = exception( \&$code ); $name ||= $tap_pos != $Tester->current_test ? "...and code should throw an exception" : "code should throw an exception"; my $ok = $Tester->ok( $exception, $name ); $ok or $Tester->diag( "expected an exception but none was raised" ); return $ok; } sub lives_ok (&;$) { my $code = shift; my $name = shift; require Test::Builder; $Tester ||= Test::Builder->new; my $tap_pos = $Tester->current_test; my $exception = exception( \&$code ); $name ||= $tap_pos != $Tester->current_test ? "...and code should not throw an exception" : "code should not throw an exception"; my $ok = $Tester->ok( ! $exception, $name ); $ok or $Tester->diag( "expected return but an exception was raised" ); return $ok; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Fatal - incredibly simple helpers for testing code with exceptions =head1 VERSION version 0.017 =head1 SYNOPSIS use Test::More; use Test::Fatal; use System::Under::Test qw(might_die); is( exception { might_die; }, undef, "the code lived", ); like( exception { might_die; }, qr/turns out it died/, "the code died as expected", ); isa_ok( exception { might_die; }, 'Exception::Whatever', 'the thrown exception', ); =head1 DESCRIPTION Test::Fatal is an alternative to the popular L<Test::Exception>. It does much less, but should allow greater flexibility in testing exception-throwing code with about the same amount of typing. It exports one routine by default: C<exception>. B<Achtung!> C<exception> intentionally does not manipulate the call stack. User-written test functions that use C<exception> must be careful to avoid false positives if exceptions use stack traces that show arguments. For a more magical approach involving globally overriding C<caller>, see L<Test::Exception>. =head1 PERL VERSION This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. =head1 FUNCTIONS =head2 exception my $exception = exception { ... }; C<exception> takes a bare block of code and returns the exception thrown by that block. If no exception was thrown, it returns undef. B<Achtung!> If the block results in a I<false> exception, such as 0 or the empty string, Test::Fatal itself will die. Since either of these cases indicates a serious problem with the system under testing, this behavior is considered a I<feature>. If you must test for these conditions, you should use L<Try::Tiny>'s try/catch mechanism. (Try::Tiny is the underlying exception handling system of Test::Fatal.) Note that there is no TAP assert being performed. In other words, no "ok" or "not ok" line is emitted. It's up to you to use the rest of C<exception> in an existing test like C<ok>, C<isa_ok>, C<is>, et cetera. Or you may wish to use the C<dies_ok> and C<lives_ok> wrappers, which do provide TAP output. C<exception> does I<not> alter the stack presented to the called block, meaning that if the exception returned has a stack trace, it will include some frames between the code calling C<exception> and the thing throwing the exception. This is considered a I<feature> because it avoids the occasionally twitchy C<Sub::Uplevel> mechanism. B<Achtung!> This is not a great idea: sub exception_like(&$;$) { my ($code, $pattern, $name) = @_; like( &exception($code), $pattern, $name ); } exception_like(sub { }, qr/foo/, 'foo appears in the exception'); If the code in the C<...> is going to throw a stack trace with the arguments to each subroutine in its call stack (for example via C<Carp::confess>, the test name, "foo appears in the exception" will itself be matched by the regex. Instead, write this: like( exception { ... }, qr/foo/, 'foo appears in the exception' ); If you really want a test function that passes the test name, wrap the arguments in an array reference to hide the literal text from a stack trace: sub exception_like(&$) { my ($code, $args) = @_; my ($pattern, $name) = @$args; like( &exception($code), $pattern, $name ); } exception_like(sub { }, [ qr/foo/, 'foo appears in the exception' ] ); To aid in avoiding the problem where the pattern is seen in the exception because of the call stack, C<$Carp::MaxArgNums> is locally set to -1 when the code block is called. If you really don't want that, set it back to whatever value you like at the beginning of the code block. Obviously, this solution doens't affect all possible ways that args of subroutines in the call stack might taint the test. The intention here is to prevent some false passes from people who didn't read the documentation. Your punishment for reading it is that you must consider whether to do anything about this. B<Achtung>: One final bad idea: isnt( exception { ... }, undef, "my code died!"); It's true that this tests that your code died, but you should really test that it died I<for the right reason>. For example, if you make an unrelated mistake in the block, like using the wrong dereference, your test will pass even though the code to be tested isn't really run at all. If you're expecting an inspectable exception with an identifier or class, test that. If you're expecting a string exception, consider using C<like>. =head2 success try { should_live; } catch { fail("boo, we died"); } success { pass("hooray, we lived"); }; C<success>, exported only by request, is a L<Try::Tiny> helper with semantics identical to L<C<finally>|Try::Tiny/finally>, but the body of the block will only be run if the C<try> block ran without error. Although almost any needed exception tests can be performed with C<exception>, success blocks may sometimes help organize complex testing. =head2 dies_ok =head2 lives_ok Exported only by request, these two functions run a given block of code, and provide TAP output indicating if it did, or did not throw an exception. These provide an easy upgrade path for replacing existing unit tests based on C<Test::Exception>. RJBS does not suggest using this except as a convenience while porting tests to use Test::Fatal's C<exception> routine. use Test::More tests => 2; use Test::Fatal qw(dies_ok lives_ok); dies_ok { die "I failed" } 'code that fails'; lives_ok { return "I'm still alive" } 'code that does not fail'; =head1 AUTHOR Ricardo Signes <cpan@semiotic.systems> =head1 CONTRIBUTORS =for stopwords David Golden Graham Knop Jesse Luehrs Joel Bernstein Karen Etheridge Ricardo Signes =over 4 =item * David Golden <dagolden@cpan.org> =item * Graham Knop <haarg@haarg.org> =item * Jesse Luehrs <doy@tozt.net> =item * Joel Bernstein <joel@fysh.org> =item * Karen Etheridge <ether@cpan.org> =item * Ricardo Signes <rjbs@semiotic.systems> =back =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2010 by Ricardo Signes. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK � �[ lib/auto/Test/Fatal/.existsnu �[��� PK � �[��bY Y man3/Test::File.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::File 3" .TH Test::File 3 "2022-12-31" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::File \-\- test file attributes .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Test::File; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This modules provides a collection of test utilities for file attributes. .PP Some file attributes depend on the owner of the process testing the file in the same way the file test operators do. For instance, root (or super-user or Administrator) may always be able to read files no matter the permissions. .PP Some attributes don't make sense outside of Unix, either, so some tests automatically skip if they think they won't work on the platform. If you have a way to make these functions work on Windows, for instance, please send me a patch. :) If you want to pretend to be Windows on a non-Windows machine (for instance, to test \f(CW\*(C`skip()\*(C'\fR), you can set the \f(CW\*(C`PRETEND_TO_BE_WINDOWS\*(C'\fR environment variable. .PP The optional \s-1NAME\s0 parameter for every function allows you to specify a name for the test. If not supplied, a reasonable default will be generated. .SS "Functions" .IX Subsection "Functions" .IP "has_symlinks" 4 .IX Item "has_symlinks" Returns true is this module thinks that the current system supports symlinks. .Sp This is not a test function. It's something that tests can use to determine what it should expect or skip. .IP "file_exists_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_exists_ok( FILENAME [, NAME ] )" Ok if the file exists, and not ok otherwise. .IP "file_not_exists_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_not_exists_ok( FILENAME [, NAME ] )" Ok if the file does not exist, and not okay if it does exist. .IP "file_empty_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_empty_ok( FILENAME [, NAME ] )" Ok if the file exists and has empty size, not ok if the file does not exist or exists with non-zero size. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_not_empty_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_not_empty_ok( FILENAME [, NAME ] )" Ok if the file exists and has non-zero size, not ok if the file does not exist or exists with zero size. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_size_ok( \s-1FILENAME, SIZE\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_size_ok( FILENAME, SIZE [, NAME ] )" Ok if the file exists and has \s-1SIZE\s0 size in bytes (exactly), not ok if the file does not exist or exists with size other than \s-1SIZE.\s0 .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_max_size_ok( \s-1FILENAME, MAX\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_max_size_ok( FILENAME, MAX [, NAME ] )" Ok if the file exists and has size less than or equal to \s-1MAX\s0 bytes, not ok if the file does not exist or exists with size greater than \s-1MAX\s0 bytes. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_min_size_ok( \s-1FILENAME, MIN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_min_size_ok( FILENAME, MIN [, NAME ] )" Ok if the file exists and has size greater than or equal to \s-1MIN\s0 bytes, not ok if the file does not exist or exists with size less than \s-1MIN\s0 bytes. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_line_count_is( \s-1FILENAME, COUNT\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_line_count_is( FILENAME, COUNT [, NAME ] )" Ok if the file exists and has \s-1COUNT\s0 lines (exactly), not ok if the file does not exist or exists with a line count other than \s-1COUNT.\s0 .Sp This function uses the current value of \f(CW$/\fR as the line ending and counts the lines by reading them and counting how many it read. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_line_count_isnt( \s-1FILENAME, COUNT\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_line_count_isnt( FILENAME, COUNT [, NAME ] )" Ok if the file exists and doesn't have exactly \s-1COUNT\s0 lines, not ok if the file does not exist or exists with a line count of \s-1COUNT.\s0 Read that carefully: the file must exist for this test to pass! .Sp This function uses the current value of \f(CW$/\fR as the line ending and counts the lines by reading them and counting how many it read. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_line_count_between( \s-1FILENAME, MIN, MAX,\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_line_count_between( FILENAME, MIN, MAX, [, NAME ] )" Ok if the file exists and has a line count between \s-1MIN\s0 and \s-1MAX,\s0 inclusively. .Sp This function uses the current value of \f(CW$/\fR as the line ending and counts the lines by reading them and counting how many it read. .Sp Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. .IP "file_contains_like ( \s-1FILENAME, PATTERN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_contains_like ( FILENAME, PATTERN [, NAME ] )" Ok if the file exists and its contents (as one big string) match \&\s-1PATTERN,\s0 not ok if the file does not exist, is not readable, or exists but doesn't match \s-1PATTERN.\s0 .Sp Since the file contents are read into memory, you should not use this for large files. Besides memory consumption, test diagnostics for failing tests might be difficult to decipher. However, for short files this works very well. .Sp Because the entire contents are treated as one large string, you can make a pattern that tests multiple lines. Don't forget that you may need to use the /s modifier for such patterns: .Sp .Vb 2 \& # make sure file has one or more paragraphs with CSS class X \& file_contains_like($html_file, qr{<p class="X">.*?</p>}s); .Ve .Sp Contrariwise, if you need to match at the beginning or end of a line inside the file, use the /m modifier: .Sp .Vb 2 \& # make sure file has a setting for foo \& file_contains_like($config_file, qr/^ foo \es* = \es* \ew+ $/mx); .Ve .Sp If you want to test your file contents against multiple patterns, but don't want to have the file read in repeatedly, you can pass an arrayref of patterns instead of a single pattern, like so: .Sp .Vb 7 \& # make sure our template has rendered correctly \& file_contains_like($template_out, \& [ \& qr/^ $title_line $/mx, \& map { qr/^ $_ $/mx } @chapter_headings, \& qr/^ $footer_line $/mx, \& ]); .Ve .Sp Please note that if you do this, and your file does not exist or is not readable, you'll only get one test failure instead of a failure for each pattern. This could cause your test plan to be off, although you may not care at that point because your test failed anyway. If you do care, either skip the test plan altogether by employing Test::More's \f(CW\*(C`done_testing()\*(C'\fR function, or use \&\*(L"file_readable_ok\*(R" in conjunction with a \f(CW\*(C`SKIP\*(C'\fR block. .Sp Contributed by Buddy Burden \f(CW\*(C`<barefoot@cpan.org>\*(C'\fR. .IP "file_contains_unlike ( \s-1FILENAME, PATTERN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_contains_unlike ( FILENAME, PATTERN [, NAME ] )" Ok if the file exists and its contents (as one big string) do \fBnot\fR match \s-1PATTERN,\s0 not ok if the file does not exist, is not readable, or exists but matches \s-1PATTERN.\s0 .Sp All notes and caveats for \*(L"file_contains_like\*(R" apply to this function as well. .Sp Contributed by Buddy Burden \f(CW\*(C`<barefoot@cpan.org>\*(C'\fR. .IP "file_contains_utf8_like ( \s-1FILENAME, PATTERN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_contains_utf8_like ( FILENAME, PATTERN [, NAME ] )" The same as \f(CW\*(C`file_contains_like\*(C'\fR, except the file is opened as \s-1UTF\-8.\s0 .IP "file_contains_utf8_unlike ( \s-1FILENAME, PATTERN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_contains_utf8_unlike ( FILENAME, PATTERN [, NAME ] )" The same as \f(CW\*(C`file_contains_unlike\*(C'\fR, except the file is opened as \s-1UTF\-8.\s0 .IP "file_contains_encoded_like ( \s-1FILENAME, ENCODING, PATTERN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_contains_encoded_like ( FILENAME, ENCODING, PATTERN [, NAME ] )" The same as \f(CW\*(C`file_contains_like\*(C'\fR, except the file is opened with \s-1ENCODING\s0 .IP "file_contains_encoded_unlike ( \s-1FILENAME, ENCODING, PATTERN\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_contains_encoded_unlike ( FILENAME, ENCODING, PATTERN [, NAME ] )" The same as \f(CW\*(C`file_contains_unlike\*(C'\fR, except the file is opened with \s-1ENCODING.\s0 .IP "file_readable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_readable_ok( FILENAME [, NAME ] )" Ok if the file exists and is readable, not ok if the file does not exist or is not readable. .IP "file_not_readable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_not_readable_ok( FILENAME [, NAME ] )" Ok if the file exists and is not readable, not ok if the file does not exist or is readable. .IP "file_writable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_writable_ok( FILENAME [, NAME ] )" .PD 0 .IP "file_writeable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_writeable_ok( FILENAME [, NAME ] )" .PD Ok if the file exists and is writable, not ok if the file does not exist or is not writable. .Sp The original name is \f(CW\*(C`file_writeable_ok\*(C'\fR with that extra \fIe\fR. That still works but there's a function with the correct spelling too. .IP "file_not_writeable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_not_writeable_ok( FILENAME [, NAME ] )" .PD 0 .IP "file_not_writable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_not_writable_ok( FILENAME [, NAME ] )" .PD Ok if the file exists and is not writable, not ok if the file does not exist or is writable. .Sp The original name is \f(CW\*(C`file_not_writeable_ok\*(C'\fR with that extra \fIe\fR. That still works but there's a function with the correct spelling too. .IP "file_executable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_executable_ok( FILENAME [, NAME ] )" Ok if the file exists and is executable, not ok if the file does not exist or is not executable. .Sp This test automatically skips if it thinks it is on a Windows platform. .IP "file_not_executable_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_not_executable_ok( FILENAME [, NAME ] )" Ok if the file exists and is not executable, not ok if the file does not exist or is executable. .Sp This test automatically skips if it thinks it is on a Windows platform. .IP "file_mode_is( \s-1FILENAME, MODE\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_mode_is( FILENAME, MODE [, NAME ] )" Ok if the file exists and the mode matches, not ok if the file does not exist or the mode does not match. .Sp This test automatically skips if it thinks it is on a Windows platform. .Sp Contributed by Shawn Sorichetti \f(CW\*(C`<ssoriche@coloredblocks.net>\*(C'\fR .IP "file_mode_isnt( \s-1FILENAME, MODE\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_mode_isnt( FILENAME, MODE [, NAME ] )" Ok if the file exists and mode does not match, not ok if the file does not exist or mode does match. .Sp This test automatically skips if it thinks it is on a Windows platform. .Sp Contributed by Shawn Sorichetti \f(CW\*(C`<ssoriche@coloredblocks.net>\*(C'\fR .IP "file_mode_has( \s-1FILENAME, MODE\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_mode_has( FILENAME, MODE [, NAME ] )" Ok if the file exists and has all the bits in mode turned on, not ok if the file does not exist or the mode does not match. That is, \f(CW\*(C`FILEMODE & MODE == MODE\*(C'\fR must be true. .Sp This test automatically skips if it thinks it is on a Windows platform. .Sp Contributed by Ricardo Signes \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR .IP "file_mode_hasnt( \s-1FILENAME, MODE\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_mode_hasnt( FILENAME, MODE [, NAME ] )" Ok if the file exists and has all the bits in mode turned off, not ok if the file does not exist or the mode does not match. That is, \&\f(CW\*(C`FILEMODE & MODE == 0\*(C'\fR must be true. .Sp This test automatically skips if it thinks it is on a Windows platform. .Sp Contributed by Ricardo Signes \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR .IP "file_is_symlink_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_is_symlink_ok( FILENAME [, NAME ] )" Ok if \s-1FILENAME\s0 is a symlink, even if it points to a non-existent file. This test automatically skips if the operating system does not support symlinks. .IP "file_is_not_symlink_ok( \s-1FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_is_not_symlink_ok( FILENAME [, NAME ] )" Ok if \s-1FILENAME\s0 is a not symlink. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. .IP "symlink_target_exists_ok( \s-1SYMLINK\s0 [, \s-1TARGET\s0] [, \s-1NAME\s0 ] )" 4 .IX Item "symlink_target_exists_ok( SYMLINK [, TARGET] [, NAME ] )" Ok if \s-1FILENAME\s0 is a symlink and it points to a existing file. With the optional \s-1TARGET\s0 argument, the test fails if \s-1SYMLINK\s0's target is not \&\s-1TARGET.\s0 This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. .IP "symlink_target_dangles_ok( \s-1SYMLINK\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "symlink_target_dangles_ok( SYMLINK [, NAME ] )" Ok if \s-1FILENAME\s0 is a symlink and if it doesn't point to a existing file. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. .IP "symlink_target_is( \s-1SYMLINK, TARGET\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "symlink_target_is( SYMLINK, TARGET [, NAME ] )" Ok if \s-1FILENAME\s0 is a symlink and if points to \s-1TARGET.\s0 This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. .IP "symlink_target_is_absolute_ok( \s-1SYMLINK\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "symlink_target_is_absolute_ok( SYMLINK [, NAME ] )" Ok if \s-1FILENAME\s0 is a symlink and if its target is an absolute path. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. .IP "dir_exists_ok( \s-1DIRECTORYNAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "dir_exists_ok( DIRECTORYNAME [, NAME ] )" Ok if the file exists and is a directory, not ok if the file doesn't exist, or exists but isn't a directory. .Sp Contributed by Buddy Burden \f(CW\*(C`<barefoot@cpan.org>\*(C'\fR. .IP "dir_contains_ok( \s-1DIRECTORYNAME, FILENAME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "dir_contains_ok( DIRECTORYNAME, FILENAME [, NAME ] )" Ok if the directory exists and contains the file, not ok if the directory doesn't exist, or exists but doesn't contain the file. .Sp Contributed by Buddy Burden \f(CW\*(C`<barefoot@cpan.org>\*(C'\fR. .IP "link_count_is_ok( \s-1FILE, LINK_COUNT\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "link_count_is_ok( FILE, LINK_COUNT [, NAME ] )" Ok if the link count to \s-1FILE\s0 is \s-1LINK_COUNT. LINK_COUNT\s0 is interpreted as an integer. A \s-1LINK_COUNT\s0 that evaluates to 0 returns Ok if the file does not exist. .IP "link_count_gt_ok( \s-1FILE, LINK_COUNT\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "link_count_gt_ok( FILE, LINK_COUNT [, NAME ] )" Ok if the link count to \s-1FILE\s0 is greater than \s-1LINK_COUNT. LINK_COUNT\s0 is interpreted as an integer. A \s-1LINK_COUNT\s0 that evaluates to 0 returns Ok if the file has at least one link. .IP "link_count_lt_ok( \s-1FILE, LINK_COUNT\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "link_count_lt_ok( FILE, LINK_COUNT [, NAME ] )" Ok if the link count to \s-1FILE\s0 is less than \s-1LINK_COUNT. LINK_COUNT\s0 is interpreted as an integer. A \s-1LINK_COUNT\s0 that evaluates to 0 returns Ok if the file has at least one link. .IP "owner_is( \s-1FILE , OWNER\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "owner_is( FILE , OWNER [, NAME ] )" Ok if \s-1FILE\s0's owner is the same as \s-1OWNER.\s0 \s-1OWNER\s0 may be a text user name or a numeric userid. Test skips on Dos, and Mac \s-1OS\s0 <= 9. If the file does not exist, the test fails. .Sp Contributed by Dylan Martin .IP "owner_isnt( \s-1FILE, OWNER\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "owner_isnt( FILE, OWNER [, NAME ] )" Ok if \s-1FILE\s0's owner is not the same as \s-1OWNER.\s0 \s-1OWNER\s0 may be a text user name or a numeric userid. Test skips on Dos and Mac \s-1OS\s0 <= 9. If the file does not exist, the test fails. .Sp Contributed by Dylan Martin .IP "group_is( \s-1FILE , GROUP\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "group_is( FILE , GROUP [, NAME ] )" Ok if \s-1FILE\s0's group is the same as \s-1GROUP.\s0 \s-1GROUP\s0 may be a text group name or a numeric group id. Test skips on Dos, Mac \s-1OS\s0 <= 9 and any other operating systems that do not support \fBgetpwuid()\fR and friends. If the file does not exist, the test fails. .Sp Contributed by Dylan Martin .IP "group_isnt( \s-1FILE , GROUP\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "group_isnt( FILE , GROUP [, NAME ] )" Ok if \s-1FILE\s0's group is not the same as \s-1GROUP.\s0 \s-1GROUP\s0 may be a text group name or a numeric group id. Test skips on Dos, Mac \s-1OS\s0 <= 9 and any other operating systems that do not support \fBgetpwuid()\fR and friends. If the file does not exist, the test fails. .Sp Contributed by Dylan Martin .IP "file_mtime_age_ok( \s-1FILE\s0 [, \s-1WITHIN_SECONDS\s0 ] [, \s-1NAME\s0 ] )" 4 .IX Item "file_mtime_age_ok( FILE [, WITHIN_SECONDS ] [, NAME ] )" Ok if \s-1FILE\s0's modified time is \s-1WITHIN_SECONDS\s0 inclusive of the system's current time. This test uses \fBstat()\fR to obtain the mtime. If the file does not exist the test returns failure. If \fBstat()\fR fails, the test is skipped. .IP "file_mtime_gt_ok( \s-1FILE, UNIXTIME\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_mtime_gt_ok( FILE, UNIXTIME [, NAME ] )" Ok if \s-1FILE\s0's mtime is > \s-1UNIXTIME.\s0 This test uses \fBstat()\fR to get the mtime. If \fBstat()\fR fails this test is skipped. If \s-1FILE\s0 does not exist, this test fails. .IP "file_mtime_lt_ok( \s-1FILE, UNIXTIME,\s0 [, \s-1NAME\s0 ] )" 4 .IX Item "file_mtime_lt_ok( FILE, UNIXTIME, [, NAME ] )" Ok if \s-1FILE\s0's modified time is < \s-1UNIXTIME.\s0 This test uses \fBstat()\fR to get the mtime. If \fBstat()\fR fails this test is skipped. If \s-1FILE\s0 does not exist, this test fails. .SH "TO DO" .IX Header "TO DO" * check properties for other users (readable_by_root, for instance) .PP * check times .PP * check number of links to file .PP * check path parts (directory, filename, extension) .SH "SEE ALSO" .IX Header "SEE ALSO" Test::Builder, Test::More .PP If you are using the new \f(CW\*(C`Test2\*(C'\fR stuff, see Test2::Tools::File (https://github.com/torbjorn/Test2\-Tools\-File). .SH "SOURCE AVAILABILITY" .IX Header "SOURCE AVAILABILITY" This module is in Github: .PP .Vb 1 \& https://github.com/briandfoy/test\-file .Ve .SH "AUTHOR" .IX Header "AUTHOR" brian d foy, \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR .SH "CREDITS" .IX Header "CREDITS" Shawn Sorichetti \f(CW\*(C`<ssoriche@coloredblocks.net>\*(C'\fR provided some functions. .PP Tom Metro helped me figure out some Windows capabilities. .PP Dylan Martin added \f(CW\*(C`owner_is\*(C'\fR and \f(CW\*(C`owner_isnt\*(C'\fR. .PP David Wheeler added \f(CW\*(C`file_line_count_is\*(C'\fR. .PP Buddy Burden \f(CW\*(C`<barefoot@cpan.org>\*(C'\fR provided \f(CW\*(C`dir_exists_ok\*(C'\fR, \&\f(CW\*(C`dir_contains_ok\*(C'\fR, \f(CW\*(C`file_contains_like\*(C'\fR, and \&\f(CW\*(C`file_contains_unlike\*(C'\fR. .PP xmikew \f(CW\*(C`<https://github.com/xmikew>\*(C'\fR provided the \f(CW\*(C`mtime_age\*(C'\fR stuff. .PP Torbjørn Lindahl is working on Test2::Tools::File and we're working together to align our interfaces. .PP Jean-Damien Durand added bits to use Win32::IsSymlinkCreationAllowed, new since Win32 0.55. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright © 2002\-2023, brian d foy <bdfoy@cpan.org>. All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 PK � �[ arch/auto/Test/File/.existsnu �[��� PK � �[�En�� �� lib/Test/File.pmnu ��6�$ package Test::File; use strict; use vars qw(@EXPORT $VERSION); use Carp qw(carp); use Exporter qw(import); use File::Spec; use Test::Builder; use XSLoader; @EXPORT = qw( file_exists_ok file_not_exists_ok file_empty_ok file_not_empty_ok file_size_ok file_max_size_ok file_min_size_ok file_readable_ok file_not_readable_ok file_writeable_ok file_writable_ok file_not_writeable_ok file_not_writable_ok file_executable_ok file_not_executable_ok file_mode_is file_mode_isnt file_mode_has file_mode_hasnt file_is_symlink_ok file_is_not_symlink_ok symlink_target_exists_ok symlink_target_is symlink_target_dangles_ok dir_exists_ok dir_contains_ok link_count_is_ok link_count_gt_ok link_count_lt_ok owner_is owner_isnt group_is group_isnt file_line_count_is file_line_count_isnt file_line_count_between file_contains_like file_contains_unlike file_contains_utf8_like file_contains_utf8_unlike file_contains_encoded_like file_contains_encoded_unlike file_mtime_gt_ok file_mtime_lt_ok file_mtime_age_ok ); $VERSION = '1.993'; XSLoader::load(__PACKAGE__, $VERSION) if $^O eq 'MSWin32'; my $Test = Test::Builder->new(); =encoding utf8 =head1 NAME Test::File -- test file attributes =head1 SYNOPSIS use Test::File; =head1 DESCRIPTION This modules provides a collection of test utilities for file attributes. Some file attributes depend on the owner of the process testing the file in the same way the file test operators do. For instance, root (or super-user or Administrator) may always be able to read files no matter the permissions. Some attributes don't make sense outside of Unix, either, so some tests automatically skip if they think they won't work on the platform. If you have a way to make these functions work on Windows, for instance, please send me a patch. :) If you want to pretend to be Windows on a non-Windows machine (for instance, to test C<skip()>), you can set the C<PRETEND_TO_BE_WINDOWS> environment variable. The optional NAME parameter for every function allows you to specify a name for the test. If not supplied, a reasonable default will be generated. =head2 Functions =over 4 =cut sub _is_plain_file { my $filename = _normalize( shift ); my $message = do { if( ! -e $filename ) { "does not exist" } elsif( ! -f _ ) { "is not a plain file" } elsif( -d _ ) { "is a directory" } else { () } }; if( $message ) { $Test->diag( "file [$filename] $message"); return 0; } return 1; } sub _normalize { my $file = shift; return unless defined $file; return $file =~ m|/| ? File::Spec->catfile( split m|/|, $file ) : $file; } sub _win32 { return 0 if $^O eq 'darwin'; return $ENV{PRETEND_TO_BE_WIN32} if defined $ENV{PRETEND_TO_BE_WIN32}; return $^O =~ m/Win/ || $^O eq 'msys'; } # returns true if symlinks can't exist BEGIN { my $cannot_symlink; sub _no_symlinks_here { return $cannot_symlink if defined $cannot_symlink; $cannot_symlink = ! do { eval { symlink("",""); # symlink exist in perl _IsSymlinkCreationAllowed() # symlink is ok in current session } }; } sub _IsSymlinkCreationAllowed { if ($^O eq 'MSWin32') { # # Bare copy of Perl's Win32::IsSymlinkCreationAllowed but with Test::File::Win32 namespace instead of Win32 # my(undef, $major, $minor, $build) = Test::File::Win32::GetOSVersion(); # Vista was the first Windows version with symlink support return !!0 if $major < 6; # Since Windows 10 1703, enabling the developer mode allows to create # symlinks regardless of process privileges if ($major > 10 || ($major == 10 && ($minor > 0 || $build > 15063))) { return !!1 if Test::File::Win32::IsDeveloperModeEnabled(); } my $privs = Test::File::Win32::GetProcessPrivileges(); return !!0 unless $privs; # It doesn't matter if the permission is enabled or not, it just has to # exist. CreateSymbolicLink() will automatically enable it when needed. return exists $privs->{SeCreateSymbolicLinkPrivilege}; } 1; } =item has_symlinks Returns true is this module thinks that the current system supports symlinks. This is not a test function. It's something that tests can use to determine what it should expect or skip. =cut sub has_symlinks { ! _no_symlinks_here() } } # owner_is and owner_isn't should skip on OS where the question makes no # sense. I really don't know a good way to test for that, so I'm going # to skip on the two OS's that I KNOW aren't multi-user. I'd love to add # more if anyone knows of any # Note: I don't have a dos or mac os < 10 machine to test this on sub _obviously_non_multi_user { foreach my $os ( qw(dos MacOS) ) { return 1 if $^O eq $os } return 0 if $^O eq 'MSWin32'; eval { my $holder = getpwuid(0) }; return 1 if $@; eval { my $holder = getgrgid(0) }; return 1 if $@; return 0; } =item file_exists_ok( FILENAME [, NAME ] ) Ok if the file exists, and not ok otherwise. =cut sub file_exists_ok { my $filename = _normalize( shift ); my $name = shift || "$filename exists"; my $ok = -e $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag("file [$filename] does not exist"); $Test->ok(0, $name); } } =item file_not_exists_ok( FILENAME [, NAME ] ) Ok if the file does not exist, and not okay if it does exist. =cut sub file_not_exists_ok { my $filename = _normalize( shift ); my $name = shift || "$filename does not exist"; my $ok = not -e $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag("file [$filename] exists"); $Test->ok(0, $name); } } =item file_empty_ok( FILENAME [, NAME ] ) Ok if the file exists and has empty size, not ok if the file does not exist or exists with non-zero size. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_empty_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is empty"; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); my $ok = -z $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] exists with non-zero size" ); $Test->ok(0, $name); } } =item file_not_empty_ok( FILENAME [, NAME ] ) Ok if the file exists and has non-zero size, not ok if the file does not exist or exists with zero size. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_not_empty_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is not empty"; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); my $ok = not -z _; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] exists with zero size" ); $Test->ok(0, $name); } } =item file_size_ok( FILENAME, SIZE [, NAME ] ) Ok if the file exists and has SIZE size in bytes (exactly), not ok if the file does not exist or exists with size other than SIZE. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_size_ok { my $filename = _normalize( shift ); my $expected = int shift; my $name = shift || "$filename has right size"; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); my $ok = ( -s $filename ) == $expected; if( $ok ) { $Test->ok(1, $name); } else { my $actual = -s $filename; $Test->diag( "file [$filename] has actual size [$actual] not [$expected]" ); $Test->ok(0, $name); } } =item file_max_size_ok( FILENAME, MAX [, NAME ] ) Ok if the file exists and has size less than or equal to MAX bytes, not ok if the file does not exist or exists with size greater than MAX bytes. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_max_size_ok { my $filename = _normalize( shift ); my $max = int shift; my $name = shift || "$filename is under $max bytes"; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); my $ok = ( -s $filename ) <= $max; if( $ok ) { $Test->ok(1, $name); } else { my $actual = -s $filename; $Test->diag( "file [$filename] has actual size [$actual] " . "greater than [$max]" ); $Test->ok(0, $name); } } =item file_min_size_ok( FILENAME, MIN [, NAME ] ) Ok if the file exists and has size greater than or equal to MIN bytes, not ok if the file does not exist or exists with size less than MIN bytes. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_min_size_ok { my $filename = _normalize( shift ); my $min = int shift; my $name = shift || "$filename is over $min bytes"; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); my $ok = ( -s $filename ) >= $min; if( $ok ) { $Test->ok(1, $name); } else { my $actual = -s $filename; $Test->diag( "file [$filename] has actual size ". "[$actual] less than [$min]" ); $Test->ok(0, $name); } } =item file_line_count_is( FILENAME, COUNT [, NAME ] ) Ok if the file exists and has COUNT lines (exactly), not ok if the file does not exist or exists with a line count other than COUNT. This function uses the current value of C<$/> as the line ending and counts the lines by reading them and counting how many it read. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub _ENOFILE () { -1 } sub _ECANTOPEN () { -2 } sub _ENOTPLAIN () { -3 } sub _file_line_counter { my $filename = shift; return _ENOFILE unless -e $filename; return _ENOTPLAIN unless -f $filename; return _ECANTOPEN unless open my( $fh ), "<", $filename; my $count = 0; while( <$fh> ) { $count++ } return $count; } # XXX: lots of cut and pasting here, needs refactoring # looks like the refactoring might be worse than this though sub file_line_count_is { my $filename = _normalize( shift ); my $expected = shift; my $name = do { no warnings 'uninitialized'; shift || "$filename line count is $expected lines"; }; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); unless( defined $expected && int( $expected ) == $expected ) { no warnings 'uninitialized'; $Test->diag( "file_line_count_is expects a positive whole number for " . "the second argument. Got [$expected]" ); return $Test->ok( 0, $name ); } my $got = _file_line_counter( $filename ); if( $got eq _ENOFILE ) { $Test->diag( "file [$filename] does not exist" ); $Test->ok( 0, $name ); } elsif( $got eq _ENOTPLAIN ) { $Test->diag( "file [$filename] is not a plain file" ); $Test->ok( 0, $name ); } elsif( $got == _ECANTOPEN ) { $Test->diag( "file [$filename] could not be opened: \$! is [$!]" ); $Test->ok( 0, $name ); } elsif( $got == $expected ) { $Test->ok( 1, $name ); } else { $Test->diag( "expected [$expected] lines in [$filename], " . "got [$got] lines" ); $Test->ok( 0, $name ); } } =item file_line_count_isnt( FILENAME, COUNT [, NAME ] ) Ok if the file exists and doesn't have exactly COUNT lines, not ok if the file does not exist or exists with a line count of COUNT. Read that carefully: the file must exist for this test to pass! This function uses the current value of C<$/> as the line ending and counts the lines by reading them and counting how many it read. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_line_count_isnt { my $filename = _normalize( shift ); my $expected = shift; my $name = do { no warnings 'uninitialized'; shift || "$filename line count is not $expected lines"; }; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); unless( defined $expected && int( $expected ) == $expected ) { no warnings 'uninitialized'; $Test->diag( "file_line_count_is expects a positive whole number for " . "the second argument. Got [$expected]" ); return $Test->ok( 0, $name ); } my $got = _file_line_counter( $filename ); if( $got eq _ENOFILE ) { $Test->diag( "file [$filename] does not exist" ); $Test->ok( 0, $name ); } elsif( $got eq _ENOTPLAIN ) { $Test->diag( "file [$filename] is not a plain file" ); $Test->ok( 0, $name ); } elsif( $got == _ECANTOPEN ) { $Test->diag( "file [$filename] could not be opened: \$! is [$!]" ); $Test->ok( 0, $name ); } elsif( $got != $expected ) { $Test->ok( 1, $name ); } else { $Test->diag( "expected something other than [$expected] lines in [$filename], " . "but got [$got] lines" ); $Test->ok( 0, $name ); } } =item file_line_count_between( FILENAME, MIN, MAX, [, NAME ] ) Ok if the file exists and has a line count between MIN and MAX, inclusively. This function uses the current value of C<$/> as the line ending and counts the lines by reading them and counting how many it read. Previously this tried to test any sort of file. Sometime in the future this will fail if the argument is not a plain file or is a directory. =cut sub file_line_count_between { my $filename = _normalize( shift ); my $min = shift; my $max = shift; my $name = do { no warnings 'uninitialized'; shift || "$filename line count is between [$min] and [$max] lines"; }; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); foreach my $ref ( \$min, \$max ) { unless( defined $$ref && int( $$ref ) == $$ref ) { no warnings 'uninitialized'; $Test->diag( "file_line_count_between expects positive whole numbers for " . "the second and third arguments. Got [$min] and [$max]" ); return $Test->ok( 0, $name ); } } my $got = _file_line_counter( $filename ); if( $got eq _ENOFILE ) { $Test->diag( "file [$filename] does not exist" ); $Test->ok( 0, $name ); } elsif( $got eq _ENOTPLAIN ) { $Test->diag( "file [$filename] is not a plain file" ); $Test->ok( 0, $name ); } elsif( $got == _ECANTOPEN ) { $Test->diag( "file [$filename] could not be opened: \$! is [$!]" ); $Test->ok( 0, $name ); } elsif( $min <= $got and $got <= $max ) { $Test->ok( 1, $name ); } else { $Test->diag( "expected a line count between [$min] and [$max] " . "in [$filename], but got [$got] lines" ); $Test->ok( 0, $name ); } } =item file_contains_like ( FILENAME, PATTERN [, NAME ] ) Ok if the file exists and its contents (as one big string) match PATTERN, not ok if the file does not exist, is not readable, or exists but doesn't match PATTERN. Since the file contents are read into memory, you should not use this for large files. Besides memory consumption, test diagnostics for failing tests might be difficult to decipher. However, for short files this works very well. Because the entire contents are treated as one large string, you can make a pattern that tests multiple lines. Don't forget that you may need to use the /s modifier for such patterns: # make sure file has one or more paragraphs with CSS class X file_contains_like($html_file, qr{<p class="X">.*?</p>}s); Contrariwise, if you need to match at the beginning or end of a line inside the file, use the /m modifier: # make sure file has a setting for foo file_contains_like($config_file, qr/^ foo \s* = \s* \w+ $/mx); If you want to test your file contents against multiple patterns, but don't want to have the file read in repeatedly, you can pass an arrayref of patterns instead of a single pattern, like so: # make sure our template has rendered correctly file_contains_like($template_out, [ qr/^ $title_line $/mx, map { qr/^ $_ $/mx } @chapter_headings, qr/^ $footer_line $/mx, ]); Please note that if you do this, and your file does not exist or is not readable, you'll only get one test failure instead of a failure for each pattern. This could cause your test plan to be off, although you may not care at that point because your test failed anyway. If you do care, either skip the test plan altogether by employing L<Test::More>'s C<done_testing()> function, or use L</file_readable_ok> in conjunction with a C<SKIP> block. Contributed by Buddy Burden C<< <barefoot@cpan.org> >>. =item file_contains_unlike ( FILENAME, PATTERN [, NAME ] ) Ok if the file exists and its contents (as one big string) do B<not> match PATTERN, not ok if the file does not exist, is not readable, or exists but matches PATTERN. All notes and caveats for L</file_contains_like> apply to this function as well. Contributed by Buddy Burden C<< <barefoot@cpan.org> >>. =item file_contains_utf8_like ( FILENAME, PATTERN [, NAME ] ) The same as C<file_contains_like>, except the file is opened as UTF-8. =item file_contains_utf8_unlike ( FILENAME, PATTERN [, NAME ] ) The same as C<file_contains_unlike>, except the file is opened as UTF-8. =item file_contains_encoded_like ( FILENAME, ENCODING, PATTERN [, NAME ] ) The same as C<file_contains_like>, except the file is opened with ENCODING =item file_contains_encoded_unlike ( FILENAME, ENCODING, PATTERN [, NAME ] ) The same as C<file_contains_unlike>, except the file is opened with ENCODING. =cut sub file_contains_like { local $Test::Builder::Level = $Test::Builder::Level + 1; _file_contains(like => "contains", undef, @_); } sub file_contains_unlike { local $Test::Builder::Level = $Test::Builder::Level + 1; _file_contains(unlike => "doesn't contain", undef, @_); } sub file_contains_utf8_like { local $Test::Builder::Level = $Test::Builder::Level + 1; _file_contains(like => "contains", 'UTF-8', @_); } sub file_contains_utf8_unlike { local $Test::Builder::Level = $Test::Builder::Level + 1; _file_contains(unlike => "doesn't contain", 'UTF-8', @_); } sub file_contains_encoded_like { local $Test::Builder::Level = $Test::Builder::Level + 1; my $filename = shift; my $encoding = shift; _file_contains(like => "contains", $encoding, $filename, @_); } sub file_contains_encoded_unlike { local $Test::Builder::Level = $Test::Builder::Level + 1; my $filename = shift; my $encoding = shift; _file_contains(unlike => "doesn't contain", $encoding, $filename, @_); } sub _file_contains { my $method = shift; my $verb = shift; my $encoding = shift; my $filename = _normalize( shift ); my $patterns = shift; my $name = shift; my (@patterns, %patterns); if (ref $patterns eq 'ARRAY') { @patterns = @$patterns; %patterns = map { $_ => $name || "$filename $verb $_" } @patterns; } else { @patterns = ($patterns); %patterns = ( $patterns => $name || "$filename $verb $patterns" ); } # for purpose of checking the file's existence, just use the first # test name as the name $name = $patterns{$patterns[0]}; return $Test->ok( 0, $name ) unless _is_plain_file( $filename ); unless( -r $filename ) { $Test->diag( "file [$filename] is not readable" ); return $Test->ok(0, $name); } # do the slurp my $file_contents; { unless (open(FH, $filename)) { $Test->diag( "file [$filename] could not be opened: \$! is [$!]" ); return $Test->ok( 0, $name ); } if (defined $encoding) { binmode FH, ":encoding($encoding)"; } local $/ = undef; $file_contents = <FH>; close FH; } foreach my $p (@patterns) { $Test->$method($file_contents, $p, $patterns{$p}); } } =item file_readable_ok( FILENAME [, NAME ] ) Ok if the file exists and is readable, not ok if the file does not exist or is not readable. =cut sub file_readable_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is readable"; my $ok = -r $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] is not readable" ); $Test->ok(0, $name); } } =item file_not_readable_ok( FILENAME [, NAME ] ) Ok if the file exists and is not readable, not ok if the file does not exist or is readable. =cut sub file_not_readable_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is not readable"; my $ok = not -r $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] is readable" ); $Test->ok(0, $name); } } =item file_writable_ok( FILENAME [, NAME ] ) =item file_writeable_ok( FILENAME [, NAME ] ) Ok if the file exists and is writable, not ok if the file does not exist or is not writable. The original name is C<file_writeable_ok> with that extra I<e>. That still works but there's a function with the correct spelling too. =cut sub file_writeable_ok { carp "file_writeable_ok is now file_writable_ok"; &file_writable_ok; } sub file_writable_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is writable"; my $ok = -w $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] is not writable" ); $Test->ok(0, $name); } } =item file_not_writeable_ok( FILENAME [, NAME ] ) =item file_not_writable_ok( FILENAME [, NAME ] ) Ok if the file exists and is not writable, not ok if the file does not exist or is writable. The original name is C<file_not_writeable_ok> with that extra I<e>. That still works but there's a function with the correct spelling too. =cut sub file_not_writeable_ok { carp "file_not_writeable_ok is now file_not_writable_ok"; &file_not_writable_ok; } sub file_not_writable_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is not writable"; my $ok = not -w $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag("file [$filename] is writable"); $Test->ok(0, $name); } } =item file_executable_ok( FILENAME [, NAME ] ) Ok if the file exists and is executable, not ok if the file does not exist or is not executable. This test automatically skips if it thinks it is on a Windows platform. =cut sub file_executable_ok { if( _win32() ) { $Test->skip( "file_executable_ok doesn't work on Windows" ); return; } my $filename = _normalize( shift ); my $name = shift || "$filename is executable"; my $ok = -x $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag("file [$filename] is not executable"); $Test->ok(0, $name); } } =item file_not_executable_ok( FILENAME [, NAME ] ) Ok if the file exists and is not executable, not ok if the file does not exist or is executable. This test automatically skips if it thinks it is on a Windows platform. =cut sub file_not_executable_ok { if( _win32() ) { $Test->skip( "file_not_executable_ok doesn't work on Windows" ); return; } my $filename = _normalize( shift ); my $name = shift || "$filename is not executable"; my $ok = not -x $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag("file [$filename] is executable"); $Test->ok(0, $name); } } =item file_mode_is( FILENAME, MODE [, NAME ] ) Ok if the file exists and the mode matches, not ok if the file does not exist or the mode does not match. This test automatically skips if it thinks it is on a Windows platform. Contributed by Shawn Sorichetti C<< <ssoriche@coloredblocks.net> >> =cut sub file_mode_is { if( _win32() ) { $Test->skip( "file_mode_is doesn't work on Windows" ); return; } my $filename = _normalize( shift ); my $mode = shift; my $name = shift || sprintf("%s mode is %04o", $filename, $mode); my $ok = -e $filename && ((stat($filename))[2] & 07777) == $mode; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag(sprintf("file [%s] mode is not %04o", $filename, $mode) ); $Test->ok(0, $name); } } =item file_mode_isnt( FILENAME, MODE [, NAME ] ) Ok if the file exists and mode does not match, not ok if the file does not exist or mode does match. This test automatically skips if it thinks it is on a Windows platform. Contributed by Shawn Sorichetti C<< <ssoriche@coloredblocks.net> >> =cut sub file_mode_isnt { if( _win32() ) { $Test->skip( "file_mode_isnt doesn't work on Windows" ); return; } my $filename = _normalize( shift ); my $mode = shift; my $name = shift || sprintf("%s mode is not %04o",$filename,$mode); my $ok = not (-e $filename && ((stat($filename))[2] & 07777) == $mode); if( $ok ) { $Test->ok(1, $name); } else { $Test->diag(sprintf("file [%s] mode is %04o",$filename,$mode)); $Test->ok(0, $name); } } =item file_mode_has( FILENAME, MODE [, NAME ] ) Ok if the file exists and has all the bits in mode turned on, not ok if the file does not exist or the mode does not match. That is, C<< FILEMODE & MODE == MODE >> must be true. This test automatically skips if it thinks it is on a Windows platform. Contributed by Ricardo Signes C<< <rjbs@cpan.org> >> =cut sub file_mode_has { if( _win32() ) { $Test->skip( "file_mode_has doesn't work on Windows" ); return; } my $filename = _normalize( shift ); my $mode = shift; my $name = shift || sprintf("%s mode has all bits of %04o", $filename, $mode); my $present = -e $filename; my $gotmode = $present ? (stat($filename))[2] : undef; my $ok = $present && ($gotmode & $mode) == $mode; if( $ok ) { $Test->ok(1, $name); } else { my $missing = ($gotmode ^ $mode) & $mode; $Test->diag(sprintf("file [%s] mode is missing component %04o", $filename, $missing) ); $Test->ok(0, $name); } } =item file_mode_hasnt( FILENAME, MODE [, NAME ] ) Ok if the file exists and has all the bits in mode turned off, not ok if the file does not exist or the mode does not match. That is, C<< FILEMODE & MODE == 0 >> must be true. This test automatically skips if it thinks it is on a Windows platform. Contributed by Ricardo Signes C<< <rjbs@cpan.org> >> =cut sub file_mode_hasnt { if( _win32() ) { $Test->skip( "file_mode_hasnt doesn't work on Windows" ); return; } my $filename = _normalize( shift ); my $mode = shift; my $name = shift || sprintf("%s mode has no bits of %04o", $filename, $mode); my $present = -e $filename; my $gotmode = $present ? (stat($filename))[2] : undef; my $ok = $present && ($gotmode & $mode) == 0; if( $ok ) { $Test->ok(1, $name); } else { my $bad = $gotmode & $mode; $Test->diag(sprintf("file [%s] mode has forbidden component %04o", $filename, $bad) ); $Test->ok(0, $name); } } =item file_is_symlink_ok( FILENAME [, NAME ] ) Ok if FILENAME is a symlink, even if it points to a non-existent file. This test automatically skips if the operating system does not support symlinks. =cut sub file_is_symlink_ok { if( _no_symlinks_here() ) { $Test->skip( "file_is_symlink_ok doesn't work on systems without symlinks" ); return; } my $file = shift; my $name = shift || "$file is a symlink"; if( -l $file ) { $Test->ok(1, $name) } else { $Test->diag( "file [$file] is not a symlink" ); $Test->ok(0, $name); } } =item file_is_not_symlink_ok( FILENAME [, NAME ] ) Ok if FILENAME is a not symlink. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. =cut sub file_is_not_symlink_ok { if( _no_symlinks_here() ) { $Test->skip( "file_is_symlink_ok doesn't work on systems without symlinks" ); return; } my $file = shift; my $name = shift || "$file is not a symlink"; unless( -e $file ) { $Test->diag( "file [$file] does not exist" ); return $Test->ok(0, $name); } if( ! -l $file ) { $Test->ok(1, $name) } else { $Test->diag( "file [$file] is a symlink" ); $Test->ok(0, $name); } } =item symlink_target_exists_ok( SYMLINK [, TARGET] [, NAME ] ) Ok if FILENAME is a symlink and it points to a existing file. With the optional TARGET argument, the test fails if SYMLINK's target is not TARGET. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. =cut sub symlink_target_exists_ok { if( _no_symlinks_here() ) { $Test->skip( "symlink_target_exists_ok doesn't work on systems without symlinks" ); return; } my $file = shift; my $dest = shift || readlink( $file ); my $name = shift || "$file is a symlink"; unless( -l $file ) { $Test->diag( "file [$file] is not a symlink" ); return $Test->ok( 0, $name ); } unless( -e $dest ) { $Test->diag( "symlink [$file] points to non-existent target [$dest]" ); return $Test->ok( 0, $name ); } my $actual = readlink( $file ); unless( $dest eq $actual ) { $Test->diag( "symlink [$file] points to\n" . " got: $actual\n" . " expected: $dest\n" ); return $Test->ok( 0, $name ); } $Test->ok( 1, $name ); } =item symlink_target_dangles_ok( SYMLINK [, NAME ] ) Ok if FILENAME is a symlink and if it doesn't point to a existing file. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. =cut sub symlink_target_dangles_ok { if( _no_symlinks_here() ) { $Test->skip( "symlink_target_dangles_ok doesn't work on systems without symlinks" ); return; } my $file = shift; my $dest = readlink( $file ); my $name = shift || "$file is a symlink"; unless( -l $file ) { $Test->diag( "file [$file] is not a symlink" ); return $Test->ok( 0, $name ); } if( -e $dest ) { $Test->diag( "symlink [$file] points to existing file [$dest] but shouldn't" ); return $Test->ok( 0, $name ); } $Test->ok( 1, $name ); } =item symlink_target_is( SYMLINK, TARGET [, NAME ] ) Ok if FILENAME is a symlink and if points to TARGET. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. =cut sub symlink_target_is { if( _no_symlinks_here() ) { $Test->skip( "symlink_target_is doesn't work on systems without symlinks" ); return; } my $file = shift; my $dest = shift; my $name = shift || "symlink $file points to $dest"; unless( -l $file ) { $Test->diag( "file [$file] is not a symlink" ); return $Test->ok( 0, $name ); } my $actual_dest = readlink( $file ); my $link_error = $!; unless( defined $actual_dest ) { $Test->diag( "symlink [$file] does not have a defined target" ); $Test->diag( "readlink error: $link_error" ) if defined $link_error; return $Test->ok( 0, $name ); } if( $dest eq $actual_dest ) { $Test->ok( 1, $name ); } else { $Test->ok( 0, $name ); $Test->diag(" got: $actual_dest" ); $Test->diag(" expected: $dest" ); } } =item symlink_target_is_absolute_ok( SYMLINK [, NAME ] ) Ok if FILENAME is a symlink and if its target is an absolute path. This test automatically skips if the operating system does not support symlinks. If the file does not exist, the test fails. =cut sub symlink_target_is_absolute_ok { if( _no_symlinks_here() ) { $Test->skip( "symlink_target_exists_ok doesn't work on systems without symlinks" ); return; } my( $from, $from_base, $to, $to_base, $name ) = @_; my $link = readlink( $from ); my $link_err = defined( $link ) ? '' : $!; # $! doesn't always get reset my $link_abs = abs_path( rel2abs($link, $from_base) ); my $to_abs = abs_path( rel2abs($to, $to_base) ); if (defined( $link_abs ) && defined( $to_abs ) && $link_abs eq $to_abs) { $Test->ok( 1, $name ); } else { $Test->ok( 0, $name ); $link ||= 'undefined'; $link_abs ||= 'undefined'; $to_abs ||= 'undefined'; $Test->diag(" link: $from"); $Test->diag(" got: $link"); $Test->diag(" (abs): $link_abs"); $Test->diag(" expected: $to"); $Test->diag(" (abs): $to_abs"); $Test->diag(" readlink() error: $link_err") if ($link_err); } } =item dir_exists_ok( DIRECTORYNAME [, NAME ] ) Ok if the file exists and is a directory, not ok if the file doesn't exist, or exists but isn't a directory. Contributed by Buddy Burden C<< <barefoot@cpan.org> >>. =cut sub dir_exists_ok { my $filename = _normalize( shift ); my $name = shift || "$filename is a directory"; unless( -e $filename ) { $Test->diag( "directory [$filename] does not exist" ); return $Test->ok(0, $name); } my $ok = -d $filename; if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] exists but is not a directory" ); $Test->ok(0, $name); } } =item dir_contains_ok( DIRECTORYNAME, FILENAME [, NAME ] ) Ok if the directory exists and contains the file, not ok if the directory doesn't exist, or exists but doesn't contain the file. Contributed by Buddy Burden C<< <barefoot@cpan.org> >>. =cut sub dir_contains_ok { my $dirname = _normalize( shift ); my $filename = _normalize( shift ); my $name = shift || "directory $dirname contains file $filename"; unless( -d $dirname ) { $Test->diag( "directory [$dirname] does not exist" ); return $Test->ok(0, $name); } my $ok = -e File::Spec->catfile($dirname, $filename); if( $ok ) { $Test->ok(1, $name); } else { $Test->diag( "file [$filename] does not exist in directory $dirname" ); $Test->ok(0, $name); } } =item link_count_is_ok( FILE, LINK_COUNT [, NAME ] ) Ok if the link count to FILE is LINK_COUNT. LINK_COUNT is interpreted as an integer. A LINK_COUNT that evaluates to 0 returns Ok if the file does not exist. =cut sub link_count_is_ok { my $file = shift; my $count = int( 0 + shift ); my $name = shift || "$file has a link count of [$count]"; my $actual = ( stat $file )[3]; unless( $actual == $count ) { $Test->diag( "file [$file] points has [$actual] links: expected [$count]" ); return $Test->ok( 0, $name ); } $Test->ok( 1, $name ); } =item link_count_gt_ok( FILE, LINK_COUNT [, NAME ] ) Ok if the link count to FILE is greater than LINK_COUNT. LINK_COUNT is interpreted as an integer. A LINK_COUNT that evaluates to 0 returns Ok if the file has at least one link. =cut sub link_count_gt_ok { my $file = shift; my $count = int( 0 + shift ); my $name = shift || "$file has a link count of [$count]"; my $actual = (stat $file )[3]; unless( $actual > $count ) { $Test->diag( "file [$file] points has [$actual] links: ". "expected more than [$count]" ); return $Test->ok( 0, $name ); } $Test->ok( 1, $name ); } =item link_count_lt_ok( FILE, LINK_COUNT [, NAME ] ) Ok if the link count to FILE is less than LINK_COUNT. LINK_COUNT is interpreted as an integer. A LINK_COUNT that evaluates to 0 returns Ok if the file has at least one link. =cut sub link_count_lt_ok { my $file = shift; my $count = int( 0 + shift ); my $name = shift || "$file has a link count of [$count]"; my $actual = (stat $file )[3]; unless( $actual < $count ) { $Test->diag( "file [$file] points has [$actual] links: ". "expected less than [$count]" ); return $Test->ok( 0, $name ); } $Test->ok( 1, $name ); } # owner_is, owner_isnt, group_is and group_isnt are almost # identical in the beginning, so I'm writing a skeleton they can all use. # I can't think of a better name... sub _dm_skeleton { no warnings 'uninitialized'; if( _obviously_non_multi_user() ) { my $calling_sub = (caller(1))[3]; $Test->skip( $calling_sub . " only works on a multi-user OS" ); return 'skip'; } my $filename = _normalize( shift ); my $testing_for = shift; my $name = shift; unless( defined $filename ) { $Test->diag( "file name not specified" ); return $Test->ok( 0, $name ); } unless( -e $filename ) { $Test->diag( "file [$filename] does not exist" ); return $Test->ok( 0, $name ); } return; } =item owner_is( FILE , OWNER [, NAME ] ) Ok if FILE's owner is the same as OWNER. OWNER may be a text user name or a numeric userid. Test skips on Dos, and Mac OS <= 9. If the file does not exist, the test fails. Contributed by Dylan Martin =cut sub owner_is { my $filename = shift; my $owner = shift; my $name = shift || "$filename belongs to $owner"; my $err = _dm_skeleton( $filename, $owner, $name ); return if( defined( $err ) && $err eq 'skip' ); return $err if defined($err); my $owner_uid = _get_uid( $owner ); unless( defined $owner_uid ) { $Test->diag("user [$owner] does not exist on this system"); return $Test->ok( 0, $name ); } my $file_uid = ( stat $filename )[4]; unless( defined $file_uid ) { $Test->skip("stat failed to return owner uid for $filename"); return; } return $Test->ok( 1, $name ) if $file_uid == $owner_uid; my $real_owner = ( getpwuid $file_uid )[0]; unless( defined $real_owner ) { $Test->diag("file does not belong to $owner"); return $Test->ok( 0, $name ); } $Test->diag( "file [$filename] belongs to $real_owner ($file_uid), ". "not $owner ($owner_uid)" ); return $Test->ok( 0, $name ); } =item owner_isnt( FILE, OWNER [, NAME ] ) Ok if FILE's owner is not the same as OWNER. OWNER may be a text user name or a numeric userid. Test skips on Dos and Mac OS <= 9. If the file does not exist, the test fails. Contributed by Dylan Martin =cut sub owner_isnt { my $filename = shift; my $owner = shift; my $name = shift || "$filename doesn't belong to $owner"; my $err = _dm_skeleton( $filename, $owner, $name ); return if( defined( $err ) && $err eq 'skip' ); return $err if defined($err); my $owner_uid = _get_uid( $owner ); unless( defined $owner_uid ) { return $Test->ok( 1, $name ); } my $file_uid = ( stat $filename )[4]; #$Test->diag( "owner_isnt: $owner_uid $file_uid" ); return $Test->ok( 1, $name ) if $file_uid != $owner_uid; $Test->diag( "file [$filename] belongs to $owner ($owner_uid)" ); return $Test->ok( 0, $name ); } =item group_is( FILE , GROUP [, NAME ] ) Ok if FILE's group is the same as GROUP. GROUP may be a text group name or a numeric group id. Test skips on Dos, Mac OS <= 9 and any other operating systems that do not support getpwuid() and friends. If the file does not exist, the test fails. Contributed by Dylan Martin =cut sub group_is { my $filename = shift; my $group = shift; my $name = ( shift || "$filename belongs to group $group" ); my $err = _dm_skeleton( $filename, $group, $name ); return if( defined( $err ) && $err eq 'skip' ); return $err if defined($err); my $group_gid = _get_gid( $group ); unless( defined $group_gid ) { $Test->diag("group [$group] does not exist on this system"); return $Test->ok( 0, $name ); } my $file_gid = ( stat $filename )[5]; unless( defined $file_gid ) { $Test->skip("stat failed to return group gid for $filename"); return; } return $Test->ok( 1, $name ) if $file_gid == $group_gid; my $real_group = ( getgrgid $file_gid )[0]; unless( defined $real_group ) { $Test->diag("file does not belong to $group"); return $Test->ok( 0, $name ); } $Test->diag( "file [$filename] belongs to $real_group ($file_gid), ". "not $group ($group_gid)" ); return $Test->ok( 0, $name ); } =item group_isnt( FILE , GROUP [, NAME ] ) Ok if FILE's group is not the same as GROUP. GROUP may be a text group name or a numeric group id. Test skips on Dos, Mac OS <= 9 and any other operating systems that do not support getpwuid() and friends. If the file does not exist, the test fails. Contributed by Dylan Martin =cut sub group_isnt { my $filename = shift; my $group = shift; my $name = shift || "$filename does not belong to group $group"; my $err = _dm_skeleton( $filename, $group, $name ); return if( defined( $err ) && $err eq 'skip' ); return $err if defined($err); my $group_gid = _get_gid( $group ); my $file_gid = ( stat $filename )[5]; unless( defined $file_gid ) { $Test->skip("stat failed to return group gid for $filename"); return; } return $Test->ok( 1, $name ) if $file_gid != $group_gid; $Test->diag( "file [$filename] belongs to $group ($group_gid)" ); return $Test->ok( 0, $name ); } sub _get_uid { my $arg = shift; # the name might be numeric (why would you do that?), so we need # to figure out which of several possibilities we have. And, 0 means # root, so we have to be very careful with the values. # maybe the argument is a UID. First, it has to be numeric. If it's # a UID, we'll get the same UID back. But, if we get back a value # that doesn't mean that we are done. There might be a name with # the same value. # # Don't use this value in comparisons! An undef could be turned # into zero! my $from_uid = (getpwuid($arg))[2] if $arg =~ /\A[0-9]+\z/; # Now try the argument as a name. If it's a name, then we'll get # back a UID. Maybe we get back nothing. my $from_nam = (getpwnam($arg))[2]; return do { # first case, we got back nothing from getpwnam but did get # something from getpwuid. The arg is not a name and is a # UID. if( defined $from_uid and not defined $from_nam ) { $arg } # second case, we got back nothing from getpwuid but did get # something from getpwnam. The arg is a name and is not a # UID. elsif( not defined $from_uid and defined $from_nam ) { $from_nam } # Now, what happens if neither are defined? The argument does # not correspond to a name or GID on the system. Since no such # user exists, we return undef. elsif( not defined $from_uid and not defined $from_nam ) { undef } # But what if they are both defined? The argument could represent # a UID and a name, and those could be different users! In this # case, we'll choose the original argument. That might be wrong, # so the best we can do is a warning. else { carp( "Found both a UID or name for <$arg>. Guessing the UID is <$arg>." ); $arg } }; } sub _get_gid { my $arg = shift; # the name might be numeric (why would you do that?), so we need # to figure out which of several possibilities we have. And, 0 means # root, so we have to be very careful with the values. # maybe the argument is a GID. First, it has to be numeric. If it's # a GID, we'll get the same GID back. But, if we get back a value # that doesn't mean that we are done. There might be a name with # the same value. # # Don't use this value in comparisons! An undef could be turned # into zero! my $from_gid = (getgrgid($arg))[2] if $arg =~ /\A[0-9]+\z/; # Now try the argument as a name. If it's a name, then we'll get # back a GID. Maybe we get back nothing. my $from_nam = (getgrnam($arg))[2]; return do { # first case, we got back nothing from getgrnam but did get # something from getpwuid. The arg is not a name and is a # GID. if( defined $from_gid and not defined $from_nam ) { $arg } # second case, we got back nothing from getgrgid but did get # something from getgrnam. The arg is a name and is not a # GID. elsif( not defined $from_gid and defined $from_nam ) { $from_nam } # Now, what happens if neither are defined? The argument does # not correspond to a name or GID on the system. Since no such # user exists, we return undef. elsif( not defined $from_gid and not defined $from_nam ) { undef } # But what if they are both defined? The argument could represent # a GID and a name, and those could be different users! In this # case, we'll choose the original argument. That might be wrong, # so the best we can do is a warning. else { carp( "Found both a GID or name for <$arg>. Guessing the GID is <$arg>." ); $arg; } }; } =item file_mtime_age_ok( FILE [, WITHIN_SECONDS ] [, NAME ] ) Ok if FILE's modified time is WITHIN_SECONDS inclusive of the system's current time. This test uses stat() to obtain the mtime. If the file does not exist the test returns failure. If stat() fails, the test is skipped. =cut sub file_mtime_age_ok { my $filename = shift; my $within_secs = shift || 0; my $name = shift || "$filename mtime within $within_secs seconds of current time"; my $time = time(); my $filetime = _stat_file($filename, 9); return if ( $filetime == -1 ); #skip return $Test->ok(1, $name) if ( $filetime + $within_secs > $time-1 ); $Test->diag( "file [$filename] mtime [$filetime] is not $within_secs seconds within current system time [$time]."); return $Test->ok(0, $name); } =item file_mtime_gt_ok( FILE, UNIXTIME [, NAME ] ) Ok if FILE's mtime is > UNIXTIME. This test uses stat() to get the mtime. If stat() fails this test is skipped. If FILE does not exist, this test fails. =cut sub file_mtime_gt_ok { my $filename = shift; my $time = int shift; my $name = shift || "$filename mtime is greater than unix timestamp $time"; my $filetime = _stat_file($filename, 9); return if ( $filetime == -1 ); #skip return $Test->ok(1, $name) if ( $filetime > $time ); $Test->diag( "file [$filename] mtime [$filetime] not greater than $time" ); $Test->ok(0, $name); } =item file_mtime_lt_ok( FILE, UNIXTIME, [, NAME ] ) Ok if FILE's modified time is < UNIXTIME. This test uses stat() to get the mtime. If stat() fails this test is skipped. If FILE does not exist, this test fails. =cut sub file_mtime_lt_ok { my $filename = shift; my $time = int shift; my $name = shift || "$filename mtime less than unix timestamp $time"; # gets mtime my $filetime = _stat_file($filename, 9); return if ( $filetime == -1 ); #skip return $Test->ok(1, $name) if ( $filetime < $time ); $Test->diag( "file [$filename] mtime [$filetime] not less than $time" ); $Test->ok(0, $name); } # private function to safely stat a file # # Arugments: # filename file to perform on # attr_pos pos of the array returned from stat we want to compare. perldoc -f stat # # Returns: # -1 - stat failed # 0 - failure (file doesn't exist etc) # filetime - on success, time requested provided by stat # sub _stat_file { my $filename = _normalize( shift ); my $attr_pos = shift; unless( defined $filename ) { $Test->diag( "file name not specified" ); return 0; } unless( -e $filename ) { $Test->diag( "file [$filename] does not exist" ); return 0; } my $filetime = ( stat($filename) )[$attr_pos]; unless( $filetime ) { $Test->diag( "stat of $filename failed" ); return -1; #skip on stat failure } return $filetime; } =back =head1 TO DO * check properties for other users (readable_by_root, for instance) * check times * check number of links to file * check path parts (directory, filename, extension) =head1 SEE ALSO L<Test::Builder>, L<Test::More> If you are using the new C<Test2> stuff, see Test2::Tools::File (https://github.com/torbjorn/Test2-Tools-File). =head1 SOURCE AVAILABILITY This module is in Github: https://github.com/briandfoy/test-file =head1 AUTHOR brian d foy, C<< <bdfoy@cpan.org> >> =head1 CREDITS Shawn Sorichetti C<< <ssoriche@coloredblocks.net> >> provided some functions. Tom Metro helped me figure out some Windows capabilities. Dylan Martin added C<owner_is> and C<owner_isnt>. David Wheeler added C<file_line_count_is>. Buddy Burden C<< <barefoot@cpan.org> >> provided C<dir_exists_ok>, C<dir_contains_ok>, C<file_contains_like>, and C<file_contains_unlike>. xmikew C<< <https://github.com/xmikew> >> provided the C<mtime_age> stuff. Torbjørn Lindahl is working on L<Test2::Tools::File> and we're working together to align our interfaces. Jean-Damien Durand added bits to use Win32::IsSymlinkCreationAllowed, new since Win32 0.55. =head1 COPYRIGHT AND LICENSE Copyright © 2002-2023, brian d foy <bdfoy@cpan.org>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 =cut "The quick brown fox jumped over the lazy dog"; PK � �[ lib/auto/Test/File/.existsnu �[��� PK � �[Eֿ�TN TN $ man3/cPanel::PublicAPI::WHM::API.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM::API 3" .TH cPanel::PublicAPI::WHM::API 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM::API \- Legacy interface for querying the xml\-api. .PP NOTE: This module is provided for legacy purposes, cPanel::PublicAPI should be used instead .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides legacy compatibility support between cPanel::PublicAPI and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). .PP Every method contained within this object can be queried using \fBcPanel::publicAPI::whm_api()\fR instead. .PP For more information on the calls within the methods contained here and what the parameter names mean, please read the documentation at: <http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi> .SH "functions" .IX Header "functions" .ie n .SS """api_listaccts()""" .el .SS "\f(CWapi_listaccts()\fP" .IX Subsection "api_listaccts()" Used to list the accounts on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listaccts( $search, $searchtype ); .Ve .ie n .SS """api_createacct()""" .el .SS "\f(CWapi_createacct()\fP" .IX Subsection "api_createacct()" Create a new cPanel account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_createacct( $username, $domain, $password, $plan ); .Ve .ie n .SS """api_removeacct()""" .el .SS "\f(CWapi_removeacct()\fP" .IX Subsection "api_removeacct()" Terminate an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_removeacct( $user ); .Ve .ie n .SS """api_showversion()""" .el .SS "\f(CWapi_showversion()\fP" .IX Subsection "api_showversion()" Get the version of cPanel running on the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_showversion( ); .Ve .ie n .SS """api_version()""" .el .SS "\f(CWapi_version()\fP" .IX Subsection "api_version()" Get the version of cPanel running on the server (as as showversion) .PP Syntax: .PP .Vb 1 \& $pubapi\->api_version( ); .Ve .ie n .SS """api_applist()""" .el .SS "\f(CWapi_applist()\fP" .IX Subsection "api_applist()" List out the available xml-api calls. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_applist( ); .Ve .ie n .SS """api_generatessl()""" .el .SS "\f(CWapi_generatessl()\fP" .IX Subsection "api_generatessl()" Generate an ssl certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_generatessl( $host, $pass, $country, $state, $city, $co, $cod, $email, $xemail ); .Ve .ie n .SS """api_generatessl_noemail()""" .el .SS "\f(CWapi_generatessl_noemail()\fP" .IX Subsection "api_generatessl_noemail()" Generate an \s-1SSL\s0 certificate without an email. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_generatessl_noemail( $noemail=1 ); .Ve .ie n .SS """api_listcrts()""" .el .SS "\f(CWapi_listcrts()\fP" .IX Subsection "api_listcrts()" List out the certificates that exist on the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listcrts( ); .Ve .ie n .SS """api_setresellerlimits()""" .el .SS "\f(CWapi_setresellerlimits()\fP" .IX Subsection "api_setresellerlimits()" Set the limits for a single reseller account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setresellerlimits( ); .Ve .ie n .SS """api_setresellerpackagelimit()""" .el .SS "\f(CWapi_setresellerpackagelimit()\fP" .IX Subsection "api_setresellerpackagelimit()" Set which packages a reseller account can use. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setresellerpackagelimit( $user, $package, $allowerd, $number, $no_limit ); .Ve .ie n .SS """api_setresellermainip()""" .el .SS "\f(CWapi_setresellermainip()\fP" .IX Subsection "api_setresellermainip()" Set a reseller's main \s-1IP.\s0 .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setresellermainip( $user, $ip ); .Ve .ie n .SS """api_setresellerips()""" .el .SS "\f(CWapi_setresellerips()\fP" .IX Subsection "api_setresellerips()" Set the \s-1IP\s0 that a reseller has available to it. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setresellerips( $user, $delegate, $ips ); .Ve .ie n .SS """api_setresellernameservers()""" .el .SS "\f(CWapi_setresellernameservers()\fP" .IX Subsection "api_setresellernameservers()" Set the nameservers that a reseller uses by default. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setresellernameservers( $user, $nameservers ); .Ve .ie n .SS """api_suspendreseller()""" .el .SS "\f(CWapi_suspendreseller()\fP" .IX Subsection "api_suspendreseller()" Suspend a reseller and all of their accounts. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_suspendreseller( $user, $reason, $disallow ); .Ve .ie n .SS """api_unsuspendreseller()""" .el .SS "\f(CWapi_unsuspendreseller()\fP" .IX Subsection "api_unsuspendreseller()" Unsuspend a reseller and all of their accounts. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_unsuspendreseller( $user ); .Ve .ie n .SS """api_addzonerecord()""" .el .SS "\f(CWapi_addzonerecord()\fP" .IX Subsection "api_addzonerecord()" Add a record to a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_addzonerecord( @args ); .Ve .ie n .SS """api_editzonerecord()""" .el .SS "\f(CWapi_editzonerecord()\fP" .IX Subsection "api_editzonerecord()" Edit a zone record. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_editzonerecord(@args ); .Ve .ie n .SS """api_removezonerecord()""" .el .SS "\f(CWapi_removezonerecord()\fP" .IX Subsection "api_removezonerecord()" Remove a line from a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_removezonerecord( $domain, $Line ); .Ve .ie n .SS """api_getzonerecord()""" .el .SS "\f(CWapi_getzonerecord()\fP" .IX Subsection "api_getzonerecord()" Get a record from a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_getzonerecord( $domain, $Line ); .Ve .ie n .SS """api_servicestatus()""" .el .SS "\f(CWapi_servicestatus()\fP" .IX Subsection "api_servicestatus()" Get the status of various services running on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_servicestatus( $service ); .Ve .ie n .SS """api_configureservice()""" .el .SS "\f(CWapi_configureservice()\fP" .IX Subsection "api_configureservice()" Enable/Disable various services. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_configureservice( $service, $enabled, $monitored ); .Ve .ie n .SS """api_acctcounts()""" .el .SS "\f(CWapi_acctcounts()\fP" .IX Subsection "api_acctcounts()" Get the number of accounts on a system/that belong to a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_acctcounts( $user ); .Ve .ie n .SS """api_domainuserdata()""" .el .SS "\f(CWapi_domainuserdata()\fP" .IX Subsection "api_domainuserdata()" Get the information about a specific domain's virtualhost. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_domainuserdata( $domain ); .Ve .ie n .SS """api_editquota()""" .el .SS "\f(CWapi_editquota()\fP" .IX Subsection "api_editquota()" Edit a user's quota. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_editquota( $user, $quota ); .Ve .ie n .SS """api_nvget()""" .el .SS "\f(CWapi_nvget()\fP" .IX Subsection "api_nvget()" Get non-volatile data. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_nvget( $key ); .Ve .ie n .SS """api_nvset()""" .el .SS "\f(CWapi_nvset()\fP" .IX Subsection "api_nvset()" Set non-volatile data. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_nvset( $key, $value ); .Ve .ie n .SS """api_myprivs()""" .el .SS "\f(CWapi_myprivs()\fP" .IX Subsection "api_myprivs()" See what privileges are available to your user. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_myprivs( ); .Ve .ie n .SS """api_listzones()""" .el .SS "\f(CWapi_listzones()\fP" .IX Subsection "api_listzones()" List all the zones available to a user. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listzones( ); .Ve .ie n .SS """api_sethostname()""" .el .SS "\f(CWapi_sethostname()\fP" .IX Subsection "api_sethostname()" Set the hostname of a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_sethostname( $hostname ); .Ve .ie n .SS """api_setresolvers()""" .el .SS "\f(CWapi_setresolvers()\fP" .IX Subsection "api_setresolvers()" Set the resolvers a system uses. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setresolvers( $nameserver1, $nameserver2, $nameserver3 ); .Ve .ie n .SS """api_addip()""" .el .SS "\f(CWapi_addip()\fP" .IX Subsection "api_addip()" Add a new \s-1IP\s0 to a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_addip( $ip, $netmask ); .Ve .ie n .SS """api_delip()""" .el .SS "\f(CWapi_delip()\fP" .IX Subsection "api_delip()" Remove an \s-1IP\s0 from a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_delip( $ip, $ethernetdev, $skipifshutdown ); .Ve .ie n .SS """api_listips()""" .el .SS "\f(CWapi_listips()\fP" .IX Subsection "api_listips()" List the IPs on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listips( ); .Ve .ie n .SS """api_dumpzone()""" .el .SS "\f(CWapi_dumpzone()\fP" .IX Subsection "api_dumpzone()" Get the contents of a zone file. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_dumpzone( $domain ); .Ve .ie n .SS """api_listpkgs()""" .el .SS "\f(CWapi_listpkgs()\fP" .IX Subsection "api_listpkgs()" List the packages available to your user. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listpkgs( ); .Ve .ie n .SS """api_limitbw()""" .el .SS "\f(CWapi_limitbw()\fP" .IX Subsection "api_limitbw()" Limit the amount of bandwidth available to an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_limitbw( $user, $bwlimit ); .Ve .ie n .SS """api_showbw()""" .el .SS "\f(CWapi_showbw()\fP" .IX Subsection "api_showbw()" Show the amount of \s-1BW\s0 used by an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_showbw( $month, $year, $showres, $search, $searchtype ); .Ve .ie n .SS """api_killdns()""" .el .SS "\f(CWapi_killdns()\fP" .IX Subsection "api_killdns()" Remove a \s-1DNS\s0 zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_killdns( $domain ); .Ve .ie n .SS """api_adddns()""" .el .SS "\f(CWapi_adddns()\fP" .IX Subsection "api_adddns()" Add a dns zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_adddns( $domain, $ip, $trueowner ); .Ve .ie n .SS """api_changepackage()""" .el .SS "\f(CWapi_changepackage()\fP" .IX Subsection "api_changepackage()" Change an Account's Package. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_changepackage( $user, $pkg ); .Ve .ie n .SS """api_modifyacct()""" .el .SS "\f(CWapi_modifyacct()\fP" .IX Subsection "api_modifyacct()" Modify an Account's limits. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_modifyacct( $user, $domain, $HASCGI, $CPTHEME, $LANG, $MAXPOP, $MAXFTP, $MAXLST, $MAXSUB, $MAXPARK, $MAXADDON, $MAXSQL, $shell ); .Ve .ie n .SS """api_suspendacct()""" .el .SS "\f(CWapi_suspendacct()\fP" .IX Subsection "api_suspendacct()" Suspend an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_suspendacct( $user, $reason ); .Ve .ie n .SS """api_unsuspendacct()""" .el .SS "\f(CWapi_unsuspendacct()\fP" .IX Subsection "api_unsuspendacct()" Unsuspend an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_unsuspendacct( $user ); .Ve .ie n .SS """api_listsuspended()""" .el .SS "\f(CWapi_listsuspended()\fP" .IX Subsection "api_listsuspended()" List the suspended accounts on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listsuspended( ); .Ve .ie n .SS """api_addpkg()""" .el .SS "\f(CWapi_addpkg()\fP" .IX Subsection "api_addpkg()" Add a new package. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_addpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); .Ve .ie n .SS """api_killpkg()""" .el .SS "\f(CWapi_killpkg()\fP" .IX Subsection "api_killpkg()" Remove a package. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_killpkg( $pkg ); .Ve .ie n .SS """api_editpkg()""" .el .SS "\f(CWapi_editpkg()\fP" .IX Subsection "api_editpkg()" Edit a package. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_editpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); .Ve .ie n .SS """api_setacls()""" .el .SS "\f(CWapi_setacls()\fP" .IX Subsection "api_setacls()" Change features available to a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setacls( $reseller, $acllist ); .Ve .ie n .SS """api_terminatereseller()""" .el .SS "\f(CWapi_terminatereseller()\fP" .IX Subsection "api_terminatereseller()" Remove a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_terminatereseller( $reseller, $verify ); .Ve .ie n .SS """api_resellerstats()""" .el .SS "\f(CWapi_resellerstats()\fP" .IX Subsection "api_resellerstats()" Get statistics on a specific reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_resellerstats( $reseller ); .Ve .ie n .SS """api_setupreseller()""" .el .SS "\f(CWapi_setupreseller()\fP" .IX Subsection "api_setupreseller()" Make a cPanel account a Reseller account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setupreseller( $user, $makeowner ); .Ve .ie n .SS """api_lookupnsip()""" .el .SS "\f(CWapi_lookupnsip()\fP" .IX Subsection "api_lookupnsip()" Get the \s-1IP\s0 for a nameserver. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_lookupnsip( $nameserver ); .Ve .ie n .SS """api_listresellers()""" .el .SS "\f(CWapi_listresellers()\fP" .IX Subsection "api_listresellers()" List all the resellers on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listresellers( ); .Ve .ie n .SS """api_listacls()""" .el .SS "\f(CWapi_listacls()\fP" .IX Subsection "api_listacls()" List all of the \s-1ACL\s0 lists available. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_listacls( ); .Ve .ie n .SS """api_saveacllist()""" .el .SS "\f(CWapi_saveacllist()\fP" .IX Subsection "api_saveacllist()" Save a new \s-1ACL\s0 list. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_saveacllist( $acllist ); .Ve .ie n .SS """api_unsetupreseller()""" .el .SS "\f(CWapi_unsetupreseller()\fP" .IX Subsection "api_unsetupreseller()" Remove reseller permissions from an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_unsetupreseller( $user ); .Ve .ie n .SS """api_gethostname()""" .el .SS "\f(CWapi_gethostname()\fP" .IX Subsection "api_gethostname()" Get the hostname of the server currently being queried. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_gethostname( ); .Ve .ie n .SS """api_fetchsslinfo()""" .el .SS "\f(CWapi_fetchsslinfo()\fP" .IX Subsection "api_fetchsslinfo()" Get information on a specific \s-1SSL\s0 certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_fetchsslinfo( $domain, $crtdata ); .Ve .ie n .SS """api_installssl()""" .el .SS "\f(CWapi_installssl()\fP" .IX Subsection "api_installssl()" Install a new \s-1SSL\s0 certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_installssl( $domain, $user, $cert, $key, $cab, $ip ); .Ve .ie n .SS """api_passwd()""" .el .SS "\f(CWapi_passwd()\fP" .IX Subsection "api_passwd()" Change an account's password. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_passwd( $user, $pass ); .Ve .ie n .SS """api_getlanglist()""" .el .SS "\f(CWapi_getlanglist()\fP" .IX Subsection "api_getlanglist()" Get a list of languages available on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_getlanglist( ); .Ve .ie n .SS """api_reboot()""" .el .SS "\f(CWapi_reboot()\fP" .IX Subsection "api_reboot()" Reboot the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_reboot( $force ); .Ve .ie n .SS """api_accountsummary_user()""" .el .SS "\f(CWapi_accountsummary_user()\fP" .IX Subsection "api_accountsummary_user()" Get a summary of an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_accountsummary_user( $user ); .Ve .ie n .SS """api_accountsummary_domain()""" .el .SS "\f(CWapi_accountsummary_domain()\fP" .IX Subsection "api_accountsummary_domain()" Get the summary of an account by specifying the domain. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_accountsummary_domain( $domain ); .Ve .ie n .SS """api_loadavg()""" .el .SS "\f(CWapi_loadavg()\fP" .IX Subsection "api_loadavg()" Get the loadavg on the system. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_loadavg( ); .Ve .ie n .SS """api_restartservice()""" .el .SS "\f(CWapi_restartservice()\fP" .IX Subsection "api_restartservice()" Restart a service. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_restartservice( $service ); .Ve .ie n .SS """api_setsiteip_user()""" .el .SS "\f(CWapi_setsiteip_user()\fP" .IX Subsection "api_setsiteip_user()" Set the \s-1IP\s0 for a specific user. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setsiteip_user( $user, $ip ); .Ve .ie n .SS """api_setsiteip_domain()""" .el .SS "\f(CWapi_setsiteip_domain()\fP" .IX Subsection "api_setsiteip_domain()" Set the \s-1IP\s0 for a specific domain. .PP Syntax: .PP .Vb 1 \& $pubapi\->api_setsiteip_domain( $domain, $ip ); .Ve .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[]�)$B B ! man3/cPanel::PublicAPI::Utils.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::Utils 3" .TH cPanel::PublicAPI::Utils 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::Utils \- Provides some internally used utility functions for cPanel::PublicAPI, should never be used externally. .SH "Subroutines" .IX Header "Subroutines" .SS "\fBremove_trailing_newline()\fP" .IX Subsection "remove_trailing_newline()" Removes the training newline from the provided string .SS "get_string_with_collapsed_trailing_eols" .IX Subsection "get_string_with_collapsed_trailing_eols" Takes an array or array of arrays and puts them into a newline-seperated string. .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[�M��R �R ( man3/cPanel::PublicAPI::WHM::JSONAPI.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM::JSONAPI 3" .TH cPanel::PublicAPI::WHM::JSONAPI 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM::API \- Legacy interface for querying the xml\-api. .PP NOTE: This module is provided for legacy purposes, cPanel::PublicAPI should be used instead .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides legacy compatibility support between cPanel::PublicAPI and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). .PP Every method contained within this object can be queried using \fBcPanel::publicAPI::whm_api()\fR instead. .PP For more information on the calls within the methods contained here and what the parameter names mean, please read the documentation at: <http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi> .SH "functions" .IX Header "functions" .ie n .SS """jsonapi_listaccts()""" .el .SS "\f(CWjsonapi_listaccts()\fP" .IX Subsection "jsonapi_listaccts()" Used to list the accounts on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listaccts( $search, $searchtype ); .Ve .ie n .SS """jsonapi_createacct()""" .el .SS "\f(CWjsonapi_createacct()\fP" .IX Subsection "jsonapi_createacct()" Create a new cPanel account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_createacct( $username, $domain, $password, $plan ); .Ve .ie n .SS """jsonapi_removeacct()""" .el .SS "\f(CWjsonapi_removeacct()\fP" .IX Subsection "jsonapi_removeacct()" Terminate an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_removeacct( $user ); .Ve .ie n .SS """jsonapi_showversion()""" .el .SS "\f(CWjsonapi_showversion()\fP" .IX Subsection "jsonapi_showversion()" Get the version of cPanel running on the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_showversion( ); .Ve .ie n .SS """jsonapi_version()""" .el .SS "\f(CWjsonapi_version()\fP" .IX Subsection "jsonapi_version()" Get the version of cPanel running on the server (as as showversion) .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_version( ); .Ve .ie n .SS """jsonapi_applist()""" .el .SS "\f(CWjsonapi_applist()\fP" .IX Subsection "jsonapi_applist()" List out the available xml-api calls. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_applist( ); .Ve .ie n .SS """jsonapi_generatessl()""" .el .SS "\f(CWjsonapi_generatessl()\fP" .IX Subsection "jsonapi_generatessl()" Generate an ssl certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_generatessl( $host, $pass, $country, $state, $city, $co, $cod, $email, $xemail ); .Ve .ie n .SS """jsonapi_generatessl_noemail()""" .el .SS "\f(CWjsonapi_generatessl_noemail()\fP" .IX Subsection "jsonapi_generatessl_noemail()" Generate an \s-1SSL\s0 certificate without an email. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_generatessl_noemail( $noemail=1 ); .Ve .ie n .SS """jsonapi_listcrts()""" .el .SS "\f(CWjsonapi_listcrts()\fP" .IX Subsection "jsonapi_listcrts()" List out the certificates that exist on the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listcrts( ); .Ve .ie n .SS """jsonapi_setresellerlimits()""" .el .SS "\f(CWjsonapi_setresellerlimits()\fP" .IX Subsection "jsonapi_setresellerlimits()" Set the limits for a single reseller account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setresellerlimits( ); .Ve .ie n .SS """jsonapi_setresellerpackagelimit()""" .el .SS "\f(CWjsonapi_setresellerpackagelimit()\fP" .IX Subsection "jsonapi_setresellerpackagelimit()" Set which packages a reseller account can use. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setresellerpackagelimit( $user, $package, $allowerd, $number, $no_limit ); .Ve .ie n .SS """jsonapi_setresellermainip()""" .el .SS "\f(CWjsonapi_setresellermainip()\fP" .IX Subsection "jsonapi_setresellermainip()" Set a reseller's main \s-1IP.\s0 .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setresellermainip( $user, $ip ); .Ve .ie n .SS """jsonapi_setresellerips()""" .el .SS "\f(CWjsonapi_setresellerips()\fP" .IX Subsection "jsonapi_setresellerips()" Set the \s-1IP\s0 that a reseller has available to it. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setresellerips( $user, $delegate, $ips ); .Ve .ie n .SS """jsonapi_setresellernameservers()""" .el .SS "\f(CWjsonapi_setresellernameservers()\fP" .IX Subsection "jsonapi_setresellernameservers()" Set the nameservers that a reseller uses by default. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setresellernameservers( $user, $nameservers ); .Ve .ie n .SS """jsonapi_suspendreseller()""" .el .SS "\f(CWjsonapi_suspendreseller()\fP" .IX Subsection "jsonapi_suspendreseller()" Suspend a reseller and all of their accounts. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_suspendreseller( $user, $reason, $disallow ); .Ve .ie n .SS """jsonapi_unsuspendreseller()""" .el .SS "\f(CWjsonapi_unsuspendreseller()\fP" .IX Subsection "jsonapi_unsuspendreseller()" Unsuspend a reseller and all of their accounts. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_unsuspendreseller( $user ); .Ve .ie n .SS """jsonapi_addzonerecord()""" .el .SS "\f(CWjsonapi_addzonerecord()\fP" .IX Subsection "jsonapi_addzonerecord()" Add a record to a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_addzonerecord( @args ); .Ve .ie n .SS """jsonapi_editzonerecord()""" .el .SS "\f(CWjsonapi_editzonerecord()\fP" .IX Subsection "jsonapi_editzonerecord()" Edit a zone record. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_editzonerecord(@args ); .Ve .ie n .SS """jsonapi_removezonerecord()""" .el .SS "\f(CWjsonapi_removezonerecord()\fP" .IX Subsection "jsonapi_removezonerecord()" Remove a line from a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_removezonerecord( $domain, $Line ); .Ve .ie n .SS """jsonapi_getzonerecord()""" .el .SS "\f(CWjsonapi_getzonerecord()\fP" .IX Subsection "jsonapi_getzonerecord()" Get a record from a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_getzonerecord( $domain, $Line ); .Ve .ie n .SS """jsonapi_servicestatus()""" .el .SS "\f(CWjsonapi_servicestatus()\fP" .IX Subsection "jsonapi_servicestatus()" Get the status of various services running on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_servicestatus( $service ); .Ve .ie n .SS """jsonapi_configureservice()""" .el .SS "\f(CWjsonapi_configureservice()\fP" .IX Subsection "jsonapi_configureservice()" Enable/Disable various services. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_configureservice( $service, $enabled, $monitored ); .Ve .ie n .SS """jsonapi_acctcounts()""" .el .SS "\f(CWjsonapi_acctcounts()\fP" .IX Subsection "jsonapi_acctcounts()" Get the number of accounts on a system/that belong to a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_acctcounts( $user ); .Ve .ie n .SS """jsonapi_domainuserdata()""" .el .SS "\f(CWjsonapi_domainuserdata()\fP" .IX Subsection "jsonapi_domainuserdata()" Get the information about a specific domain's virtualhost. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_domainuserdata( $domain ); .Ve .ie n .SS """jsonapi_editquota()""" .el .SS "\f(CWjsonapi_editquota()\fP" .IX Subsection "jsonapi_editquota()" Edit a user's quota. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_editquota( $user, $quota ); .Ve .ie n .SS """jsonapi_nvget()""" .el .SS "\f(CWjsonapi_nvget()\fP" .IX Subsection "jsonapi_nvget()" Get non-volatile data. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_nvget( $key ); .Ve .ie n .SS """jsonapi_nvset()""" .el .SS "\f(CWjsonapi_nvset()\fP" .IX Subsection "jsonapi_nvset()" Set non-volatile data. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_nvset( $key, $value ); .Ve .ie n .SS """jsonapi_myprivs()""" .el .SS "\f(CWjsonapi_myprivs()\fP" .IX Subsection "jsonapi_myprivs()" See what privileges are available to your user. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_myprivs( ); .Ve .ie n .SS """jsonapi_listzones()""" .el .SS "\f(CWjsonapi_listzones()\fP" .IX Subsection "jsonapi_listzones()" List all the zones available to a user. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listzones( ); .Ve .ie n .SS """jsonapi_sethostname()""" .el .SS "\f(CWjsonapi_sethostname()\fP" .IX Subsection "jsonapi_sethostname()" Set the hostname of a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_sethostname( $hostname ); .Ve .ie n .SS """jsonapi_setresolvers()""" .el .SS "\f(CWjsonapi_setresolvers()\fP" .IX Subsection "jsonapi_setresolvers()" Set the resolvers a system uses. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setresolvers( $nameserver1, $nameserver2, $nameserver3 ); .Ve .ie n .SS """jsonapi_addip()""" .el .SS "\f(CWjsonapi_addip()\fP" .IX Subsection "jsonapi_addip()" Add a new \s-1IP\s0 to a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_addip( $ip, $netmask ); .Ve .ie n .SS """jsonapi_delip()""" .el .SS "\f(CWjsonapi_delip()\fP" .IX Subsection "jsonapi_delip()" Remove an \s-1IP\s0 from a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_delip( $ip, $ethernetdev, $skipifshutdown ); .Ve .ie n .SS """jsonapi_listips()""" .el .SS "\f(CWjsonapi_listips()\fP" .IX Subsection "jsonapi_listips()" List the IPs on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listips( ); .Ve .ie n .SS """jsonapi_dumpzone()""" .el .SS "\f(CWjsonapi_dumpzone()\fP" .IX Subsection "jsonapi_dumpzone()" Get the contents of a zone file. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_dumpzone( $domain ); .Ve .ie n .SS """jsonapi_listpkgs()""" .el .SS "\f(CWjsonapi_listpkgs()\fP" .IX Subsection "jsonapi_listpkgs()" List the packages available to your user. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listpkgs( ); .Ve .ie n .SS """jsonapi_limitbw()""" .el .SS "\f(CWjsonapi_limitbw()\fP" .IX Subsection "jsonapi_limitbw()" Limit the amount of bandwidth available to an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_limitbw( $user, $bwlimit ); .Ve .ie n .SS """jsonapi_showbw()""" .el .SS "\f(CWjsonapi_showbw()\fP" .IX Subsection "jsonapi_showbw()" Show the amount of \s-1BW\s0 used by an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_showbw( $month, $year, $showres, $search, $searchtype ); .Ve .ie n .SS """jsonapi_killdns()""" .el .SS "\f(CWjsonapi_killdns()\fP" .IX Subsection "jsonapi_killdns()" Remove a \s-1DNS\s0 zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_killdns( $domain ); .Ve .ie n .SS """jsonapi_adddns()""" .el .SS "\f(CWjsonapi_adddns()\fP" .IX Subsection "jsonapi_adddns()" Add a dns zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_adddns( $domain, $ip, $trueowner ); .Ve .ie n .SS """jsonapi_changepackage()""" .el .SS "\f(CWjsonapi_changepackage()\fP" .IX Subsection "jsonapi_changepackage()" Change an Account's Package. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_changepackage( $user, $pkg ); .Ve .ie n .SS """jsonapi_modifyacct()""" .el .SS "\f(CWjsonapi_modifyacct()\fP" .IX Subsection "jsonapi_modifyacct()" Modify an Account's limits. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_modifyacct( $user, $domain, $HASCGI, $CPTHEME, $LANG, $MAXPOP, $MAXFTP, $MAXLST, $MAXSUB, $MAXPARK, $MAXADDON, $MAXSQL, $shell ); .Ve .ie n .SS """jsonapi_suspendacct()""" .el .SS "\f(CWjsonapi_suspendacct()\fP" .IX Subsection "jsonapi_suspendacct()" Suspend an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_suspendacct( $user, $reason ); .Ve .ie n .SS """jsonapi_unsuspendacct()""" .el .SS "\f(CWjsonapi_unsuspendacct()\fP" .IX Subsection "jsonapi_unsuspendacct()" Unsuspend an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_unsuspendacct( $user ); .Ve .ie n .SS """jsonapi_listsuspended()""" .el .SS "\f(CWjsonapi_listsuspended()\fP" .IX Subsection "jsonapi_listsuspended()" List the suspended accounts on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listsuspended( ); .Ve .ie n .SS """jsonapi_addpkg()""" .el .SS "\f(CWjsonapi_addpkg()\fP" .IX Subsection "jsonapi_addpkg()" Add a new package. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_addpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); .Ve .ie n .SS """jsonapi_killpkg()""" .el .SS "\f(CWjsonapi_killpkg()\fP" .IX Subsection "jsonapi_killpkg()" Remove a package. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_killpkg( $pkg ); .Ve .ie n .SS """jsonapi_editpkg()""" .el .SS "\f(CWjsonapi_editpkg()\fP" .IX Subsection "jsonapi_editpkg()" Edit a package. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_editpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); .Ve .ie n .SS """jsonapi_setacls()""" .el .SS "\f(CWjsonapi_setacls()\fP" .IX Subsection "jsonapi_setacls()" Change features available to a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setacls( $reseller, $acllist ); .Ve .ie n .SS """jsonapi_terminatereseller()""" .el .SS "\f(CWjsonapi_terminatereseller()\fP" .IX Subsection "jsonapi_terminatereseller()" Remove a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_terminatereseller( $reseller, $verify ); .Ve .ie n .SS """jsonapi_resellerstats()""" .el .SS "\f(CWjsonapi_resellerstats()\fP" .IX Subsection "jsonapi_resellerstats()" Get statistics on a specific reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_resellerstats( $reseller ); .Ve .ie n .SS """jsonapi_setupreseller()""" .el .SS "\f(CWjsonapi_setupreseller()\fP" .IX Subsection "jsonapi_setupreseller()" Make a cPanel account a Reseller account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setupreseller( $user, $makeowner ); .Ve .ie n .SS """jsonapi_lookupnsip()""" .el .SS "\f(CWjsonapi_lookupnsip()\fP" .IX Subsection "jsonapi_lookupnsip()" Get the \s-1IP\s0 for a nameserver. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_lookupnsip( $nameserver ); .Ve .ie n .SS """jsonapi_listresellers()""" .el .SS "\f(CWjsonapi_listresellers()\fP" .IX Subsection "jsonapi_listresellers()" List all the resellers on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listresellers( ); .Ve .ie n .SS """jsonapi_listacls()""" .el .SS "\f(CWjsonapi_listacls()\fP" .IX Subsection "jsonapi_listacls()" List all of the \s-1ACL\s0 lists available. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_listacls( ); .Ve .ie n .SS """jsonapi_saveacllist()""" .el .SS "\f(CWjsonapi_saveacllist()\fP" .IX Subsection "jsonapi_saveacllist()" Save a new \s-1ACL\s0 list. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_saveacllist( $acllist ); .Ve .ie n .SS """jsonapi_unsetupreseller()""" .el .SS "\f(CWjsonapi_unsetupreseller()\fP" .IX Subsection "jsonapi_unsetupreseller()" Remove reseller permissions from an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_unsetupreseller( $user ); .Ve .ie n .SS """jsonapi_gethostname()""" .el .SS "\f(CWjsonapi_gethostname()\fP" .IX Subsection "jsonapi_gethostname()" Get the hostname of the server currently being queried. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_gethostname( ); .Ve .ie n .SS """jsonapi_fetchsslinfo()""" .el .SS "\f(CWjsonapi_fetchsslinfo()\fP" .IX Subsection "jsonapi_fetchsslinfo()" Get information on a specific \s-1SSL\s0 certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_fetchsslinfo( $domain, $crtdata ); .Ve .ie n .SS """jsonapi_installssl()""" .el .SS "\f(CWjsonapi_installssl()\fP" .IX Subsection "jsonapi_installssl()" Install a new \s-1SSL\s0 certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_installssl( $domain, $user, $cert, $key, $cab, $ip ); .Ve .ie n .SS """jsonapi_passwd()""" .el .SS "\f(CWjsonapi_passwd()\fP" .IX Subsection "jsonapi_passwd()" Change an account's password. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_passwd( $user, $pass ); .Ve .ie n .SS """jsonapi_getlanglist()""" .el .SS "\f(CWjsonapi_getlanglist()\fP" .IX Subsection "jsonapi_getlanglist()" Get a list of languages available on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_getlanglist( ); .Ve .ie n .SS """jsonapi_reboot()""" .el .SS "\f(CWjsonapi_reboot()\fP" .IX Subsection "jsonapi_reboot()" Reboot the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_reboot( $force ); .Ve .ie n .SS """jsonapi_accountsummary_user()""" .el .SS "\f(CWjsonapi_accountsummary_user()\fP" .IX Subsection "jsonapi_accountsummary_user()" Get a summary of an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_accountsummary_user( $user ); .Ve .ie n .SS """jsonapi_accountsummary_domain()""" .el .SS "\f(CWjsonapi_accountsummary_domain()\fP" .IX Subsection "jsonapi_accountsummary_domain()" Get the summary of an account by specifying the domain. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_accountsummary_domain( $domain ); .Ve .ie n .SS """jsonapi_loadavg()""" .el .SS "\f(CWjsonapi_loadavg()\fP" .IX Subsection "jsonapi_loadavg()" Get the loadavg on the system. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_loadavg( ); .Ve .ie n .SS """jsonapi_restartservice()""" .el .SS "\f(CWjsonapi_restartservice()\fP" .IX Subsection "jsonapi_restartservice()" Restart a service. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_restartservice( $service ); .Ve .ie n .SS """jsonapi_setsiteip_user()""" .el .SS "\f(CWjsonapi_setsiteip_user()\fP" .IX Subsection "jsonapi_setsiteip_user()" Set the \s-1IP\s0 for a specific user. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setsiteip_user( $user, $ip ); .Ve .ie n .SS """jsonapi_setsiteip_domain()""" .el .SS "\f(CWjsonapi_setsiteip_domain()\fP" .IX Subsection "jsonapi_setsiteip_domain()" Set the \s-1IP\s0 for a specific domain. .PP Syntax: .PP .Vb 1 \& $pubapi\->jsonapi_setsiteip_domain( $domain, $ip ); .Ve .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[�"{G�Q �Q ' man3/cPanel::PublicAPI::WHM::XMLAPI.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM::XMLAPI 3" .TH cPanel::PublicAPI::WHM::XMLAPI 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM::API \- Legacy interface for querying the xml\-api. .PP NOTE: This module is provided for legacy purposes, cPanel::PublicAPI should be used instead .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides legacy compatibility support between cPanel::PublicAPI and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). .PP Every method contained within this object can be queried using \fBcPanel::publicAPI::whm_api()\fR instead. .PP For more information on the calls within the methods contained here and what the parameter names mean, please read the documentation at: <http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi> .SH "functions" .IX Header "functions" .ie n .SS """xmlapi_listaccts()""" .el .SS "\f(CWxmlapi_listaccts()\fP" .IX Subsection "xmlapi_listaccts()" Used to list the accounts on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listaccts( $search, $searchtype ); .Ve .ie n .SS """xmlapi_createacct()""" .el .SS "\f(CWxmlapi_createacct()\fP" .IX Subsection "xmlapi_createacct()" Create a new cPanel account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_createacct( $username, $domain, $password, $plan ); .Ve .ie n .SS """xmlapi_removeacct()""" .el .SS "\f(CWxmlapi_removeacct()\fP" .IX Subsection "xmlapi_removeacct()" Terminate an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_removeacct( $user ); .Ve .ie n .SS """xmlapi_showversion()""" .el .SS "\f(CWxmlapi_showversion()\fP" .IX Subsection "xmlapi_showversion()" Get the version of cPanel running on the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_showversion( ); .Ve .ie n .SS """xmlapi_version()""" .el .SS "\f(CWxmlapi_version()\fP" .IX Subsection "xmlapi_version()" Get the version of cPanel running on the server (as as showversion) .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_version( ); .Ve .ie n .SS """xmlapi_applist()""" .el .SS "\f(CWxmlapi_applist()\fP" .IX Subsection "xmlapi_applist()" List out the available xml-api calls. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_applist( ); .Ve .ie n .SS """xmlapi_generatessl()""" .el .SS "\f(CWxmlapi_generatessl()\fP" .IX Subsection "xmlapi_generatessl()" Generate an ssl certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_generatessl( $host, $pass, $country, $state, $city, $co, $cod, $email, $xemail ); .Ve .ie n .SS """xmlapi_generatessl_noemail()""" .el .SS "\f(CWxmlapi_generatessl_noemail()\fP" .IX Subsection "xmlapi_generatessl_noemail()" Generate an \s-1SSL\s0 certificate without an email. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_generatessl_noemail( $noemail=1 ); .Ve .ie n .SS """xmlapi_listcrts()""" .el .SS "\f(CWxmlapi_listcrts()\fP" .IX Subsection "xmlapi_listcrts()" List out the certificates that exist on the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listcrts( ); .Ve .ie n .SS """xmlapi_setresellerlimits()""" .el .SS "\f(CWxmlapi_setresellerlimits()\fP" .IX Subsection "xmlapi_setresellerlimits()" Set the limits for a single reseller account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setresellerlimits( ); .Ve .ie n .SS """xmlapi_setresellerpackagelimit()""" .el .SS "\f(CWxmlapi_setresellerpackagelimit()\fP" .IX Subsection "xmlapi_setresellerpackagelimit()" Set which packages a reseller account can use. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setresellerpackagelimit( $user, $package, $allowerd, $number, $no_limit ); .Ve .ie n .SS """xmlapi_setresellermainip()""" .el .SS "\f(CWxmlapi_setresellermainip()\fP" .IX Subsection "xmlapi_setresellermainip()" Set a reseller's main \s-1IP.\s0 .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setresellermainip( $user, $ip ); .Ve .ie n .SS """xmlapi_setresellerips()""" .el .SS "\f(CWxmlapi_setresellerips()\fP" .IX Subsection "xmlapi_setresellerips()" Set the \s-1IP\s0 that a reseller has available to it. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setresellerips( $user, $delegate, $ips ); .Ve .ie n .SS """xmlapi_setresellernameservers()""" .el .SS "\f(CWxmlapi_setresellernameservers()\fP" .IX Subsection "xmlapi_setresellernameservers()" Set the nameservers that a reseller uses by default. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setresellernameservers( $user, $nameservers ); .Ve .ie n .SS """xmlapi_suspendreseller()""" .el .SS "\f(CWxmlapi_suspendreseller()\fP" .IX Subsection "xmlapi_suspendreseller()" Suspend a reseller and all of their accounts. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_suspendreseller( $user, $reason, $disallow ); .Ve .ie n .SS """xmlapi_unsuspendreseller()""" .el .SS "\f(CWxmlapi_unsuspendreseller()\fP" .IX Subsection "xmlapi_unsuspendreseller()" Unsuspend a reseller and all of their accounts. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_unsuspendreseller( $user ); .Ve .ie n .SS """xmlapi_addzonerecord()""" .el .SS "\f(CWxmlapi_addzonerecord()\fP" .IX Subsection "xmlapi_addzonerecord()" Add a record to a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_addzonerecord( @args ); .Ve .ie n .SS """xmlapi_editzonerecord()""" .el .SS "\f(CWxmlapi_editzonerecord()\fP" .IX Subsection "xmlapi_editzonerecord()" Edit a zone record. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_editzonerecord(@args ); .Ve .ie n .SS """xmlapi_removezonerecord()""" .el .SS "\f(CWxmlapi_removezonerecord()\fP" .IX Subsection "xmlapi_removezonerecord()" Remove a line from a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_removezonerecord( $domain, $Line ); .Ve .ie n .SS """xmlapi_getzonerecord()""" .el .SS "\f(CWxmlapi_getzonerecord()\fP" .IX Subsection "xmlapi_getzonerecord()" Get a record from a zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_getzonerecord( $domain, $Line ); .Ve .ie n .SS """xmlapi_servicestatus()""" .el .SS "\f(CWxmlapi_servicestatus()\fP" .IX Subsection "xmlapi_servicestatus()" Get the status of various services running on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_servicestatus( $service ); .Ve .ie n .SS """xmlapi_configureservice()""" .el .SS "\f(CWxmlapi_configureservice()\fP" .IX Subsection "xmlapi_configureservice()" Enable/Disable various services. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_configureservice( $service, $enabled, $monitored ); .Ve .ie n .SS """xmlapi_acctcounts()""" .el .SS "\f(CWxmlapi_acctcounts()\fP" .IX Subsection "xmlapi_acctcounts()" Get the number of accounts on a system/that belong to a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_acctcounts( $user ); .Ve .ie n .SS """xmlapi_domainuserdata()""" .el .SS "\f(CWxmlapi_domainuserdata()\fP" .IX Subsection "xmlapi_domainuserdata()" Get the information about a specific domain's virtualhost. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_domainuserdata( $domain ); .Ve .ie n .SS """xmlapi_editquota()""" .el .SS "\f(CWxmlapi_editquota()\fP" .IX Subsection "xmlapi_editquota()" Edit a user's quota. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_editquota( $user, $quota ); .Ve .ie n .SS """xmlapi_nvget()""" .el .SS "\f(CWxmlapi_nvget()\fP" .IX Subsection "xmlapi_nvget()" Get non-volatile data. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_nvget( $key ); .Ve .ie n .SS """xmlapi_nvset()""" .el .SS "\f(CWxmlapi_nvset()\fP" .IX Subsection "xmlapi_nvset()" Set non-volatile data. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_nvset( $key, $value ); .Ve .ie n .SS """xmlapi_myprivs()""" .el .SS "\f(CWxmlapi_myprivs()\fP" .IX Subsection "xmlapi_myprivs()" See what privileges are available to your user. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_myprivs( ); .Ve .ie n .SS """xmlapi_listzones()""" .el .SS "\f(CWxmlapi_listzones()\fP" .IX Subsection "xmlapi_listzones()" List all the zones available to a user. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listzones( ); .Ve .ie n .SS """xmlapi_sethostname()""" .el .SS "\f(CWxmlapi_sethostname()\fP" .IX Subsection "xmlapi_sethostname()" Set the hostname of a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_sethostname( $hostname ); .Ve .ie n .SS """xmlapi_setresolvers()""" .el .SS "\f(CWxmlapi_setresolvers()\fP" .IX Subsection "xmlapi_setresolvers()" Set the resolvers a system uses. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setresolvers( $nameserver1, $nameserver2, $nameserver3 ); .Ve .ie n .SS """xmlapi_addip()""" .el .SS "\f(CWxmlapi_addip()\fP" .IX Subsection "xmlapi_addip()" Add a new \s-1IP\s0 to a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_addip( $ip, $netmask ); .Ve .ie n .SS """xmlapi_delip()""" .el .SS "\f(CWxmlapi_delip()\fP" .IX Subsection "xmlapi_delip()" Remove an \s-1IP\s0 from a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_delip( $ip, $ethernetdev, $skipifshutdown ); .Ve .ie n .SS """xmlapi_listips()""" .el .SS "\f(CWxmlapi_listips()\fP" .IX Subsection "xmlapi_listips()" List the IPs on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listips( ); .Ve .ie n .SS """xmlapi_dumpzone()""" .el .SS "\f(CWxmlapi_dumpzone()\fP" .IX Subsection "xmlapi_dumpzone()" Get the contents of a zone file. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_dumpzone( $domain ); .Ve .ie n .SS """xmlapi_listpkgs()""" .el .SS "\f(CWxmlapi_listpkgs()\fP" .IX Subsection "xmlapi_listpkgs()" List the packages available to your user. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listpkgs( ); .Ve .ie n .SS """xmlapi_limitbw()""" .el .SS "\f(CWxmlapi_limitbw()\fP" .IX Subsection "xmlapi_limitbw()" Limit the amount of bandwidth available to an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_limitbw( $user, $bwlimit ); .Ve .ie n .SS """xmlapi_showbw()""" .el .SS "\f(CWxmlapi_showbw()\fP" .IX Subsection "xmlapi_showbw()" Show the amount of \s-1BW\s0 used by an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_showbw( $month, $year, $showres, $search, $searchtype ); .Ve .ie n .SS """xmlapi_killdns()""" .el .SS "\f(CWxmlapi_killdns()\fP" .IX Subsection "xmlapi_killdns()" Remove a \s-1DNS\s0 zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_killdns( $domain ); .Ve .ie n .SS """xmlapi_adddns()""" .el .SS "\f(CWxmlapi_adddns()\fP" .IX Subsection "xmlapi_adddns()" Add a dns zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_adddns( $domain, $ip, $trueowner ); .Ve .ie n .SS """xmlapi_changepackage()""" .el .SS "\f(CWxmlapi_changepackage()\fP" .IX Subsection "xmlapi_changepackage()" Change an Account's Package. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_changepackage( $user, $pkg ); .Ve .ie n .SS """xmlapi_modifyacct()""" .el .SS "\f(CWxmlapi_modifyacct()\fP" .IX Subsection "xmlapi_modifyacct()" Modify an Account's limits. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_modifyacct( $user, $domain, $HASCGI, $CPTHEME, $LANG, $MAXPOP, $MAXFTP, $MAXLST, $MAXSUB, $MAXPARK, $MAXADDON, $MAXSQL, $shell ); .Ve .ie n .SS """xmlapi_suspendacct()""" .el .SS "\f(CWxmlapi_suspendacct()\fP" .IX Subsection "xmlapi_suspendacct()" Suspend an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_suspendacct( $user, $reason ); .Ve .ie n .SS """xmlapi_unsuspendacct()""" .el .SS "\f(CWxmlapi_unsuspendacct()\fP" .IX Subsection "xmlapi_unsuspendacct()" Unsuspend an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_unsuspendacct( $user ); .Ve .ie n .SS """xmlapi_listsuspended()""" .el .SS "\f(CWxmlapi_listsuspended()\fP" .IX Subsection "xmlapi_listsuspended()" List the suspended accounts on a server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listsuspended( ); .Ve .ie n .SS """xmlapi_addpkg()""" .el .SS "\f(CWxmlapi_addpkg()\fP" .IX Subsection "xmlapi_addpkg()" Add a new package. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_addpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); .Ve .ie n .SS """xmlapi_killpkg()""" .el .SS "\f(CWxmlapi_killpkg()\fP" .IX Subsection "xmlapi_killpkg()" Remove a package. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_killpkg( $pkg ); .Ve .ie n .SS """xmlapi_editpkg()""" .el .SS "\f(CWxmlapi_editpkg()\fP" .IX Subsection "xmlapi_editpkg()" Edit a package. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_editpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); .Ve .ie n .SS """xmlapi_setacls()""" .el .SS "\f(CWxmlapi_setacls()\fP" .IX Subsection "xmlapi_setacls()" Change features available to a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setacls( $reseller, $acllist ); .Ve .ie n .SS """xmlapi_terminatereseller()""" .el .SS "\f(CWxmlapi_terminatereseller()\fP" .IX Subsection "xmlapi_terminatereseller()" Remove a reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_terminatereseller( $reseller, $verify ); .Ve .ie n .SS """xmlapi_resellerstats()""" .el .SS "\f(CWxmlapi_resellerstats()\fP" .IX Subsection "xmlapi_resellerstats()" Get statistics on a specific reseller. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_resellerstats( $reseller ); .Ve .ie n .SS """xmlapi_setupreseller()""" .el .SS "\f(CWxmlapi_setupreseller()\fP" .IX Subsection "xmlapi_setupreseller()" Make a cPanel account a Reseller account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setupreseller( $user, $makeowner ); .Ve .ie n .SS """xmlapi_lookupnsip()""" .el .SS "\f(CWxmlapi_lookupnsip()\fP" .IX Subsection "xmlapi_lookupnsip()" Get the \s-1IP\s0 for a nameserver. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_lookupnsip( $nameserver ); .Ve .ie n .SS """xmlapi_listresellers()""" .el .SS "\f(CWxmlapi_listresellers()\fP" .IX Subsection "xmlapi_listresellers()" List all the resellers on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listresellers( ); .Ve .ie n .SS """xmlapi_listacls()""" .el .SS "\f(CWxmlapi_listacls()\fP" .IX Subsection "xmlapi_listacls()" List all of the \s-1ACL\s0 lists available. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_listacls( ); .Ve .ie n .SS """xmlapi_saveacllist()""" .el .SS "\f(CWxmlapi_saveacllist()\fP" .IX Subsection "xmlapi_saveacllist()" Save a new \s-1ACL\s0 list. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_saveacllist( $acllist ); .Ve .ie n .SS """xmlapi_unsetupreseller()""" .el .SS "\f(CWxmlapi_unsetupreseller()\fP" .IX Subsection "xmlapi_unsetupreseller()" Remove reseller permissions from an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_unsetupreseller( $user ); .Ve .ie n .SS """xmlapi_gethostname()""" .el .SS "\f(CWxmlapi_gethostname()\fP" .IX Subsection "xmlapi_gethostname()" Get the hostname of the server currently being queried. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_gethostname( ); .Ve .ie n .SS """xmlapi_fetchsslinfo()""" .el .SS "\f(CWxmlapi_fetchsslinfo()\fP" .IX Subsection "xmlapi_fetchsslinfo()" Get information on a specific \s-1SSL\s0 certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_fetchsslinfo( $domain, $crtdata ); .Ve .ie n .SS """xmlapi_installssl()""" .el .SS "\f(CWxmlapi_installssl()\fP" .IX Subsection "xmlapi_installssl()" Install a new \s-1SSL\s0 certificate. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_installssl( $domain, $user, $cert, $key, $cab, $ip ); .Ve .ie n .SS """xmlapi_passwd()""" .el .SS "\f(CWxmlapi_passwd()\fP" .IX Subsection "xmlapi_passwd()" Change an account's password. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_passwd( $user, $pass ); .Ve .ie n .SS """xmlapi_getlanglist()""" .el .SS "\f(CWxmlapi_getlanglist()\fP" .IX Subsection "xmlapi_getlanglist()" Get a list of languages available on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_getlanglist( ); .Ve .ie n .SS """xmlapi_reboot()""" .el .SS "\f(CWxmlapi_reboot()\fP" .IX Subsection "xmlapi_reboot()" Reboot the server. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_reboot( $force ); .Ve .ie n .SS """xmlapi_accountsummary_user()""" .el .SS "\f(CWxmlapi_accountsummary_user()\fP" .IX Subsection "xmlapi_accountsummary_user()" Get a summary of an account. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_accountsummary_user( $user ); .Ve .ie n .SS """xmlapi_accountsummary_domain()""" .el .SS "\f(CWxmlapi_accountsummary_domain()\fP" .IX Subsection "xmlapi_accountsummary_domain()" Get the summary of an account by specifying the domain. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_accountsummary_domain( $domain ); .Ve .ie n .SS """xmlapi_loadavg()""" .el .SS "\f(CWxmlapi_loadavg()\fP" .IX Subsection "xmlapi_loadavg()" Get the loadavg on the system. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_loadavg( ); .Ve .ie n .SS """xmlapi_restartservice()""" .el .SS "\f(CWxmlapi_restartservice()\fP" .IX Subsection "xmlapi_restartservice()" Restart a service. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_restartservice( $service ); .Ve .ie n .SS """xmlapi_setsiteip_user()""" .el .SS "\f(CWxmlapi_setsiteip_user()\fP" .IX Subsection "xmlapi_setsiteip_user()" Set the \s-1IP\s0 for a specific user. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setsiteip_user( $user, $ip ); .Ve .ie n .SS """xmlapi_setsiteip_domain()""" .el .SS "\f(CWxmlapi_setsiteip_domain()\fP" .IX Subsection "xmlapi_setsiteip_domain()" Set the \s-1IP\s0 for a specific domain. .PP Syntax: .PP .Vb 1 \& $pubapi\->xmlapi_setsiteip_domain( $domain, $ip ); .Ve .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[��&��] �] man3/cPanel::PublicAPI.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI 3" .TH cPanel::PublicAPI 3 "2019-11-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI \- A perl interface for interacting with cPanel .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use cPanel::PublicAPI; \& \& # Auto detect authentication information \& my $cp = cPanel::PublicAPI\->new(); \& # or specify a user/password \& my $cp = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqsomeuser\*(Aq, \*(Aqpass\*(Aq => \*(Aqsomepass\*(Aq ); \& # or specify an accesshash \& my $cp = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqsomeuser\*(Aq, \*(Aqaccesshash\*(Aq => $accesshash ); \& # or specify an API token \& my $cp = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqsomeuser\*(Aq, \*(Aqapi_token\*(Aq => $api_token ); \& \& # Perform an xml\-api query \& $cp\->whm_api(\*(Aqlistaccts\*(Aq); \& # Pass parameters to the xml\-api \& $cp\->whm_api(\*(Aqcreateacct\*(Aq, {\*(Aqusername\*(Aq => \*(Aqsomeuser\*(Aq, \*(Aqpassword\*(Aq => \*(Aqs0m3P4$$w()Rd\*(Aq } ); \& # Return JSON from xml\-api (rather than a hash reference) \& $cp\->whm_api(\*(Aqversion\*(Aq, undef, \*(Aqjson\*(Aq); \& \& # Perform an API2 query \& $cp\->cpanel_api2_request(\*(Aqwhostmgr\*(Aq, \& { \& \*(Aqmodule\*(Aq => \*(AqEmail\*(Aq, \& \*(Aqfunc\*(Aq => \*(Aqlistpopswithdisk\*(Aq, \& \*(Aquser\*(Aq => \*(Aqsomeuser\*(Aq, \& } \& ); \& # Perform an API2 query when authenticated as a user \& $cp\->cpanel_api2_request(\*(Aqcpanel\*(Aq, \& { \& \*(Aqmodule\*(Aq => \*(AqEmail\*(Aq, \& \*(Aqfunc\*(Aq => \*(Aqlistpopswithdisk\*(Aq, \& } \& ); \& # Pass parameters to an API2 call \& $cp\->cpanel_api2_request(\*(Aqcpanel\*(Aq \& { \& \*(Aqmodule\*(Aq => \*(AqEmail\*(Aq, \& \*(Aqfunc\*(Aq => \*(Aqaddpop\*(Aq, \& }, \& { \& \*(Aqdomain\*(Aq => \*(Aqdomain.com\*(Aq, \& \*(Aqemail\*(Aq => \*(Aqusername\*(Aq, \& \*(Aqpassword\*(Aq => \*(AqSojmASDM(#(Jinasifodanosd\*(Aq, \& \*(Aqquota\*(Aq => 200 \& }, \& ); \& \& # Perform an API1 query \& $cp\->cpanel_api1_request(\*(Aqwhostmgr\*(Aq, \& { \& \*(Aqmodule\*(Aq => \*(AqLastLogin\*(Aq, \& \*(Aqfunc\*(Aq => \*(Aqlastlogin\*(Aq, \& \*(Aquser\*(Aq => \*(Aqsomeuser\*(Aq \& } \& ); \& # Pass parameters to an API1 query \& $cp\->cpanel_api1_request(\*(Aqcpanel\*(Aq, \& { \& \*(Aqmodule\*(Aq => \*(AqMysql\*(Aq, \& \*(Aqfunc\*(Aq => \*(Aqadduserdb\*(Aq, \& }, \& [ \*(Aqsomedb\*(Aq, \*(Aqsomedbuser\*(Aq, \*(AqALL\*(Aq ] \& ); \& \& # perform an HTTP GET request against a URL \& $cp\->api_request(\*(Aqwhostmgr\*(Aq, \*(Aq/xml\-api/loadavg\*(Aq, \*(AqGET\*(Aq); \& \& # perform an HTTP GET request with parameters \& $cp\->api_request(\*(Aqwhostmgr\*(Aq, \*(Aq/xml\-api/createacct\*(Aq, \*(AqGET\*(Aq, {\*(Aqusername\*(Aq => \*(Aqsomeuser\*(Aq, domain => \*(Aqdomain.com\*(Aq} ); \& \& # perform an HTTP POST request (with parameters) \& $cp\->api_request(\*(Aqwhostmgr\*(Aq, \*(Aq/xml\-api/createacct\*(Aq, \*(AqPOST\*(Aq, {\*(Aqusername\*(Aq => \*(Aqsomeuser\*(Aq, domain => \*(Aqdomain.com\*(Aq} ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" cPanel::PublicAPI is a supported interface for interacting with cPanel's APIs over \s-1HTTP.\s0 This allows you to query either \s-1WHM\s0 or cPanel accounts from a perl interface. The purpose of this module is to provide an easy-to-use interface into cPanel's various APIs without requiring much knowledge of how they work. .SS "Object Construction" .IX Subsection "Object Construction" a cPanel::PublicAPI object is constructed with the \fBnew()\fR method. .PP .Vb 1 \& my $publicapi = cPanel::PublicAPI\->new(); .Ve .PP When passed no parameters, this will create the object using the accesshash in ~/.accesshash. If no .accesshash file exists, it will attempt to use the \s-1REMOTE_PASS\s0 environment variable. If the \s-1REMOTE_PASS\s0 variable is not defined, object creation will error out. .PP \fI\f(BInew()\fI parameters\fR .IX Subsection "new() parameters" .PP options for \fBnew()\fR are specified as a hash reference, the following parameters are supported: .IP "\(bu" 4 user \- The username to authenticate as. .IP "\(bu" 4 pass \- The password to use for authentication. .IP "\(bu" 4 accesshash \- The accesshash to use for authentication (\s-1WHM\s0 only). .IP "\(bu" 4 api_token \- The \s-1API\s0 token to use for authentication. .IP "\(bu" 4 timeout \- The length of time (in seconds) before an http request should time out. Default to 300. .IP "\(bu" 4 ip \- The \s-1IP\s0 to be queried. defaults to 127.0.0.1, if host is defined it will take precedence over the 'ip' parameter. .IP "\(bu" 4 host \- The hostname to be queried. This will take precedence over the 'ip' parameter. .IP "\(bu" 4 usessl \- 1 or 0, Indicates whether communication should be performed over \s-1SSL\s0 or not (default to 1). .IP "\(bu" 4 ssl_verify_mode \- 1 or 0, Indicates whether to verify \s-1SSL\s0 certificates or not. (default to 1). .IP "\(bu" 4 error_log \- Path to where you want debug and error logging information to be written to. If this is not defined or the module is unable to open the path in question, it will default to \s-1STDERR.\s0 .IP "\(bu" 4 debug \- Enables debug logging, which will place considerably more information into the error_log. .IP "\(bu" 4 http_tiny_creator \- An optional code reference that receives the list of key/value pairs that normally goes into HTTP::Tiny’s constructor to create an instance of that class for this module’s internal use. The code reference, when called, should return an object that implements an HTTP::Tiny\-compatible interface. .Sp This parameter is useful for customizing that internal HTTP::Tiny instance that cPanel::PublicAPI uses. Handle with care, though: this parameter may break cPanel::PublicAPI in various ways—some subtle, others less so. .Sp For example, if you want a custom User-Agent header, you might do: .Sp .Vb 6 \& http_tiny_creator => sub { \& return HTTP::Tiny\->new( \& @_, \& agent => \*(AqMy Custom UA String\*(Aq, \& ); \& }, .Ve .PP \fIAuthentication methods\fR .IX Subsection "Authentication methods" .PP This module supports three authentication methods: .IP "1. Username & Password" 4 .IX Item "1. Username & Password" .Vb 2 \& use cPanel::PublicAPI; \& my $pubapi = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqfoo\*(Aq, \*(Aqpass\*(Aq => \*(Aqbar\*(Aq ); .Ve .IP "2. \s-1API\s0 Token" 4 .IX Item "2. API Token" (Note: This method does not work with Webmail.) .Sp To create an \s-1API\s0 token, visit \*(L"Manage \s-1API\s0 Tokens\*(R" in cPanel or \s-1WHM,\s0 and follow the appropriate prompts. Your token will appear in a special notice. Make certain that you save your \s-1API\s0 token in a safe location, as this is the only time the token will be shown to you. .Sp To use an \s-1API\s0 token with this module, do the following: .Sp .Vb 2 \& use cPanel::PublicAPI; \& my $pubapi = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqfoo\*(Aq, \*(Aqapi_token\*(Aq => $string_containing_api_token ); .Ve .IP "3. \s-1WHM\s0 Access Hash" 4 .IX Item "3. WHM Access Hash" \&\fB\s-1NOTE:\s0\fR Accesshash authentication is deprecated as of cPanel & \s-1WHM\s0 version 64. .Sp To configure accesshashes, you can either: .RS 4 .IP "\(bu" 4 In cPanel & \s-1WHM\s0 version 66 and earlier, visit “Setup remote access key” in \s-1WHM\s0 which will generate an accesshash for your server if one does not already exist. .IP "\(bu" 4 Run \fI/usr/local/cpanel/bin/mkaccesshash\fR. This will overwrite any existing access hash. .RE .RS 4 .Sp The generated accesshash is stored in \fI~/.accesshash\fR. .Sp To use an accesshash with this module, do the following: .Sp .Vb 2 \& use cPanel::PublicAPI; \& my $pubapi = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqfoo\*(Aq, \*(Aqaccesshash\*(Aq => $string_containing_access_hash ); .Ve .Sp It should be noted that the accesshash can contain newlines in it. Newlines will be stripped by the object when it attempts to perform a query. .RE .PP \fIDependencies\fR .IX Subsection "Dependencies" .PP This module will fall back on different modules if one fails to load. This allows for compatibility with cPanel & \s-1WHM\s0's internal perl parser and maintain compatibility with a standard perl implementation. The order that it will fall back on serialization modules is: .IP "\(bu" 4 JSON::Syck .IP "\(bu" 4 \&\s-1JSON\s0 .IP "\(bu" 4 \&\s-1JSON::XS\s0 .IP "\(bu" 4 \&\s-1JSON::PP\s0 .PP If you installed this module via \s-1CPAN,\s0 this should never be an issue. If you are wishing to use this module on a system where you do not have access to compiled modules, \s-1JSON::PP\s0 is the recommended serializer. .SH "Two-Factor Authentication (2FA)" .IX Header "Two-Factor Authentication (2FA)" cPanel version 54 and above allows users to configure 2FA on their accounts \- this security policy requires that the \s-1API\s0 queries are performed after authenticating and establishing a session. The workflow to accomodate 2FA will be as so: .PP .Vb 1 \& use cPanel::PublicAPI; \& \& use lib \*(Aq/usr/local/cpanel\*(Aq; \& use Cpanel::Security::Authn::TwoFactorAuth::Google (); # only available in 11.54+ \& \& my $pubapi = cPanel::PublicAPI\->new( \*(Aquser\*(Aq => \*(Aqfoo\*(Aq, \*(Aqpass\*(Aq => \*(Aqbar\*(Aq ); \& my $google_auth = Cpanel::Security::Authn::TwoFactorAuth::Google\->new( \& { \& \*(Aqaccount_name\*(Aq => \*(Aqfoo\*(Aq, \& \*(Aqsecret\*(Aq => $user_2fa_secret, \& \*(Aqissuer\*(Aq => \*(Aq\*(Aq \& } \& ); \& $pubapi\->establish_tfa_session(\*(Aqwhostmgr\*(Aq, $google_auth\->generate_code()); \& $pubapi\->whm_api(\*(Aqapplist\*(Aq); .Ve .PP Anytime you change services (e.g. from 'whostmgr' to 'cpanel'), you must establish the 2FA session for the new service. .PP .Vb 4 \& eval { \& $pubapi\->cpanel_api2_request(\*(Aqcpanel\*(Aq, { \*(Aquser\*(Aq => \*(Aqfoo\*(Aq, \*(Aqmodule\*(Aq => \*(AqMysqlFE\*(Aq, \*(Aqfunc\*(Aq => \*(Aqlistdbs\*(Aq }, {} ); \& }; \& print "failed cause 2fa session wasn\*(Aqt established\en" if $@; \& \& $pubapi\->establish_tfa_session(\*(Aqcpanel\*(Aq, $google_auth\->generate_code()); \& eval { \& $pubapi\->cpanel_api2_request(\*(Aqcpanel\*(Aq, { \*(Aquser\*(Aq => \*(Aqfoo\*(Aq, \*(Aqmodule\*(Aq => \*(AqMysqlFE\*(Aq, \*(Aqfunc\*(Aq => \*(Aqlistdbs\*(Aq }, {} ); \& }; \& print "success\en" if not $@; .Ve .PP \&\fB\s-1NOTE\s0\fR: Additionally, since accesshash authentication is not allowed to establish sessions, you must use the 'user'/'pass' authentication in order to make \s-1API\s0 requests as a user with 2FA configured. .SH "Important Methods" .IX Header "Important Methods" .SS "Querying the xml-api \- \fBwhm_api()\fP" .IX Subsection "Querying the xml-api - whm_api()" The XML-API is \s-1WHM\s0's \s-1API\s0 used for administrative functions is handled via the \fBwhm_api()\fR method. .PP The syntax for whmapi is: .PP .Vb 1 \& $cp\->whm_api($call [, \e%formdata, $format ] ); .Ve .PP The meaning of these parameters is: .IP "\(bu" 4 \&\f(CW$call\fR \- The XML-API call you wish to query .IP "\(bu" 4 \&\f(CW$formdata\fR \- The parameters for the XML-API call in question, f.ex. for suspendacct, here you would pass in a hashref containing “user” and “reason”. If there are no parameters, this can be undef or a blank hash. .IP "\(bu" 4 \&\f(CW$format\fR \- The requested response format. The valid values here are “xml”, “json” or “ref” (perl hash reference). This will default to returning a perl hash reference when the value is undef. .PP By default, \s-1WHM API\s0 v1 is used. If, for legacy reasons, you need to use v0, please set the \f(CW\*(C`api.version\*(C'\fR key to 0 in the formdata parameter. .PP For more information on what calls are available and how they can be referenced, please see the xml-api documentation at <http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi>. .SS "Querying cPanel's APIs" .IX Subsection "Querying cPanel's APIs" cPanel supports two APIs, designated \*(L"\s-1API1\*(R"\s0 and \*(L"\s-1API2\*(R".\s0 .PP cPanel \s-1API\s0 calls are seperate into Modules, these module names relate to modules within the Cpanel namespace on a cPanel server. Each module defines a set of functions that are from either \s-1API1\s0 or \s-1API2\s0 (or both). .PP There are two distinct differences between \s-1API1\s0 and \s-1API2:\s0 .IP "\(bu" 4 \&\s-1API1\s0 Takes in ordered parameters and returns strings .IP "\(bu" 4 \&\s-1API2\s0 uses named parameters and returns hashes or arrays of hashes .PP Within the context of the public api, calling a function from \s-1API1\s0 or \s-1API2\s0 will always return a hash, but the specific data returned from the \s-1API\s0 call will be contained within the 'data' key of the response. .PP For more information on the differences between \s-1API1\s0 and \s-1API2\s0 please see the documentation: <http://docs.cpanel.net/twiki/bin/view/DeveloperResources/ApiBasics/WebHome> .PP For information on calling \s-1API1\s0 and \s-1API2\s0 direct via \s-1HTTP,\s0 please see: <http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/CallingAPIFunctions> .PP \fI\f(BIcpanel_api1_request()\fI\fR .IX Subsection "cpanel_api1_request()" .PP \&\f(CW\*(C`cpanel_api1_request()\*(C'\fR is used to query cPanel's \s-1API1,\s0 the function used for querying \s-1API1\s0 has the following syntax: .PP .Vb 1 \& $cp\->cpanel_api1_request($service, \e%cfg [, \e@params, $format ] ); .Ve .IP "\(bu" 4 \&\f(CW$service\fR \- The service that you wish to query. This can be 'cpanel' 'whostmgr', or 'webmail'. It is important to note that what services you are able to query depends on the user you are authenticated as. Only a user with reseller or root access can use the whostmgr service. If you are authenticated as root, you will not be able to query the 'cpanel' service. When the service is set to 'whostmgr' a 'user' must be set in the \f(CW$cfg\fR hash. .IP "\(bu" 4 \&\f(CW$cfg\fR \- A hash reference describing the call you wish to make. Required parameters are 'module' and 'func', which correspond to the module and function of the \s-1API\s0 call you wish to query. If you are querying the \*(L"whostmgr\*(R" service, you will need to specify 'user' as well. .IP "\(bu" 4 \&\f(CW$params\fR \- An array reference containing the parameters you wish to pass to the \s-1API\s0 call. .IP "\(bu" 4 \&\f(CW$format\fR \- The format for the xml-api to respond in. The valid values here are “xml”, “json” or “ref” (perl hash reference). This will default to returning a perl hash reference. .PP To see what modules and functions are available for making \s-1API1\s0 calls, please see: <http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api1/WebHome> .PP \fI\f(BIcpanel_api2_request()\fI\fR .IX Subsection "cpanel_api2_request()" .PP \&\f(CW\*(C`cpanel_api2_request()\*(C'\fR is used to query cPanel's \s-1API2,\s0 the function use for querying \s-1API2\s0 has the following syntax: .PP .Vb 1 \& $cp\->cpanel_api2_request( $service, \e%cfg [, \e%params, $format ] ); .Ve .IP "\(bu" 4 \&\f(CW$service\fR \- The service that you wish to query. This can be 'cpanel' 'whostmgr', or 'webmail'. It is important to note that what services you are able to query depends on the user you are authenticated as. A user that does not have reseller or root access will not be able to use the whostmgr service. If you are authenticated as root, you will not be able to query the 'cpanel' service. When the service is set to 'whostmgr' a 'user' must be set in the \f(CW$cfg\fR hash. .IP "\(bu" 4 \&\f(CW$cfg\fR \- A hash reference describing the call you wish to make. required parameters here are 'module' and 'func', which correspond to the module and function of the \s-1API\s0 call you wish to query. If you are querying the \*(L"whostmgr\*(R" service, you will need to specify 'user' as well. .IP "\(bu" 4 \&\f(CW$params\fR \- An hash reference containing the parameters you wish to pass to the \s-1API\s0 call. .IP "\(bu" 4 \&\f(CW$format\fR \- The format for the xml-api to respond in. The valid values here are “xml”, “json” or “ref” (perl hash reference). This will default to returning a perl hash reference when the value is undef. .PP To see what modules and functions are available for making \s-1API2\s0 calls, please see: <http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api2/WebHome> .SS "\fBapi_request()\fP \- Making direct \s-1URL\s0 requests to cPanel & \s-1WHM.\s0" .IX Subsection "api_request() - Making direct URL requests to cPanel & WHM." There are some situations where you will need to query cPanel and \s-1WHM\s0 URLs directly. This should \s-1ONLY\s0 be done when there is not an \s-1API\s0 call available for the function you wish to query. .PP The function used for querying URLs directly is \fBapi_request()\fR. It will always return a string rather than converting the response into a hash reference. It uses the following syntax: .PP .Vb 1 \& $cp\->api_request( $service, $uri, $method, \e%formdata, $headers) .Ve .IP "\(bu" 4 \&\f(CW$service\fR \- The service that you wish to query. This can be 'cpanel' 'whostmgr', or 'webmail', when passed an numerical value, PublicAPI will query that port directly. .IP "\(bu" 4 \&\f(CW$uri\fR \- The \s-1URL\s0 you wish to query, e.g. '/xml\-api/cpanel' .IP "\(bu" 4 \&\f(CW$method\fR \- '\s-1GET\s0' or '\s-1POST\s0' .IP "\(bu" 4 \&\f(CW$formdata\fR \- The data you wish to pass to the \s-1URL\s0 .IP "\(bu" 4 \&\f(CW$headers\fR \- Any additional headers are to be passed with the request. These can be either a flat string or as a hashref like {'headertitle' => 'headerdata'} .SH "Other Features" .IX Header "Other Features" .ie n .IP """establish_tfa_session()""" 4 .el .IP "\f(CWestablish_tfa_session()\fR" 4 .IX Item "establish_tfa_session()" .PP See \*(L"Two-Factor Authentication (2FA)\*(R" above. .ie n .IP """set_debug()""" 4 .el .IP "\f(CWset_debug()\fR" 4 .IX Item "set_debug()" .PP This function allows you to enable/disable debug mode by passing a value that evaluates to 'true' or 'false'. .ie n .IP """user()""" 4 .el .IP "\f(CWuser()\fR" 4 .IX Item "user()" .PP Allows you to change the user that your PublicAPI object is authenticating with. .ie n .IP """pass()""" 4 .el .IP "\f(CWpass()\fR" 4 .IX Item "pass()" .PP Allows you to change the password that your PublicAPI object is authenticating with, this will remove the stored accesshash from the object. .ie n .IP """accesshash()""" 4 .el .IP "\f(CWaccesshash()\fR" 4 .IX Item "accesshash()" .PP Allows you to change the accesshash that your PublicAPI object is authenticating with, this will remove the stored password from the object. .ie n .IP """api_token()""" 4 .el .IP "\f(CWapi_token()\fR" 4 .IX Item "api_token()" .PP Allows you to change the \s-1API\s0 token that your PublicAPI object is authenticating with, this will remove the stored password from the object. .ie n .IP """format_http_query()""" 4 .el .IP "\f(CWformat_http_query()\fR" 4 .IX Item "format_http_query()" .PP Allows you to construct formdata for an http query from a hash. For Example: .PP .Vb 1 \& $pubapi\->format_http_query( { \*(Aqone\*(Aq => \*(Aq1\*(Aq, \*(Aqtwo\*(Aq => 2 } ); .Ve .PP would return: .PP .Vb 1 \& \*(Aqone=1&two=2\*(Aq .Ve .ie n .IP """format_http_headers()""" 4 .el .IP "\f(CWformat_http_headers()\fR" 4 .IX Item "format_http_headers()" .PP Allows you to construct headers for an http query from a hash. For Example: .PP .Vb 1 \& $pubapi\->format_http_headers( { \*(AqAuthorization\*(Aq => \*(AqBasic cm9vdDpsMGx1cnNtNHJ0IQ==\*(Aq} ); .Ve .PP would return: .PP .Vb 1 \& \*(AqAuthorization: Basic cm9vdDpsMGx1cnNtNHJ0IQ==\er\en\*(Aq .Ve .ie n .IP """$pubapi\->{\*(Aqerror\*(Aq}""" 4 .el .IP "\f(CW$pubapi\->{\*(Aqerror\*(Aq}\fR" 4 .IX Item "$pubapi->{error}" .PP Errors encountered within the class are stored here before being written out to the error_fh filehandle. This can be used for checking the existance of query errors. .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[f8�,� � man3/cPanel::PublicAPI::WHM.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM 3" .TH cPanel::PublicAPI::WHM 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM \- Legacy interface for querying WHM. .PP NOTE: This module is provided for legacy purposes, cPanel::PublicAPI should be used instead .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides legacy compatibility support between cPanel::PublicAPI and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). .SH "functions" .IX Header "functions" .ie n .SS """simple_get_whmreq()""" .el .SS "\f(CWsimple_get_whmreq()\fP" .IX Subsection "simple_get_whmreq()" This function makes a \s-1HTTP GET\s0 query to \s-1WHM,\s0 an equivalent function within cPanel::PublicAPI is \f(CW\*(C`api_request()\*(C'\fR. This function uses two arrays to specify arguments to be passed to a specific \s-1URI.\s0 This means that you would need to ensure that they both have the key/pair values in the same place in each array, f.ex: .PP .Vb 2 \& $argref = [\*(Aqvalue1\*(Aq, \*(Aqvalue2\*(Aq, \*(Aqvalue3\*(Aq]; \& $argnameref = [\*(Aqkey1\*(Aq, \*(Aqkey2\*(Aq, \*(Aqkey3\*(Aq]; .Ve .PP would be be specifying: .PP .Vb 1 \& key1=value1&key2=value2&key3=value3 .Ve .PP to be passed to the specified \s-1URI.\s0 .PP Arguments .IP "\(bu" 4 \&\f(CW$uri\fR \- The \s-1URI\s0 you to be queried. .IP "\(bu" 4 \&\f(CW$argref\fR \- An array reference containing the values to be passed. .IP "\(bu" 4 \&\f(CW$argnameref\fR \- An array reference containing the keys to be passed. .IP "\(bu" 4 \&\f(CW$opts\fR \- An array reference containing strings like 'key1=value1' to be passed to the \s-1URI.\s0 .PP This will return a scalar reference of the data returned by cpsrvd. .ie n .SS """simple_post_whmreq()""" .el .SS "\f(CWsimple_post_whmreq()\fP" .IX Subsection "simple_post_whmreq()" This function makes a \s-1HTTP POST\s0 query to \s-1WHM,\s0 an equivalent function within cPanel::PublicAPI is \f(CW\*(C`api_request()\*(C'\fR. This function uses two arrays to specify arguments to be passed to a specific \s-1URI.\s0 This means that you would need to ensure that they both have the key/pair values in the same place in each array, f.ex: .PP .Vb 2 \& $argref = [\*(Aqvalue1\*(Aq, \*(Aqvalue2\*(Aq, \*(Aqvalue3\*(Aq]; \& $argnameref = [\*(Aqkey1\*(Aq, \*(Aqkey2\*(Aq, \*(Aqkey3\*(Aq]; .Ve .PP would be be specifying: .PP .Vb 1 \& key1=value1&key2=value2&key3=value3 .Ve .PP to be passed to the specified \s-1URI.\s0 .PP Arguments .IP "\(bu" 4 \&\f(CW$uri\fR \- The \s-1URI\s0 you to be queried. .IP "\(bu" 4 \&\f(CW$argref\fR \- An array reference containing the values to be passed. .IP "\(bu" 4 \&\f(CW$argnameref\fR \- An array reference containing the keys to be passed. .IP "\(bu" 4 \&\f(CW$opts\fR \- An array reference containing strings like 'key1=value1' to be passed to the \s-1URI.\s0 .PP This will return a scalar containing the data returned by cpsrvd. .ie n .SS """whmreq()""" .el .SS "\f(CWwhmreq()\fP" .IX Subsection "whmreq()" This function is used to querying \s-1WHM\s0 with either \s-1GET\s0 or \s-1POST\s0 data. .IP "\(bu" 4 \&\f(CW$uri\fR \- The \s-1URI\s0 to be queried. .IP "\(bu" 4 \&\f(CW$method\fR \- The method of querying the \s-1URI\s0 (either \s-1GET\s0 or \s-1POST\s0). .IP "\(bu" 4 \&\f(CW$formdata\fR \- The data to be passed to the \s-1URI\s0 formatted as formdata (e.g. 'key1=value1&key2=value2'). .ie n .SS """api1()""" .el .SS "\f(CWapi1()\fP" .IX Subsection "api1()" This function is used to query cPanel's \s-1API1.\s0 This will return the \s-1XML\s0 response from the \s-1XML API\s0's cpanel call. .IP "\(bu" 4 \&\f(CW$user\fR \- The user to execute an \s-1API\s0 call for. .IP "\(bu" 4 \&\f(CW$module\fR \- The module of the \s-1API\s0 call to be executed. .IP "\(bu" 4 \&\f(CW$func\fR \- The name of the \s-1API\s0 call to be executed. .IP "\(bu" 4 \&\f(CW@params\fR \- An array containing the parameters for the \s-1API\s0 call. .ie n .SS """api2()""" .el .SS "\f(CWapi2()\fP" .IX Subsection "api2()" This function is used to query cPanel's \s-1API1.\s0 This will return the \s-1XML\s0 response from the \s-1XML API\s0's cpanel call. .IP "\(bu" 4 \&\f(CW$user\fR \- The user to execute an \s-1API\s0 call for. .IP "\(bu" 4 \&\f(CW$module\fR \- The module of the \s-1API\s0 call to be executed. .IP "\(bu" 4 \&\f(CW$func\fR \- The name of the \s-1API\s0 call to be executed. .IP "\(bu" 4 \&\f(CW%params\fR \- An hash containing the parameters for the \s-1API\s0 call. .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[%��q q . man3/cPanel::PublicAPI::WHM::CachedVersion.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM::CachedVersion 3" .TH cPanel::PublicAPI::WHM::CachedVersion 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM::CachedVersion \- Allows for lookups of remote versions of cPanel & WHM. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module allows you to lookup the version of a remote instance of cPanel & \s-1WHM\s0 based off of the contents of /var/cpanel/accounting/cache, if the server is not stored there, it will perform the version call. .PP /var/cpanel must exist in order for this to work, /var/cpanel/accounting and /var/cpanel/accounting/cache will be created if necessary. .SH "\fBcached_version()\fP" .IX Header "cached_version()" This module consists of a single function \- \fBcPanel::PublicAPI::WHM::CachedVersion::cached_version()\fR. It expects an already configured publicapi instance. .PP Syntax: .PP .Vb 2 \& my $pubapi = cPanel::PublicAPI::WHM::CachedVersion\->new( \*(Aqhost\*(Aq => \*(Aqsomehost\*(Aq, \*(Aquser\*(Aq => \*(Aqsomeuser\*(Aq, ... ); \& my $version = $pubapi\->cached_version(); .Ve .PP This will return a string containing the version of the cpanel/whm server being queried. .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[xB�( ( $ man3/cPanel::PublicAPI::WHM::DNS.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM::DNS 3" .TH cPanel::PublicAPI::WHM::DNS 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM::DNS \- A module for interacting with WHM's DNS clustering system. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is intended as a client for querying \s-1WHM\s0's \s-1DNS\s0 clustering system. Unless you are specifically looking to write your own interaction with cPanel's \s-1DNS\s0 system, you should never need to use this module, rather the \s-1DNS\s0 functions within cPanel's XML-API should do what you are looking for: <http://docs.cpanel.net/twiki/bin/vief/AllDocumentation/AutomationIntegration/XmlApi#DNS%20functions> .SH "functions" .IX Header "functions" The functions contained within this module share a similiar naming scheme for the variables used within, please consult the list below when figuring out what each function does. .IP "\(bu" 4 \&\f(CW$zone\fR \- The name of the domain to be used. .IP "\(bu" 4 \&\f(CW$dnsuniqid\fR \- A Unique string used to identify uniquely (suggested: 32 character alphanumeric) .IP "\(bu" 4 \&\f(CW$zones\fR \- A pipe seperated list of domains. .IP "\(bu" 4 \&\f(CW$zonedata\fR \- The contents of a zone file, usually used for sending changes of a zone to another system. .ie n .SS """addtocluster()""" .el .SS "\f(CWaddtocluster()\fP" .IX Subsection "addtocluster()" Add a machine to a \s-1DNS\s0 cluster. .PP Call specific parameters: .IP "\(bu" 4 \&\f(CW$clustermaster\fR \- The \s-1IP\s0 of the machine being added to the cluster. .IP "\(bu" 4 \&\f(CW$user\fR \- The user to authenticate \s-1DNS\s0 requests as. .IP "\(bu" 4 \&\f(CW$pass\fR \- The accesshash or \s-1API\s0 token to authenticate \s-1DNS\s0 requests with .IP "\(bu" 4 \&\f(CW$version\fR \- The version of cPanel/WHM of the machine being added to the cluster .PP Syntax: .PP .Vb 1 \& $pubapi\->addtocluster( $user, $clustermaster, $accesshash, $version ) .Ve .ie n .SS """getzone_local()""" .el .SS "\f(CWgetzone_local()\fP" .IX Subsection "getzone_local()" Get the contents of a zone file. .PP Syntax: .PP .Vb 1 \& $pubapi\->getzone_local( $zone, $dnsuniqid ) .Ve .ie n .SS """getzones_local()""" .el .SS "\f(CWgetzones_local()\fP" .IX Subsection "getzones_local()" Get the contents of multiple zone files, this will be split up as: .PP .Vb 1 \& cpdnszone\-%URI ENCODED ZONENAME%=%URI encoded version of zone file%&cpdnszone... .Ve .PP for each zone in the response .PP Syntax: .PP .Vb 1 \& $pubapi\->getzones_local( $zones, $dnsuniqid ) .Ve .ie n .SS """getallzones_local()""" .el .SS "\f(CWgetallzones_local()\fP" .IX Subsection "getallzones_local()" Like getzones_local, but will return all zones in a cluster. .PP Syntax: .PP .Vb 1 \& $pubapi\->getallzones_local( $dnsuniqid ) .Ve .ie n .SS """cleandns_local()""" .el .SS "\f(CWcleandns_local()\fP" .IX Subsection "cleandns_local()" Clean up any old or unused \s-1DNS\s0 zones from named.conf. .PP Syntax: .PP .Vb 1 \& $pubapi\->cleandns_local( $dnsuniqid ) .Ve .ie n .SS """getips_local()""" .el .SS "\f(CWgetips_local()\fP" .IX Subsection "getips_local()" Get a list of extra IPs available on a system, response will be formated as: .PP \&\f(CW$ip:\fR$netmask:$broadcast .PP Syntax: .PP .Vb 1 \& $pubapi\->getips_local( $dnsuniqid ) .Ve .ie n .SS """getpath_local()""" .el .SS "\f(CWgetpath_local()\fP" .IX Subsection "getpath_local()" Returns a newline separated list containing all the machines that this machine is clustered with in the following format: .PP \&\f(CW$hostname\fR \f(CW$remote_host\fR .PP Syntax: .PP .Vb 1 \& $pubapi\->getpath_local( $dnsuniqid ) .Ve .ie n .SS """removezone_local()""" .el .SS "\f(CWremovezone_local()\fP" .IX Subsection "removezone_local()" Remove a \s-1DNS\s0 zone. .PP Syntax: .PP .Vb 1 \& $pubapi\->removezone_local( $zone, $dnsuniqid ) .Ve .ie n .SS """removezones_local()""" .el .SS "\f(CWremovezones_local()\fP" .IX Subsection "removezones_local()" Remove multiple \s-1DNS\s0 zones. .PP Syntax: .PP .Vb 1 \& $pubapi\->removezones_local( $zones, $dnsuniqid ) .Ve .ie n .SS """reloadzones_local()""" .el .SS "\f(CWreloadzones_local()\fP" .IX Subsection "reloadzones_local()" Force bind to re-read zones files via the \*(L"rndc reload\*(R" command. .PP Syntax: .PP .Vb 1 \& $pubapi\->reloadzones_local( $dnsuniqid, $zones ) .Ve .ie n .SS """reloadbind_local()""" .el .SS "\f(CWreloadbind_local()\fP" .IX Subsection "reloadbind_local()" Run the 'rndc reload' command. If no zones are specified, bind will reload everything. .PP Syntax: .PP .Vb 1 \& $pubapi\->reloadbind_local( $dnsuniqid, $zone ) .Ve .ie n .SS """reconfigbind_local()""" .el .SS "\f(CWreconfigbind_local()\fP" .IX Subsection "reconfigbind_local()" Run the 'rndc reconfig' command. .PP Syntax: .PP .Vb 1 \& $pubapi\->reconfigbind_local( $dnsuniqid, $zone ) .Ve .ie n .SS """quickzoneadd_local()""" .el .SS "\f(CWquickzoneadd_local()\fP" .IX Subsection "quickzoneadd_local()" Add a new zone to a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->quickzoneadd_local( $zone, $zonedata, $dnsuniqid ) .Ve .ie n .SS """savezone_local()""" .el .SS "\f(CWsavezone_local()\fP" .IX Subsection "savezone_local()" Update a zone file with the data specified in \f(CW$zonedata\fR. .PP Syntax: .PP .Vb 1 \& $pubapi\->savezone_local( $zone, $zonedata, $dnsuniqid ) .Ve .ie n .SS """synczones_local()""" .el .SS "\f(CWsynczones_local()\fP" .IX Subsection "synczones_local()" Send a dump of all zones and update zones when required. The zones are sent within the \f(CW$formdata\fR in the following format: .PP .Vb 1 \& cpdnszone\-%URI ENCODED ZONENAME%=%URI encoded version of zone file%&cpdnszone... .Ve .PP Syntax: .PP .Vb 1 \& $pubapi\->synczones_local( $formdata, $dnsuniqid ) .Ve .ie n .SS """addzoneconf_local()""" .el .SS "\f(CWaddzoneconf_local()\fP" .IX Subsection "addzoneconf_local()" Add a zone to the named.conf file. .PP Syntax: .PP .Vb 1 \& $pubapi\->addzoneconf_local( $zone, $dnsuniqid ) .Ve .ie n .SS """getzonelist_local()""" .el .SS "\f(CWgetzonelist_local()\fP" .IX Subsection "getzonelist_local()" Get a newline seperated list of the zones on a system. .PP Syntax: .PP .Vb 1 \& $pubapi\->getzonelist_local( $dnsuniqid ) .Ve .ie n .SS """zoneexists_local()""" .el .SS "\f(CWzoneexists_local()\fP" .IX Subsection "zoneexists_local()" Return boolean value indicating whether a zone exists on a remote system or not. .PP Syntax: .PP .Vb 1 \& $pubapi\->zoneexists_local( $zone, $dnsuniqid ) .Ve .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[��*o o ' man3/cPanel::PublicAPI::WHM::Legacy.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "cPanel::PublicAPI::WHM::Legacy 3" .TH cPanel::PublicAPI::WHM::Legacy 3 "2019-03-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cPanel::PublicAPI::WHM::Legacy \- A module for handling Cpanel::Accounting backward compatibility within the cPanel::PublicAPI framework. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module should never be used, please use cPanel::PublicAPI\->\fBwhm_api()\fR instead. .SH "Bugs" .IX Header "Bugs" see http://rt.cpan.org to report and view bugs .SH "License" .IX Header "License" Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL\s0 \s-1BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 PK � �[ " arch/auto/cPanel/PublicAPI/.existsnu �[��� PK � �[+` n� � lib/cPanel/PublicAPI/WHM.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM - Legacy interface for querying WHM. NOTE: This module is provided for legacy purposes, L<cPanel::PublicAPI> should be used instead =head1 DESCRIPTION This module provides legacy compatibility support between L<cPanel::PublicAPI> and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). =head1 functions =head2 C<simple_get_whmreq()> This function makes a HTTP GET query to WHM, an equivalent function within L<cPanel::PublicAPI> is C<api_request()>. This function uses two arrays to specify arguments to be passed to a specific URI. This means that you would need to ensure that they both have the key/pair values in the same place in each array, f.ex: $argref = ['value1', 'value2', 'value3']; $argnameref = ['key1', 'key2', 'key3']; would be be specifying: key1=value1&key2=value2&key3=value3 to be passed to the specified URI. Arguments =over =item * $uri - The URI you to be queried. =item * $argref - An array reference containing the values to be passed. =item * $argnameref - An array reference containing the keys to be passed. =item * $opts - An array reference containing strings like 'key1=value1' to be passed to the URI. =back This will return a scalar reference of the data returned by cpsrvd. =head2 C<simple_post_whmreq()> This function makes a HTTP POST query to WHM, an equivalent function within L<cPanel::PublicAPI> is C<api_request()>. This function uses two arrays to specify arguments to be passed to a specific URI. This means that you would need to ensure that they both have the key/pair values in the same place in each array, f.ex: $argref = ['value1', 'value2', 'value3']; $argnameref = ['key1', 'key2', 'key3']; would be be specifying: key1=value1&key2=value2&key3=value3 to be passed to the specified URI. Arguments =over =item * $uri - The URI you to be queried. =item * $argref - An array reference containing the values to be passed. =item * $argnameref - An array reference containing the keys to be passed. =item * $opts - An array reference containing strings like 'key1=value1' to be passed to the URI. =back This will return a scalar containing the data returned by cpsrvd. =head2 C<whmreq()> This function is used to querying WHM with either GET or POST data. =over =item * $uri - The URI to be queried. =item * $method - The method of querying the URI (either GET or POST). =item * $formdata - The data to be passed to the URI formatted as formdata (e.g. 'key1=value1&key2=value2'). =back =head2 C<api1()> This function is used to query cPanel's API1. This will return the XML response from the XML API's cpanel call. =over =item * $user - The user to execute an API call for. =item * $module - The module of the API call to be executed. =item * $func - The name of the API call to be executed. =item * @params - An array containing the parameters for the API call. =back =head2 C<api2()> This function is used to query cPanel's API1. This will return the XML response from the XML API's cpanel call. =over =item * $user - The user to execute an API call for. =item * $module - The module of the API call to be executed. =item * $func - The name of the API call to be executed. =item * %params - An hash containing the parameters for the API call. =back =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[�J�� � lib/cPanel/PublicAPI/Utils.pmnu ��6�$ package cPanel::PublicAPI::Utils; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. sub remove_trailing_newline { my $string = shift; $string =~ s/\r?\n$//g; return $string; } sub get_string_with_collapsed_trailing_eols { my @copy = @_; # this addresses 'Modification of a read-only value attempted at Cpanel/Accounting.pm ...' from $line =~ below my $txt; foreach my $line (@copy) { if ( ref $line eq 'ARRAY' ) { foreach my $subline ( @{$line} ) { $subline =~ s/[\r\n]+$//g; $txt .= $subline . "\n"; } } else { $line =~ s/[\r\n]+$//g; $txt .= $line . "\n"; } } return $txt; } 1; PK � �[��>�� � * lib/cPanel/PublicAPI/WHM/CachedVersion.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM::CachedVersion - Allows for lookups of remote versions of cPanel & WHM. =head1 DESCRIPTION This module allows you to lookup the version of a remote instance of cPanel & WHM based off of the contents of /var/cpanel/accounting/cache, if the server is not stored there, it will perform the version call. /var/cpanel must exist in order for this to work, /var/cpanel/accounting and /var/cpanel/accounting/cache will be created if necessary. =head1 cached_version() This module consists of a single function - cPanel::PublicAPI::WHM::CachedVersion::cached_version(). It expects an already configured publicapi instance. Syntax: my $pubapi = cPanel::PublicAPI::WHM::CachedVersion->new( 'host' => 'somehost', 'user' => 'someuser', ... ); my $version = $pubapi->cached_version(); This will return a string containing the version of the cpanel/whm server being queried. =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[� `�C C lib/cPanel/PublicAPI/WHM/API.pmnu ��6�$ package cPanel::PublicAPI::API; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = '2.3'; package cPanel::PublicAPI; use cPanel::PublicAPI::WHM (); cPanel::PublicAPI::_init_serializer() if !exists $cPanel::PublicAPI::CFG{'serializer'}; sub api_listaccts { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listaccts', \@_, [ 'search', 'searchtype' ] ) ); } sub api_createacct { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/createacct', \@_, [ 'username', 'domain', 'password', 'plan' ] ) ); } sub api_removeacct { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/removeacct', \@_, ['user'] ) ); } sub api_showversion { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/version', \@_ ) ); } sub api_version { goto &xmlapi_showversion; } sub api_applist { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/applist', \@_ ) ); } sub api_generatessl { my $self = shift; return $self->serialize( $self->simple_post_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/generatessl', \@_, [ 'host', 'pass', 'country', 'state', 'city', 'co', 'cod', 'email', 'xemail' ] ) ); } sub api_generatessl_noemail { my $self = shift; return $self->serialize( $self->simple_post_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/generatessl', \@_, [ 'host', 'pass', 'country', 'state', 'city', 'co', 'cod', 'email' ], ['noemail=1'] ) ); } sub api_listcrts { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listcrts', \@_ ) ); } # Variable arguments sub api_setresellerlimits { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setresellerlimits', \@_ ) ); } sub api_setresellerpackagelimit { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setresellerpackagelimit', \@_, [ 'user', 'package', 'allowerd', 'number', 'no_limit' ] ) ); } sub api_setresellermainip { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setresellermainip', \@_, [ 'user', 'ip' ] ) ); } sub api_setresellerips { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setresellerips', \@_, [ 'user', 'delegate', 'ips' ] ) ); } sub api_setresellernameservers { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setresellernameservers', \@_, [ 'user', 'nameservers' ] ) ); } sub api_suspendreseller { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/suspendreseller', \@_, [ 'user', 'reason', 'disallow' ] ) ); } sub api_unsuspendreseller { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/unsuspendreseller', \@_, ['user'] ) ); } # Variable arguments sub api_addzonerecord { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/addzonerecord', \@_ ) ); } # Variable arguments sub api_editzonerecord { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/editzonerecord', \@_ ) ); } sub api_removezonerecord { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/removezonerecord', \@_, [ 'domain', 'Line' ] ) ); } sub api_getzonerecord { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/getzonerecord', \@_, [ 'domain', 'Line' ] ) ); } sub api_servicestatus { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/servicestatus', \@_, ['service'] ) ); } sub api_configureservice { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/configureservice', \@_, [ 'service', 'enabled', 'monitored' ] ) ); } sub api_acctcounts { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/acctcounts', \@_, ['user'] ) ); } sub api_domainuserdata { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/domainuserdata', \@_, ['domain'] ) ); } sub api_editquota { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/editquota', \@_, [ 'user', 'quota' ] ) ); } sub api_nvget { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/nvget', \@_, ['key'] ) ); } # The underlying XMLAPI call allows setting multiple nvvars at once by appending # labels to the end of the variable names... i.e. key1, value1 sub api_nvset { my $self = shift; return $self->serialize( $self->simple_post_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/nvset', \@_, [ 'key', 'value' ] ) ); } sub api_myprivs { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/myprivs', \@_ ) ); } sub api_listzones { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listzones', \@_ ) ); } sub api_sethostname { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/sethostname', \@_, ['hostname'] ) ); } sub api_setresolvers { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setresolvers', \@_, [ 'nameserver1', 'nameserver2', 'nameserver3' ] ) ); } sub api_addip { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/addip', \@_, [ 'ip', 'netmask' ] ) ); } sub api_delip { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/delip', \@_, [ 'ip', 'ethernetdev', 'skipifshutdown' ] ) ); } sub api_listips { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listips', \@_ ) ); } sub api_dumpzone { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/dumpzone', \@_, ['domain'] ) ); } sub api_listpkgs { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listpkgs', \@_ ) ); } sub api_limitbw { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/limitbw', \@_, [ 'user', 'bwlimit' ] ) ); } sub api_showbw { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/showbw', \@_, [ 'month', 'year', 'showres', 'search', 'searchtype' ] ) ); } sub api_killdns { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/killdns', \@_, ['domain'] ) ); } sub api_adddns { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/adddns', \@_, [ 'domain', 'ip', 'trueowner' ] ) ); } sub api_changepackage { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/changepackage', \@_, [ 'user', 'pkg' ] ) ); } sub api_modifyacct { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/modifyacct', \@_, [ 'user', 'domain', 'HASCGI', 'CPTHEME', 'LANG', 'MAXPOP', 'MAXFTP', 'MAXLST', 'MAXSUB', 'MAXPARK', 'MAXADDON', 'MAXSQL', 'shell' ] ) ); } sub api_suspendacct { my $self = shift; return $self->serialize( $self->simple_post_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/suspendacct', \@_, [ 'user', 'reason' ] ) ); } sub api_unsuspendacct { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/unsuspendacct', \@_, ['user'] ) ); } sub api_listsuspended { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listsuspended', \@_ ) ); } sub api_addpkg { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/addpkg', \@_, [ 'pkgname', 'quota', 'ip', 'cgi', 'cpmod', 'maxftp', 'maxsql', 'maxpop', 'maxlst', 'maxsub', 'maxpark', 'maxaddon', 'featurelist', 'hasshell', 'bwlimit' ] ) ); } sub api_killpkg { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/killpkg', \@_, ['pkg'] ) ); } sub api_editpkg { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/editpkg', \@_, [ 'pkgname', 'quota', 'ip', 'cgi', 'cpmod', 'maxftp', 'maxsql', 'maxpop', 'maxlst', 'maxsub', 'maxpark', 'maxaddon', 'featurelist', 'hasshell', 'bwlimit' ] ) ); } sub api_setacls { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setacls', \@_, [ 'reseller', 'acllist' ] ) ); } sub api_terminatereseller { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/terminatereseller', \@_, [ 'reseller', 'verify' ] ) ); } sub api_resellerstats { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/resellerstats', \@_, ['reseller'] ) ); } sub api_setupreseller { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setupreseller', \@_, [ 'user', 'makeowner' ] ) ); } sub api_lookupnsip { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/lookupnsip', \@_, ['nameserver'] ) ); } sub api_listresellers { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listresellers', \@_ ) ); } sub api_listacls { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/listacls', \@_ ) ); } sub api_saveacllist { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/saveacllist', \@_, ['acllist'] ) ); } sub api_unsetupreseller { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/unsetupreseller', \@_, ['user'] ) ); } sub api_gethostname { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/gethostname', \@_ ) ); } sub api_fetchsslinfo { my $self = shift; return $self->serialize( $self->simple_post_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/fetchsslinfo', \@_, [ 'domain', 'crtdata' ] ) ); } sub api_installssl { my $self = shift; return $self->serialize( $self->simple_post_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/installssl', \@_, [ 'domain', 'user', 'cert', 'key', 'cab', 'ip' ] ) ); } sub api_passwd { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/passwd', \@_, [ 'user', 'pass' ] ) ); } sub api_getlanglist { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/getlanglist', \@_ ) ); } sub api_reboot { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/reboot', \@_, ['force'] ) ); } sub api_accountsummary_user { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/accountsummary', \@_, ['user'] ) ); } sub api_accountsummary_domain { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/accountsummary', \@_, ['domain'] ) ); } sub api_loadavg { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/loadavg', \@_ ) ); } sub api_restartservice { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/restartservice', \@_, ['service'] ) ); } sub api_setsiteip_user { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setsiteip', \@_, [ 'user', 'ip' ] ) ); } sub api_setsiteip_domain { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/setsiteip', \@_, [ 'domain', 'ip' ] ) ); } sub api_initializemsgcenter { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/initializemsgcenter', \@_, [ 'title', 'id' ] ) ); } sub api_createmsg { my $self = shift; # Need to perform magic to deal with the optional parameters. my @parm_names = ( 'title', 'updated', 'published', 'content', 'author.name', 'author.email', 'author.uri', 'contributor.name', 'contributor.email', 'contributor.uri', 'summary' ); my $extra_count = scalar(@_) - scalar(@parm_names); my $cat_count = int( $extra_count / 3 + ( ( $extra_count % 3 ) && 1 ) ); foreach my $i ( 1 .. $cat_count ) { push @parm_names, "category.$i.term", "category.$i.label", "category.$i.scheme"; } return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/createmsg', \@_, \@parm_names ) ); } sub api_deletemsg { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/deletemsg', \@_, ['atom_id'] ) ); } sub api_getmsgfeed { my $self = shift; return $self->serialize( $self->simple_get_whmreq( '/' . $cPanel::PublicAPI::CFG{'serializer'} . '-api/getmsgfeed', \@_, ['which'] ) ); } sub serialize { my $self = shift; return $cPanel::PublicAPI::CFG{'api_decode_func'}->(@_); } 1; PK � �[��SZ- Z- $ lib/cPanel/PublicAPI/WHM/JSONAPI.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM::API - Legacy interface for querying the xml-api. NOTE: This module is provided for legacy purposes, L<cPanel::PublicAPI> should be used instead =head1 DESCRIPTION This module provides legacy compatibility support between L<cPanel::PublicAPI> and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). Every method contained within this object can be queried using cPanel::publicAPI::whm_api() instead. For more information on the calls within the methods contained here and what the parameter names mean, please read the documentation at: L<http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi> =head1 functions =head2 C<jsonapi_listaccts()> Used to list the accounts on a server. Syntax: $pubapi->jsonapi_listaccts( $search, $searchtype ); =head2 C<jsonapi_createacct()> Create a new cPanel account. Syntax: $pubapi->jsonapi_createacct( $username, $domain, $password, $plan ); =head2 C<jsonapi_removeacct()> Terminate an account. Syntax: $pubapi->jsonapi_removeacct( $user ); =head2 C<jsonapi_showversion()> Get the version of cPanel running on the server. Syntax: $pubapi->jsonapi_showversion( ); =head2 C<jsonapi_version()> Get the version of cPanel running on the server (as as showversion) Syntax: $pubapi->jsonapi_version( ); =head2 C<jsonapi_applist()> List out the available xml-api calls. Syntax: $pubapi->jsonapi_applist( ); =head2 C<jsonapi_generatessl()> Generate an ssl certificate. Syntax: $pubapi->jsonapi_generatessl( $host, $pass, $country, $state, $city, $co, $cod, $email, $xemail ); =head2 C<jsonapi_generatessl_noemail()> Generate an SSL certificate without an email. Syntax: $pubapi->jsonapi_generatessl_noemail( $noemail=1 ); =head2 C<jsonapi_listcrts()> List out the certificates that exist on the server. Syntax: $pubapi->jsonapi_listcrts( ); =head2 C<jsonapi_setresellerlimits()> Set the limits for a single reseller account. Syntax: $pubapi->jsonapi_setresellerlimits( ); =head2 C<jsonapi_setresellerpackagelimit()> Set which packages a reseller account can use. Syntax: $pubapi->jsonapi_setresellerpackagelimit( $user, $package, $allowerd, $number, $no_limit ); =head2 C<jsonapi_setresellermainip()> Set a reseller's main IP. Syntax: $pubapi->jsonapi_setresellermainip( $user, $ip ); =head2 C<jsonapi_setresellerips()> Set the IP that a reseller has available to it. Syntax: $pubapi->jsonapi_setresellerips( $user, $delegate, $ips ); =head2 C<jsonapi_setresellernameservers()> Set the nameservers that a reseller uses by default. Syntax: $pubapi->jsonapi_setresellernameservers( $user, $nameservers ); =head2 C<jsonapi_suspendreseller()> Suspend a reseller and all of their accounts. Syntax: $pubapi->jsonapi_suspendreseller( $user, $reason, $disallow ); =head2 C<jsonapi_unsuspendreseller()> Unsuspend a reseller and all of their accounts. Syntax: $pubapi->jsonapi_unsuspendreseller( $user ); =head2 C<jsonapi_addzonerecord()> Add a record to a zone. Syntax: $pubapi->jsonapi_addzonerecord( @args ); =head2 C<jsonapi_editzonerecord()> Edit a zone record. Syntax: $pubapi->jsonapi_editzonerecord(@args ); =head2 C<jsonapi_removezonerecord()> Remove a line from a zone. Syntax: $pubapi->jsonapi_removezonerecord( $domain, $Line ); =head2 C<jsonapi_getzonerecord()> Get a record from a zone. Syntax: $pubapi->jsonapi_getzonerecord( $domain, $Line ); =head2 C<jsonapi_servicestatus()> Get the status of various services running on a system. Syntax: $pubapi->jsonapi_servicestatus( $service ); =head2 C<jsonapi_configureservice()> Enable/Disable various services. Syntax: $pubapi->jsonapi_configureservice( $service, $enabled, $monitored ); =head2 C<jsonapi_acctcounts()> Get the number of accounts on a system/that belong to a reseller. Syntax: $pubapi->jsonapi_acctcounts( $user ); =head2 C<jsonapi_domainuserdata()> Get the information about a specific domain's virtualhost. Syntax: $pubapi->jsonapi_domainuserdata( $domain ); =head2 C<jsonapi_editquota()> Edit a user's quota. Syntax: $pubapi->jsonapi_editquota( $user, $quota ); =head2 C<jsonapi_nvget()> Get non-volatile data. Syntax: $pubapi->jsonapi_nvget( $key ); =head2 C<jsonapi_nvset()> Set non-volatile data. Syntax: $pubapi->jsonapi_nvset( $key, $value ); =head2 C<jsonapi_myprivs()> See what privileges are available to your user. Syntax: $pubapi->jsonapi_myprivs( ); =head2 C<jsonapi_listzones()> List all the zones available to a user. Syntax: $pubapi->jsonapi_listzones( ); =head2 C<jsonapi_sethostname()> Set the hostname of a system. Syntax: $pubapi->jsonapi_sethostname( $hostname ); =head2 C<jsonapi_setresolvers()> Set the resolvers a system uses. Syntax: $pubapi->jsonapi_setresolvers( $nameserver1, $nameserver2, $nameserver3 ); =head2 C<jsonapi_addip()> Add a new IP to a server. Syntax: $pubapi->jsonapi_addip( $ip, $netmask ); =head2 C<jsonapi_delip()> Remove an IP from a server. Syntax: $pubapi->jsonapi_delip( $ip, $ethernetdev, $skipifshutdown ); =head2 C<jsonapi_listips()> List the IPs on a server. Syntax: $pubapi->jsonapi_listips( ); =head2 C<jsonapi_dumpzone()> Get the contents of a zone file. Syntax: $pubapi->jsonapi_dumpzone( $domain ); =head2 C<jsonapi_listpkgs()> List the packages available to your user. Syntax: $pubapi->jsonapi_listpkgs( ); =head2 C<jsonapi_limitbw()> Limit the amount of bandwidth available to an account. Syntax: $pubapi->jsonapi_limitbw( $user, $bwlimit ); =head2 C<jsonapi_showbw()> Show the amount of BW used by an account. Syntax: $pubapi->jsonapi_showbw( $month, $year, $showres, $search, $searchtype ); =head2 C<jsonapi_killdns()> Remove a DNS zone. Syntax: $pubapi->jsonapi_killdns( $domain ); =head2 C<jsonapi_adddns()> Add a dns zone. Syntax: $pubapi->jsonapi_adddns( $domain, $ip, $trueowner ); =head2 C<jsonapi_changepackage()> Change an Account's Package. Syntax: $pubapi->jsonapi_changepackage( $user, $pkg ); =head2 C<jsonapi_modifyacct()> Modify an Account's limits. Syntax: $pubapi->jsonapi_modifyacct( $user, $domain, $HASCGI, $CPTHEME, $LANG, $MAXPOP, $MAXFTP, $MAXLST, $MAXSUB, $MAXPARK, $MAXADDON, $MAXSQL, $shell ); =head2 C<jsonapi_suspendacct()> Suspend an account. Syntax: $pubapi->jsonapi_suspendacct( $user, $reason ); =head2 C<jsonapi_unsuspendacct()> Unsuspend an account. Syntax: $pubapi->jsonapi_unsuspendacct( $user ); =head2 C<jsonapi_listsuspended()> List the suspended accounts on a server. Syntax: $pubapi->jsonapi_listsuspended( ); =head2 C<jsonapi_addpkg()> Add a new package. Syntax: $pubapi->jsonapi_addpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); =head2 C<jsonapi_killpkg()> Remove a package. Syntax: $pubapi->jsonapi_killpkg( $pkg ); =head2 C<jsonapi_editpkg()> Edit a package. Syntax: $pubapi->jsonapi_editpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); =head2 C<jsonapi_setacls()> Change features available to a reseller. Syntax: $pubapi->jsonapi_setacls( $reseller, $acllist ); =head2 C<jsonapi_terminatereseller()> Remove a reseller. Syntax: $pubapi->jsonapi_terminatereseller( $reseller, $verify ); =head2 C<jsonapi_resellerstats()> Get statistics on a specific reseller. Syntax: $pubapi->jsonapi_resellerstats( $reseller ); =head2 C<jsonapi_setupreseller()> Make a cPanel account a Reseller account. Syntax: $pubapi->jsonapi_setupreseller( $user, $makeowner ); =head2 C<jsonapi_lookupnsip()> Get the IP for a nameserver. Syntax: $pubapi->jsonapi_lookupnsip( $nameserver ); =head2 C<jsonapi_listresellers()> List all the resellers on a system. Syntax: $pubapi->jsonapi_listresellers( ); =head2 C<jsonapi_listacls()> List all of the ACL lists available. Syntax: $pubapi->jsonapi_listacls( ); =head2 C<jsonapi_saveacllist()> Save a new ACL list. Syntax: $pubapi->jsonapi_saveacllist( $acllist ); =head2 C<jsonapi_unsetupreseller()> Remove reseller permissions from an account. Syntax: $pubapi->jsonapi_unsetupreseller( $user ); =head2 C<jsonapi_gethostname()> Get the hostname of the server currently being queried. Syntax: $pubapi->jsonapi_gethostname( ); =head2 C<jsonapi_fetchsslinfo()> Get information on a specific SSL certificate. Syntax: $pubapi->jsonapi_fetchsslinfo( $domain, $crtdata ); =head2 C<jsonapi_installssl()> Install a new SSL certificate. Syntax: $pubapi->jsonapi_installssl( $domain, $user, $cert, $key, $cab, $ip ); =head2 C<jsonapi_passwd()> Change an account's password. Syntax: $pubapi->jsonapi_passwd( $user, $pass ); =head2 C<jsonapi_getlanglist()> Get a list of languages available on a system. Syntax: $pubapi->jsonapi_getlanglist( ); =head2 C<jsonapi_reboot()> Reboot the server. Syntax: $pubapi->jsonapi_reboot( $force ); =head2 C<jsonapi_accountsummary_user()> Get a summary of an account. Syntax: $pubapi->jsonapi_accountsummary_user( $user ); =head2 C<jsonapi_accountsummary_domain()> Get the summary of an account by specifying the domain. Syntax: $pubapi->jsonapi_accountsummary_domain( $domain ); =head2 C<jsonapi_loadavg()> Get the loadavg on the system. Syntax: $pubapi->jsonapi_loadavg( ); =head2 C<jsonapi_restartservice()> Restart a service. Syntax: $pubapi->jsonapi_restartservice( $service ); =head2 C<jsonapi_setsiteip_user()> Set the IP for a specific user. Syntax: $pubapi->jsonapi_setsiteip_user( $user, $ip ); =head2 C<jsonapi_setsiteip_domain()> Set the IP for a specific domain. Syntax: $pubapi->jsonapi_setsiteip_domain( $domain, $ip ); =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �['�n.�, �, # lib/cPanel/PublicAPI/WHM/XMLAPI.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM::API - Legacy interface for querying the xml-api. NOTE: This module is provided for legacy purposes, L<cPanel::PublicAPI> should be used instead =head1 DESCRIPTION This module provides legacy compatibility support between L<cPanel::PublicAPI> and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). Every method contained within this object can be queried using cPanel::publicAPI::whm_api() instead. For more information on the calls within the methods contained here and what the parameter names mean, please read the documentation at: L<http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi> =head1 functions =head2 C<xmlapi_listaccts()> Used to list the accounts on a server. Syntax: $pubapi->xmlapi_listaccts( $search, $searchtype ); =head2 C<xmlapi_createacct()> Create a new cPanel account. Syntax: $pubapi->xmlapi_createacct( $username, $domain, $password, $plan ); =head2 C<xmlapi_removeacct()> Terminate an account. Syntax: $pubapi->xmlapi_removeacct( $user ); =head2 C<xmlapi_showversion()> Get the version of cPanel running on the server. Syntax: $pubapi->xmlapi_showversion( ); =head2 C<xmlapi_version()> Get the version of cPanel running on the server (as as showversion) Syntax: $pubapi->xmlapi_version( ); =head2 C<xmlapi_applist()> List out the available xml-api calls. Syntax: $pubapi->xmlapi_applist( ); =head2 C<xmlapi_generatessl()> Generate an ssl certificate. Syntax: $pubapi->xmlapi_generatessl( $host, $pass, $country, $state, $city, $co, $cod, $email, $xemail ); =head2 C<xmlapi_generatessl_noemail()> Generate an SSL certificate without an email. Syntax: $pubapi->xmlapi_generatessl_noemail( $noemail=1 ); =head2 C<xmlapi_listcrts()> List out the certificates that exist on the server. Syntax: $pubapi->xmlapi_listcrts( ); =head2 C<xmlapi_setresellerlimits()> Set the limits for a single reseller account. Syntax: $pubapi->xmlapi_setresellerlimits( ); =head2 C<xmlapi_setresellerpackagelimit()> Set which packages a reseller account can use. Syntax: $pubapi->xmlapi_setresellerpackagelimit( $user, $package, $allowerd, $number, $no_limit ); =head2 C<xmlapi_setresellermainip()> Set a reseller's main IP. Syntax: $pubapi->xmlapi_setresellermainip( $user, $ip ); =head2 C<xmlapi_setresellerips()> Set the IP that a reseller has available to it. Syntax: $pubapi->xmlapi_setresellerips( $user, $delegate, $ips ); =head2 C<xmlapi_setresellernameservers()> Set the nameservers that a reseller uses by default. Syntax: $pubapi->xmlapi_setresellernameservers( $user, $nameservers ); =head2 C<xmlapi_suspendreseller()> Suspend a reseller and all of their accounts. Syntax: $pubapi->xmlapi_suspendreseller( $user, $reason, $disallow ); =head2 C<xmlapi_unsuspendreseller()> Unsuspend a reseller and all of their accounts. Syntax: $pubapi->xmlapi_unsuspendreseller( $user ); =head2 C<xmlapi_addzonerecord()> Add a record to a zone. Syntax: $pubapi->xmlapi_addzonerecord( @args ); =head2 C<xmlapi_editzonerecord()> Edit a zone record. Syntax: $pubapi->xmlapi_editzonerecord(@args ); =head2 C<xmlapi_removezonerecord()> Remove a line from a zone. Syntax: $pubapi->xmlapi_removezonerecord( $domain, $Line ); =head2 C<xmlapi_getzonerecord()> Get a record from a zone. Syntax: $pubapi->xmlapi_getzonerecord( $domain, $Line ); =head2 C<xmlapi_servicestatus()> Get the status of various services running on a system. Syntax: $pubapi->xmlapi_servicestatus( $service ); =head2 C<xmlapi_configureservice()> Enable/Disable various services. Syntax: $pubapi->xmlapi_configureservice( $service, $enabled, $monitored ); =head2 C<xmlapi_acctcounts()> Get the number of accounts on a system/that belong to a reseller. Syntax: $pubapi->xmlapi_acctcounts( $user ); =head2 C<xmlapi_domainuserdata()> Get the information about a specific domain's virtualhost. Syntax: $pubapi->xmlapi_domainuserdata( $domain ); =head2 C<xmlapi_editquota()> Edit a user's quota. Syntax: $pubapi->xmlapi_editquota( $user, $quota ); =head2 C<xmlapi_nvget()> Get non-volatile data. Syntax: $pubapi->xmlapi_nvget( $key ); =head2 C<xmlapi_nvset()> Set non-volatile data. Syntax: $pubapi->xmlapi_nvset( $key, $value ); =head2 C<xmlapi_myprivs()> See what privileges are available to your user. Syntax: $pubapi->xmlapi_myprivs( ); =head2 C<xmlapi_listzones()> List all the zones available to a user. Syntax: $pubapi->xmlapi_listzones( ); =head2 C<xmlapi_sethostname()> Set the hostname of a system. Syntax: $pubapi->xmlapi_sethostname( $hostname ); =head2 C<xmlapi_setresolvers()> Set the resolvers a system uses. Syntax: $pubapi->xmlapi_setresolvers( $nameserver1, $nameserver2, $nameserver3 ); =head2 C<xmlapi_addip()> Add a new IP to a server. Syntax: $pubapi->xmlapi_addip( $ip, $netmask ); =head2 C<xmlapi_delip()> Remove an IP from a server. Syntax: $pubapi->xmlapi_delip( $ip, $ethernetdev, $skipifshutdown ); =head2 C<xmlapi_listips()> List the IPs on a server. Syntax: $pubapi->xmlapi_listips( ); =head2 C<xmlapi_dumpzone()> Get the contents of a zone file. Syntax: $pubapi->xmlapi_dumpzone( $domain ); =head2 C<xmlapi_listpkgs()> List the packages available to your user. Syntax: $pubapi->xmlapi_listpkgs( ); =head2 C<xmlapi_limitbw()> Limit the amount of bandwidth available to an account. Syntax: $pubapi->xmlapi_limitbw( $user, $bwlimit ); =head2 C<xmlapi_showbw()> Show the amount of BW used by an account. Syntax: $pubapi->xmlapi_showbw( $month, $year, $showres, $search, $searchtype ); =head2 C<xmlapi_killdns()> Remove a DNS zone. Syntax: $pubapi->xmlapi_killdns( $domain ); =head2 C<xmlapi_adddns()> Add a dns zone. Syntax: $pubapi->xmlapi_adddns( $domain, $ip, $trueowner ); =head2 C<xmlapi_changepackage()> Change an Account's Package. Syntax: $pubapi->xmlapi_changepackage( $user, $pkg ); =head2 C<xmlapi_modifyacct()> Modify an Account's limits. Syntax: $pubapi->xmlapi_modifyacct( $user, $domain, $HASCGI, $CPTHEME, $LANG, $MAXPOP, $MAXFTP, $MAXLST, $MAXSUB, $MAXPARK, $MAXADDON, $MAXSQL, $shell ); =head2 C<xmlapi_suspendacct()> Suspend an account. Syntax: $pubapi->xmlapi_suspendacct( $user, $reason ); =head2 C<xmlapi_unsuspendacct()> Unsuspend an account. Syntax: $pubapi->xmlapi_unsuspendacct( $user ); =head2 C<xmlapi_listsuspended()> List the suspended accounts on a server. Syntax: $pubapi->xmlapi_listsuspended( ); =head2 C<xmlapi_addpkg()> Add a new package. Syntax: $pubapi->xmlapi_addpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); =head2 C<xmlapi_killpkg()> Remove a package. Syntax: $pubapi->xmlapi_killpkg( $pkg ); =head2 C<xmlapi_editpkg()> Edit a package. Syntax: $pubapi->xmlapi_editpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); =head2 C<xmlapi_setacls()> Change features available to a reseller. Syntax: $pubapi->xmlapi_setacls( $reseller, $acllist ); =head2 C<xmlapi_terminatereseller()> Remove a reseller. Syntax: $pubapi->xmlapi_terminatereseller( $reseller, $verify ); =head2 C<xmlapi_resellerstats()> Get statistics on a specific reseller. Syntax: $pubapi->xmlapi_resellerstats( $reseller ); =head2 C<xmlapi_setupreseller()> Make a cPanel account a Reseller account. Syntax: $pubapi->xmlapi_setupreseller( $user, $makeowner ); =head2 C<xmlapi_lookupnsip()> Get the IP for a nameserver. Syntax: $pubapi->xmlapi_lookupnsip( $nameserver ); =head2 C<xmlapi_listresellers()> List all the resellers on a system. Syntax: $pubapi->xmlapi_listresellers( ); =head2 C<xmlapi_listacls()> List all of the ACL lists available. Syntax: $pubapi->xmlapi_listacls( ); =head2 C<xmlapi_saveacllist()> Save a new ACL list. Syntax: $pubapi->xmlapi_saveacllist( $acllist ); =head2 C<xmlapi_unsetupreseller()> Remove reseller permissions from an account. Syntax: $pubapi->xmlapi_unsetupreseller( $user ); =head2 C<xmlapi_gethostname()> Get the hostname of the server currently being queried. Syntax: $pubapi->xmlapi_gethostname( ); =head2 C<xmlapi_fetchsslinfo()> Get information on a specific SSL certificate. Syntax: $pubapi->xmlapi_fetchsslinfo( $domain, $crtdata ); =head2 C<xmlapi_installssl()> Install a new SSL certificate. Syntax: $pubapi->xmlapi_installssl( $domain, $user, $cert, $key, $cab, $ip ); =head2 C<xmlapi_passwd()> Change an account's password. Syntax: $pubapi->xmlapi_passwd( $user, $pass ); =head2 C<xmlapi_getlanglist()> Get a list of languages available on a system. Syntax: $pubapi->xmlapi_getlanglist( ); =head2 C<xmlapi_reboot()> Reboot the server. Syntax: $pubapi->xmlapi_reboot( $force ); =head2 C<xmlapi_accountsummary_user()> Get a summary of an account. Syntax: $pubapi->xmlapi_accountsummary_user( $user ); =head2 C<xmlapi_accountsummary_domain()> Get the summary of an account by specifying the domain. Syntax: $pubapi->xmlapi_accountsummary_domain( $domain ); =head2 C<xmlapi_loadavg()> Get the loadavg on the system. Syntax: $pubapi->xmlapi_loadavg( ); =head2 C<xmlapi_restartservice()> Restart a service. Syntax: $pubapi->xmlapi_restartservice( $service ); =head2 C<xmlapi_setsiteip_user()> Set the IP for a specific user. Syntax: $pubapi->xmlapi_setsiteip_user( $user, $ip ); =head2 C<xmlapi_setsiteip_domain()> Set the IP for a specific domain. Syntax: $pubapi->xmlapi_setsiteip_domain( $domain, $ip ); =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[p�V*> > # lib/cPanel/PublicAPI/WHM/Legacy.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM::Legacy - A module for handling Cpanel::Accounting backward compatibility within the cPanel::PublicAPI framework. =head1 DESCRIPTION This module should never be used, please use cPanel::PublicAPI-E<gt>whm_api() instead. =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[DoD� � " lib/cPanel/PublicAPI/WHM/Legacy.pmnu ��6�$ package cPanel::PublicAPI::Legacy; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = '2.3'; package cPanel::PublicAPI; use cPanel::PublicAPI::WHM (); sub _modpkg { my $self = shift; my $op = shift; my $count = 0; my @OPTS = ('nohtml=1'); if ( $op eq 'edit' ) { push @OPTS, 'edit=yes'; } return $self->simple_get_whmreq( '/scripts/addpkg', \@_, [ 'name', 'hasshell', 'bwlimit', 'quota', 'ip', 'cgi', 'cpmod', 'maxftp', 'maxsql', 'maxpop', 'maxlst', 'maxsub', 'maxpark', 'maxaddon', 'featurelist', 'language' ], \@OPTS ); } sub addpkg { my $self = shift; return $self->_modpkg( 'add', @_ ); } sub editpkg { my $self = shift; return $self->_modpkg( 'edit', @_ ); } sub killpkg { my $self = shift; return $self->simple_get_whmreq( '/scripts/killpkg', \@_, ['pkg'], ['nohtml=1'] ); } sub suspend { my $self = shift; return $self->simple_get_whmreq( '/scripts/remote_suspend', \@_, ['user'] ); } sub unsuspend { my $self = shift; return $self->simple_get_whmreq( '/scripts/remote_unsuspend', \@_, ['user'] ); } sub killacct { my $self = shift; return $self->simple_get_whmreq( '/scripts/killacct', \@_, ['user'], ['nohtml=1'] ); } sub showversion { my $self = shift; return $self->simple_get_whmreq( '/scripts2/showversion', \@_ ); } sub version { my $self = shift; return $self->simple_get_whmreq( '/scripts2/showversion', \@_ ); } sub showhostname { my $self = shift; return $self->simple_get_whmreq( '/scripts2/gethostname', \@_ ); } sub createacct { my $self = shift; return $self->simple_get_whmreq( '/scripts/wwwacct', \@_, [ 'domain', 'username', 'password', 'plan', 'language' ], ['nohtml=1'] ); } sub listpkgs { my $self = shift; my $req = $self->simple_get_whmreq( '/scripts/remote_listpkg', \@_ ); my %PKGS; foreach ( split( /\n/, $req ) ) { my ( $pkg, $contents ) = split( /=/, $_ ); my @CONTENTS = split( /\,/, $contents ); $PKGS{$pkg} = \@CONTENTS; } return wantarray ? %PKGS : \%PKGS; } sub listaccts { my $self = shift; my $req = $self->simple_get_whmreq( '/scripts2/listaccts', \@_, [], ['nohtml=1&viewall=1'] ); my %ACCTS; foreach ( split( /\n/, $req ) ) { next if $_ !~ /=/; my ( $acct, $contents ) = split( /=/, $_ ); my @CONTENTS = split( /\,/, $contents ); $ACCTS{$acct} = \@CONTENTS; } return wantarray ? %ACCTS : \%ACCTS; } 1; PK � �[�Mq # lib/cPanel/PublicAPI/WHM/JSONAPI.pmnu ��6�$ package cPanel::PublicAPI::JSONAPI; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = '2.3'; package cPanel::PublicAPI; use cPanel::PublicAPI::WHM::API (); foreach my $sub ( grep ( /^api_/, keys %cPanel::PublicAPI:: ) ) { *{"json$sub"} = *$sub; } 1; PK � �[���� lib/cPanel/PublicAPI/WHM/DNS.pmnu ��6�$ package cPanel::PublicAPI::DNS; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = '2.3'; package cPanel::PublicAPI; use cPanel::PublicAPI::WHM (); use cPanel::PublicAPI::Utils (); sub addtocluster { my $self = shift; my $page = $self->simple_post_whmreq( '/cgi/trustclustermaster.cgi', \@_, [ 'user', 'clustermaster', 'pass', 'version' ], ['recurse=0'] ); if ( $page =~ /has been established/i ) { return 1; } return; } sub getzone_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/getzone_local', \@_, [ 'zone', 'dnsuniqid' ] ); } sub getzones_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/getzones_local', \@_, [ 'zones', 'dnsuniqid' ] ); } sub getallzones_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/getallzones_local', \@_, ['dnsuniqid'] ); } sub cleandns_local { my $self = shift; return $self->simple_get_whmreq( '/scripts2/cleandns_local', \@_, ['dnsuniqid'] ); } sub getips_local { my $self = shift; return cPanel::PublicAPI::Utils::get_string_with_collapsed_trailing_eols( split( /\n/, ( $self->simple_get_whmreq( '/scripts2/getips_local', \@_, ['dnsuniqid'] ) ) ) ); } sub getpath_local { my $self = shift; return cPanel::PublicAPI::Utils::get_string_with_collapsed_trailing_eols( split( /\n/, ( $self->simple_get_whmreq( '/scripts2/getpath_local', \@_, ['dnsuniqid'] ) ) ) ); } sub removezone_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/removezone_local', \@_, [ 'zone', 'dnsuniqid' ] ); } sub removezones_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/removezones_local', \@_, [ 'zones', 'dnsuniqid' ] ); } sub reloadzones_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/reloadzones_local', \@_, [ 'dnsuniqid', 'zone' ] ); # backcompat } sub reloadbind_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/reloadbind_local', \@_, [ 'dnsuniqid', 'zone' ] ); # backcompat } sub reconfigbind_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/reconfigbind_local', \@_, [ 'dnsuniqid', 'zone' ] ); # backcompat } sub quickzoneadd_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/quickzoneadd_local', \@_, [ 'zone', 'zonedata', 'dnsuniqid' ] ); } sub savezone_local { my $self = shift; return $self->simple_post_whmreq( '/scripts2/savezone_local', \@_, [ 'zone', 'zonedata', 'dnsuniqid' ] ); } sub synczones_local { my ( $self, $formdata, $dnsuniqid ) = @_; cPanel::PublicAPI::_init() if !exists $cPanel::PublicAPI::CFG{'init'}; $formdata =~ s/\&$//g; # formdata must come pre encoded. $formdata .= '&dnsuniqid=' . $cPanel::PublicAPI::CFG{'uri_encoder_func'}->($dnsuniqid); my $page = join( "\n", $self->whmreq( '/scripts2/synczones_local', 'POST', $formdata ) ); return if $self->{'error'}; return $page; } sub addzoneconf_local { my $self = shift; return $self->simple_get_whmreq( '/scripts2/addzoneconf_local', \@_, [ 'zone', 'dnsuniqid' ] ); } sub getzonelist_local { my $self = shift; return split( /\n/, $self->simple_get_whmreq( '/scripts2/getzonelist_local', \@_, ['dnsuniqid'] ) ); } sub zoneexists_local { my $self = shift; my $exists = cPanel::PublicAPI::Utils::remove_trailing_newline( $self->simple_post_whmreq( '/scripts2/zoneexists_local', \@_, [ 'zone', 'dnsuniqid' ] ) ); $exists =~ s/[\r\n]//g; if ( $exists eq '1' ) { return 1; } return 0; } PK � �[�E� � " lib/cPanel/PublicAPI/WHM/XMLAPI.pmnu ��6�$ package cPanel::PublicAPI::XMLAPI; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = '2.3'; package cPanel::PublicAPI; use cPanel::PublicAPI::WHM::API (); foreach my $sub ( grep ( /^api_/, keys %cPanel::PublicAPI:: ) ) { *{"xml$sub"} = *$sub; } 1; PK � �[!�ϣ lib/cPanel/PublicAPI/WHM/DNS.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM::DNS - A module for interacting with WHM's DNS clustering system. =head1 DESCRIPTION This module is intended as a client for querying WHM's DNS clustering system. Unless you are specifically looking to write your own interaction with cPanel's DNS system, you should never need to use this module, rather the DNS functions within cPanel's XML-API should do what you are looking for: L<http://docs.cpanel.net/twiki/bin/vief/AllDocumentation/AutomationIntegration/XmlApi#DNS%20functions> =head1 functions The functions contained within this module share a similiar naming scheme for the variables used within, please consult the list below when figuring out what each function does. =over =item * $zone - The name of the domain to be used. =item * $dnsuniqid - A Unique string used to identify uniquely (suggested: 32 character alphanumeric) =item * $zones - A pipe seperated list of domains. =item * $zonedata - The contents of a zone file, usually used for sending changes of a zone to another system. =back =head2 C<addtocluster()> Add a machine to a DNS cluster. Call specific parameters: =over =item * $clustermaster - The IP of the machine being added to the cluster. =item * $user - The user to authenticate DNS requests as. =item * $pass - The accesshash or API token to authenticate DNS requests with =item * $version - The version of cPanel/WHM of the machine being added to the cluster =back Syntax: $pubapi->addtocluster( $user, $clustermaster, $accesshash, $version ) =head2 C<getzone_local()> Get the contents of a zone file. Syntax: $pubapi->getzone_local( $zone, $dnsuniqid ) =head2 C<getzones_local()> Get the contents of multiple zone files, this will be split up as: cpdnszone-%URI ENCODED ZONENAME%=%URI encoded version of zone file%&cpdnszone... for each zone in the response Syntax: $pubapi->getzones_local( $zones, $dnsuniqid ) =head2 C<getallzones_local()> Like getzones_local, but will return all zones in a cluster. Syntax: $pubapi->getallzones_local( $dnsuniqid ) =head2 C<cleandns_local()> Clean up any old or unused DNS zones from named.conf. Syntax: $pubapi->cleandns_local( $dnsuniqid ) =head2 C<getips_local()> Get a list of extra IPs available on a system, response will be formated as: $ip:$netmask:$broadcast Syntax: $pubapi->getips_local( $dnsuniqid ) =head2 C<getpath_local()> Returns a newline separated list containing all the machines that this machine is clustered with in the following format: $hostname $remote_host Syntax: $pubapi->getpath_local( $dnsuniqid ) =head2 C<removezone_local()> Remove a DNS zone. Syntax: $pubapi->removezone_local( $zone, $dnsuniqid ) =head2 C<removezones_local()> Remove multiple DNS zones. Syntax: $pubapi->removezones_local( $zones, $dnsuniqid ) =head2 C<reloadzones_local()> Force bind to re-read zones files via the "rndc reload" command. Syntax: $pubapi->reloadzones_local( $dnsuniqid, $zones ) =head2 C<reloadbind_local()> Run the 'rndc reload' command. If no zones are specified, bind will reload everything. Syntax: $pubapi->reloadbind_local( $dnsuniqid, $zone ) =head2 C<reconfigbind_local()> Run the 'rndc reconfig' command. Syntax: $pubapi->reconfigbind_local( $dnsuniqid, $zone ) =head2 C<quickzoneadd_local()> Add a new zone to a system. Syntax: $pubapi->quickzoneadd_local( $zone, $zonedata, $dnsuniqid ) =head2 C<savezone_local()> Update a zone file with the data specified in $zonedata. Syntax: $pubapi->savezone_local( $zone, $zonedata, $dnsuniqid ) =head2 C<synczones_local()> Send a dump of all zones and update zones when required. The zones are sent within the $formdata in the following format: cpdnszone-%URI ENCODED ZONENAME%=%URI encoded version of zone file%&cpdnszone... Syntax: $pubapi->synczones_local( $formdata, $dnsuniqid ) =head2 C<addzoneconf_local()> Add a zone to the named.conf file. Syntax: $pubapi->addzoneconf_local( $zone, $dnsuniqid ) =head2 C<getzonelist_local()> Get a newline seperated list of the zones on a system. Syntax: $pubapi->getzonelist_local( $dnsuniqid ) =head2 C<zoneexists_local()> Return boolean value indicating whether a zone exists on a remote system or not. Syntax: $pubapi->zoneexists_local( $zone, $dnsuniqid ) =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[dM 2w w ) lib/cPanel/PublicAPI/WHM/CachedVersion.pmnu ��6�$ package cPanel::PublicAPI::WHM::CachedVersion; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = '2.3'; package cPanel::PublicAPI; use cPanel::PublicAPI::WHM::Legacy (); our $basedir = '/var/cpanel/accounting'; our $cachedir = '/var/cpanel/accounting/cache'; our $cachettl = 3600; #one hour sub check_dirs { foreach my $dir ( $basedir, $cachedir ) { if ( !-e $dir ) { mkdir( $dir, 0700 ); } } } sub cached_version { my $self = shift; my $ttl = shift || $cachettl; my $version; $self->check_dirs(); my $file = ( $self->{'ip'} || $self->{'host'} ); if ( !$file ) { return; } $file =~ s/\///g; my $fullfile = $cachedir . '/' . $file; my $now = time(); my $mtime = ( stat($fullfile) )[9]; if ( $mtime && ( $mtime + $ttl ) > $now && $mtime < $now ) { if ( open( my $cache_fh, '<', $fullfile ) ) { my $fileversion = readline($cache_fh); if ( $fileversion =~ /^(\d+\.\d+\.\d+)/ ) { $version = $1; } close($cache_fh); } } if ($version) { return $version; } $version = $self->version(); if ($version) { if ( open( my $cache_fh, '>', $fullfile ) ) { print {$cache_fh} $version; close($cache_fh); } } return $version; } 1; PK � �[撺2+ 2+ lib/cPanel/PublicAPI/WHM/API.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::WHM::API - Legacy interface for querying the xml-api. NOTE: This module is provided for legacy purposes, L<cPanel::PublicAPI> should be used instead =head1 DESCRIPTION This module provides legacy compatibility support between L<cPanel::PublicAPI> and Cpanel::Accounting (distributed with cPanel). This should never be used unless there is a very good reason to use it (such as having a script that uses Cpanel::Accounting). Every method contained within this object can be queried using cPanel::publicAPI::whm_api() instead. For more information on the calls within the methods contained here and what the parameter names mean, please read the documentation at: L<http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi> =head1 functions =head2 C<api_listaccts()> Used to list the accounts on a server. Syntax: $pubapi->api_listaccts( $search, $searchtype ); =head2 C<api_createacct()> Create a new cPanel account. Syntax: $pubapi->api_createacct( $username, $domain, $password, $plan ); =head2 C<api_removeacct()> Terminate an account. Syntax: $pubapi->api_removeacct( $user ); =head2 C<api_showversion()> Get the version of cPanel running on the server. Syntax: $pubapi->api_showversion( ); =head2 C<api_version()> Get the version of cPanel running on the server (as as showversion) Syntax: $pubapi->api_version( ); =head2 C<api_applist()> List out the available xml-api calls. Syntax: $pubapi->api_applist( ); =head2 C<api_generatessl()> Generate an ssl certificate. Syntax: $pubapi->api_generatessl( $host, $pass, $country, $state, $city, $co, $cod, $email, $xemail ); =head2 C<api_generatessl_noemail()> Generate an SSL certificate without an email. Syntax: $pubapi->api_generatessl_noemail( $noemail=1 ); =head2 C<api_listcrts()> List out the certificates that exist on the server. Syntax: $pubapi->api_listcrts( ); =head2 C<api_setresellerlimits()> Set the limits for a single reseller account. Syntax: $pubapi->api_setresellerlimits( ); =head2 C<api_setresellerpackagelimit()> Set which packages a reseller account can use. Syntax: $pubapi->api_setresellerpackagelimit( $user, $package, $allowerd, $number, $no_limit ); =head2 C<api_setresellermainip()> Set a reseller's main IP. Syntax: $pubapi->api_setresellermainip( $user, $ip ); =head2 C<api_setresellerips()> Set the IP that a reseller has available to it. Syntax: $pubapi->api_setresellerips( $user, $delegate, $ips ); =head2 C<api_setresellernameservers()> Set the nameservers that a reseller uses by default. Syntax: $pubapi->api_setresellernameservers( $user, $nameservers ); =head2 C<api_suspendreseller()> Suspend a reseller and all of their accounts. Syntax: $pubapi->api_suspendreseller( $user, $reason, $disallow ); =head2 C<api_unsuspendreseller()> Unsuspend a reseller and all of their accounts. Syntax: $pubapi->api_unsuspendreseller( $user ); =head2 C<api_addzonerecord()> Add a record to a zone. Syntax: $pubapi->api_addzonerecord( @args ); =head2 C<api_editzonerecord()> Edit a zone record. Syntax: $pubapi->api_editzonerecord(@args ); =head2 C<api_removezonerecord()> Remove a line from a zone. Syntax: $pubapi->api_removezonerecord( $domain, $Line ); =head2 C<api_getzonerecord()> Get a record from a zone. Syntax: $pubapi->api_getzonerecord( $domain, $Line ); =head2 C<api_servicestatus()> Get the status of various services running on a system. Syntax: $pubapi->api_servicestatus( $service ); =head2 C<api_configureservice()> Enable/Disable various services. Syntax: $pubapi->api_configureservice( $service, $enabled, $monitored ); =head2 C<api_acctcounts()> Get the number of accounts on a system/that belong to a reseller. Syntax: $pubapi->api_acctcounts( $user ); =head2 C<api_domainuserdata()> Get the information about a specific domain's virtualhost. Syntax: $pubapi->api_domainuserdata( $domain ); =head2 C<api_editquota()> Edit a user's quota. Syntax: $pubapi->api_editquota( $user, $quota ); =head2 C<api_nvget()> Get non-volatile data. Syntax: $pubapi->api_nvget( $key ); =head2 C<api_nvset()> Set non-volatile data. Syntax: $pubapi->api_nvset( $key, $value ); =head2 C<api_myprivs()> See what privileges are available to your user. Syntax: $pubapi->api_myprivs( ); =head2 C<api_listzones()> List all the zones available to a user. Syntax: $pubapi->api_listzones( ); =head2 C<api_sethostname()> Set the hostname of a system. Syntax: $pubapi->api_sethostname( $hostname ); =head2 C<api_setresolvers()> Set the resolvers a system uses. Syntax: $pubapi->api_setresolvers( $nameserver1, $nameserver2, $nameserver3 ); =head2 C<api_addip()> Add a new IP to a server. Syntax: $pubapi->api_addip( $ip, $netmask ); =head2 C<api_delip()> Remove an IP from a server. Syntax: $pubapi->api_delip( $ip, $ethernetdev, $skipifshutdown ); =head2 C<api_listips()> List the IPs on a server. Syntax: $pubapi->api_listips( ); =head2 C<api_dumpzone()> Get the contents of a zone file. Syntax: $pubapi->api_dumpzone( $domain ); =head2 C<api_listpkgs()> List the packages available to your user. Syntax: $pubapi->api_listpkgs( ); =head2 C<api_limitbw()> Limit the amount of bandwidth available to an account. Syntax: $pubapi->api_limitbw( $user, $bwlimit ); =head2 C<api_showbw()> Show the amount of BW used by an account. Syntax: $pubapi->api_showbw( $month, $year, $showres, $search, $searchtype ); =head2 C<api_killdns()> Remove a DNS zone. Syntax: $pubapi->api_killdns( $domain ); =head2 C<api_adddns()> Add a dns zone. Syntax: $pubapi->api_adddns( $domain, $ip, $trueowner ); =head2 C<api_changepackage()> Change an Account's Package. Syntax: $pubapi->api_changepackage( $user, $pkg ); =head2 C<api_modifyacct()> Modify an Account's limits. Syntax: $pubapi->api_modifyacct( $user, $domain, $HASCGI, $CPTHEME, $LANG, $MAXPOP, $MAXFTP, $MAXLST, $MAXSUB, $MAXPARK, $MAXADDON, $MAXSQL, $shell ); =head2 C<api_suspendacct()> Suspend an account. Syntax: $pubapi->api_suspendacct( $user, $reason ); =head2 C<api_unsuspendacct()> Unsuspend an account. Syntax: $pubapi->api_unsuspendacct( $user ); =head2 C<api_listsuspended()> List the suspended accounts on a server. Syntax: $pubapi->api_listsuspended( ); =head2 C<api_addpkg()> Add a new package. Syntax: $pubapi->api_addpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); =head2 C<api_killpkg()> Remove a package. Syntax: $pubapi->api_killpkg( $pkg ); =head2 C<api_editpkg()> Edit a package. Syntax: $pubapi->api_editpkg( $pkgname, $quota, $ip, $cgi, $frontpage, $cpmod, $maxftp, $maxsql, $maxpop, $maxlst, $maxsub, $maxpark, $maxaddon, $featurelist, $hasshell, $bwlimit ); =head2 C<api_setacls()> Change features available to a reseller. Syntax: $pubapi->api_setacls( $reseller, $acllist ); =head2 C<api_terminatereseller()> Remove a reseller. Syntax: $pubapi->api_terminatereseller( $reseller, $verify ); =head2 C<api_resellerstats()> Get statistics on a specific reseller. Syntax: $pubapi->api_resellerstats( $reseller ); =head2 C<api_setupreseller()> Make a cPanel account a Reseller account. Syntax: $pubapi->api_setupreseller( $user, $makeowner ); =head2 C<api_lookupnsip()> Get the IP for a nameserver. Syntax: $pubapi->api_lookupnsip( $nameserver ); =head2 C<api_listresellers()> List all the resellers on a system. Syntax: $pubapi->api_listresellers( ); =head2 C<api_listacls()> List all of the ACL lists available. Syntax: $pubapi->api_listacls( ); =head2 C<api_saveacllist()> Save a new ACL list. Syntax: $pubapi->api_saveacllist( $acllist ); =head2 C<api_unsetupreseller()> Remove reseller permissions from an account. Syntax: $pubapi->api_unsetupreseller( $user ); =head2 C<api_gethostname()> Get the hostname of the server currently being queried. Syntax: $pubapi->api_gethostname( ); =head2 C<api_fetchsslinfo()> Get information on a specific SSL certificate. Syntax: $pubapi->api_fetchsslinfo( $domain, $crtdata ); =head2 C<api_installssl()> Install a new SSL certificate. Syntax: $pubapi->api_installssl( $domain, $user, $cert, $key, $cab, $ip ); =head2 C<api_passwd()> Change an account's password. Syntax: $pubapi->api_passwd( $user, $pass ); =head2 C<api_getlanglist()> Get a list of languages available on a system. Syntax: $pubapi->api_getlanglist( ); =head2 C<api_reboot()> Reboot the server. Syntax: $pubapi->api_reboot( $force ); =head2 C<api_accountsummary_user()> Get a summary of an account. Syntax: $pubapi->api_accountsummary_user( $user ); =head2 C<api_accountsummary_domain()> Get the summary of an account by specifying the domain. Syntax: $pubapi->api_accountsummary_domain( $domain ); =head2 C<api_loadavg()> Get the loadavg on the system. Syntax: $pubapi->api_loadavg( ); =head2 C<api_restartservice()> Restart a service. Syntax: $pubapi->api_restartservice( $service ); =head2 C<api_setsiteip_user()> Set the IP for a specific user. Syntax: $pubapi->api_setsiteip_user( $user, $ip ); =head2 C<api_setsiteip_domain()> Set the IP for a specific domain. Syntax: $pubapi->api_setsiteip_domain( $domain, $ip ); =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[�7ߘ� � lib/cPanel/PublicAPI/Utils.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI::Utils - Provides some internally used utility functions for cPanel::PublicAPI, should never be used externally. =head1 Subroutines =head2 remove_trailing_newline() Removes the training newline from the provided string =head2 get_string_with_collapsed_trailing_eols Takes an array or array of arrays and puts them into a newline-seperated string. =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[X�F�# # lib/cPanel/PublicAPI/WHM.pmnu ��6�$ package cPanel::PublicAPI::WHM; # Copyright (c) 2015, cPanel, Inc. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. use cPanel::PublicAPI (); our $VERSION = 1.0; package cPanel::PublicAPI; sub simple_get_whmreq { my ( $self, $uri, $argref, $argnameref, $opts ) = @_; $self->_init() if !exists $cPanel::PublicAPI::CFG{'init'}; $self->debug("simple_get_whmreq: ( $self, $uri, $argref, $argnameref, $opts )\n") if $self->{'debug'}; my $count = 0; if ( !$opts || !ref $opts ) { $opts = []; } if ( ref $argnameref ) { foreach my $arg ( @{$argnameref} ) { push @{$opts}, $cPanel::PublicAPI::CFG{'uri_encoder_func'}->($arg) . '=' . ( $cPanel::PublicAPI::CFG{'uri_encoder_func'}->( $argref->[$count] ) || '' ); $count++; } } my $page_ref = $self->whmreq( $uri . '?' . join( '&', @{$opts} ) ); if ( $self->{'error'} ) { return ''; } return $page_ref; } sub simple_post_whmreq { my ( $self, $uri, $argref, $argnameref, $opts ) = @_; $self->_init() if !exists $cPanel::PublicAPI::CFG{'init'}; $self->debug("simple_post_whmreq: ( $self, $uri, $argref, $argnameref, $opts )") if $self->{'debug'}; my $count = 0; if ( !$opts || !ref $opts ) { $opts = []; } if ( ref $argnameref ) { foreach my $arg ( @{$argnameref} ) { push @{$opts}, $cPanel::PublicAPI::CFG{'uri_encoder_func'}->($arg) . '=' . $cPanel::PublicAPI::CFG{'uri_encoder_func'}->( $argref->[$count] ); $count++; } } my $page_ref = $self->whmreq( $uri, 'POST', join( '&', @{$opts} ) ); if ( $self->{'error'} ) { return ''; } return $page_ref; } sub whmreq { my $self = shift; my $uri = shift; my $method = shift || 'GET'; my $formdata = shift; if ( $method eq 'GET' && $uri =~ /\?/ ) { ( $uri, $formdata ) = split( /\?/, $uri ); } $self->debug("whmreq: ( $self, $uri, $method, $formdata )\n") if $self->{'debug'}; my ( $status, $statusmsg, $data ) = $self->api_request( 'whostmgr', $uri, $method, $formdata ); return wantarray ? split( /\r?\n/, $$data ) : $$data; } sub api1 { #Cpanel::Accounting compat my $self = shift; my $user = shift; my $module = shift; my $func = shift; return $self->cpanel_api1_request( 'whostmgr', { 'user' => $user, 'module' => $module, 'func' => $func }, \@_, 'xml' ); } sub api2 { #Cpanel::Accounting compat my $self = shift; my $user = shift; my $module = shift; my $func = shift; return $self->cpanel_api2_request( 'whostmgr', { 'user' => $user, 'module' => $module, 'func' => $func }, {@_}, 'xml' ); } 1; PK � �[ lib/cPanel/.existsnu �[��� PK � �[�r�d\ d\ lib/cPanel/PublicAPI.pmnu ��6�$ package cPanel::PublicAPI; # Copyright 2019 cPanel, L.L.C. # All rights reserved. # http://cpanel.net # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # 3. Neither the name of the owner nor the names of its contributors may be # used to endorse or promote products derived from this software without # specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. our $VERSION = '2.8'; use strict; use Carp (); use MIME::Base64 (); use HTTP::Tiny (); use HTTP::CookieJar (); our %CFG; my %PORT_DB = ( 'whostmgr' => { 'ssl' => 2087, 'plaintext' => 2086, }, 'cpanel' => { 'ssl' => 2083, 'plaintext' => 2082, }, 'webmail' => { 'ssl' => 2096, 'plaintext' => 2095, }, ); sub _create_http_tiny { return HTTP::Tiny->new(@_); } sub new { my ( $class, %OPTS ) = @_; my $self = {}; bless( $self, $class ); $self->{'debug'} = $OPTS{'debug'} || 0; $self->{'timeout'} = $OPTS{'timeout'} || 300; $self->{'usessl'} = exists $OPTS{'usessl'} ? $OPTS{'usessl'} : 1; if ( exists $OPTS{'ip'} ) { $self->{'ip'} = $OPTS{'ip'}; } elsif ( exists $OPTS{'host'} ) { $self->{'host'} = $OPTS{'host'}; } else { $self->{'ip'} = '127.0.0.1'; } my $ua_creator = $OPTS{'http_tiny_creator'} || \&_create_http_tiny; $self->{'ua'} = $ua_creator->( agent => "cPanel::PublicAPI/$VERSION ", verify_SSL => ( exists $OPTS{'ssl_verify_mode'} ? $OPTS{'ssl_verify_mode'} : 1 ), keep_alive => ( exists $OPTS{'keepalive'} ? int $OPTS{'keepalive'} : 0 ), timeout => $self->{'timeout'}, ); if ( exists $OPTS{'error_log'} && $OPTS{'error_log'} ne 'STDERR' ) { if ( !open( $self->{'error_fh'}, '>>', $OPTS{'error_log'} ) ) { print STDERR "Unable to open $OPTS{'error_log'} for writing, defaulting to STDERR for error logging: $@\n"; $self->{'error_fh'} = \*STDERR; } } else { $self->{'error_fh'} = \*STDERR; } if ( $OPTS{'user'} ) { $self->{'user'} = $OPTS{'user'}; $self->debug("Using user param from object creation") if $self->{'debug'}; } else { $self->{'user'} = exists $INC{'Cpanel/PwCache.pm'} ? ( Cpanel::PwCache::getpwuid($>) )[0] : ( getpwuid($>) )[0]; $self->debug("Setting user based on current uid ($>)") if $self->{'debug'}; } if ( exists $OPTS{'api_token'} && exists $OPTS{'accesshash'} ) { $self->error('You cannot specify both an accesshash and an API token'); die $self->{'error'}; } # Allow the user to specify an api_token instead of an accesshash. # Though, it will just act as a synonym. $OPTS{'accesshash'} = $OPTS{'api_token'} if $OPTS{'api_token'}; if ( ( !exists( $OPTS{'pass'} ) || $OPTS{'pass'} eq '' ) && ( !exists $OPTS{'accesshash'} || $OPTS{'accesshash'} eq '' ) ) { my $homedir = exists $INC{'Cpanel/PwCache.pm'} ? ( Cpanel::PwCache::getpwuid($>) )[7] : ( getpwuid($>) )[7]; $self->debug("Attempting to detect correct authentication credentials") if $self->{'debug'}; if ( -e $homedir . '/.accesshash' ) { local $/; if ( open( my $hash_fh, '<', $homedir . '/.accesshash' ) ) { $self->{'accesshash'} = readline($hash_fh); $self->{'accesshash'} =~ s/[\r\n]+//g; close($hash_fh); $self->debug("Got accesshash from $homedir/.accesshash") if $self->{'debug'}; } else { $self->debug("Failed to fetch accesshash from $homedir/.accesshash") if $self->{'debug'}; } } elsif ( exists $ENV{'REMOTE_PASSWORD'} && $ENV{'REMOTE_PASSWORD'} && $ENV{'REMOTE_PASSWORD'} ne '__HIDDEN__' && exists $ENV{'SERVER_SOFTWARE'} && $ENV{'SERVER_SOFTWARE'} =~ /^cpsrvd/ ) { $self->debug("Got user password from the REMOTE_PASSWORD environment variables.") if $self->{'debug'}; $self->{'pass'} = $ENV{'REMOTE_PASSWORD'}; } else { Carp::confess('pass, accesshash, or api_token is a required parameter'); } } elsif ( $OPTS{'pass'} ) { $self->{'pass'} = $OPTS{'pass'}; $self->debug("Using pass param from object creation") if $self->{'debug'}; } else { $OPTS{'accesshash'} =~ s/[\r\n]//; $self->{'accesshash'} = $OPTS{'accesshash'}; $self->debug("Using accesshash param from object creation") if $self->{'debug'}; } $self->_update_operating_mode(); return $self; } sub set_debug { my $self = shift; $self->{'debug'} = int shift; } sub user { my $self = shift; $self->{'user'} = shift; } sub pass { my $self = shift; $self->{'pass'} = shift; delete $self->{'accesshash'}; $self->_update_operating_mode(); } sub accesshash { my $self = shift; $self->{'accesshash'} = shift; delete $self->{'pass'}; $self->_update_operating_mode(); } sub api_token { return shift->accesshash(@_); } sub whm_api { my ( $self, $call, $formdata, $format ) = @_; $self->_init_serializer() if !exists $cPanel::PublicAPI::CFG{'serializer'}; if ( !defined $call || $call eq '' ) { $self->error("A call was not defined when called cPanel::PublicAPI::whm_api_request()"); } if ( defined $format && $format ne 'xml' && $format ne 'json' && $format ne 'ref' ) { $self->error("cPanel::PublicAPI::whm_api_request() was called with an invalid data format, the only valid format are 'json', 'ref' or 'xml'"); } $formdata ||= {}; if ( ref $formdata ) { $formdata = { 'api.version' => 1, %$formdata }; } elsif ( $formdata !~ /(^|&)api\.version=/ ) { $formdata = "api.version=1&$formdata"; } my $query_format; if ( defined $format ) { $query_format = $format; } else { $query_format = $CFG{'serializer'}; } my $uri = "/$query_format-api/$call"; my ( $status, $statusmsg, $data ) = $self->api_request( 'whostmgr', $uri, 'POST', $formdata ); return $self->_parse_returndata( { 'caller' => 'whm_api', 'data' => $data, 'format' => $format, 'call' => $call } ); } sub api_request { my ( $self, $service, $uri, $method, $formdata, $headers ) = @_; $formdata ||= ''; $method ||= 'GET'; $headers ||= {}; $self->debug("api_request: ( $self, $service, $uri, $method, $formdata, $headers )") if $self->{'debug'}; $self->_init() if !exists $CFG{'init'}; undef $self->{'error'}; my $timeout = $self->{'timeout'} || 300; my $orig_alarm = 0; my $page; my $port = $self->_determine_port_for_service($service); $self->debug("Found port for service $service to be $port (usessl=$self->{'usessl'})") if $self->{'debug'}; eval { $self->{'remote_server'} = $self->{'ip'} || $self->{'host'}; $self->_validate_connection_settings(); if ( $self->{'operating_mode'} eq 'session' ) { $self->_establish_session($service) if !( $self->{'security_tokens'}->{$service} && $self->{'cookie_jars'}->{$service} ); $self->{'ua'}->cookie_jar( $self->{'cookie_jars'}->{$service} ); } my $remote_server = $self->{'remote_server'}; my $attempts = 0; my $finished_request = 0; my $hassigpipe; local $SIG{'ALRM'} = sub { $self->error('Connection Timed Out'); die $self->{'error'}; }; local $SIG{'PIPE'} = sub { $hassigpipe = 1; }; $orig_alarm = alarm($timeout); $formdata = $self->format_http_query($formdata) if ref $formdata; my $scheme = $self->{'usessl'} ? "https" : "http"; my $url = "$scheme://$remote_server:$port"; if ( $self->{'operating_mode'} eq 'session' ) { my $security_token = $self->{'security_tokens'}->{$service}; $url .= '/' . $self->{'security_tokens'}->{$service} . $uri; } else { $url .= $uri; } my $content; if ( $method eq 'POST' || $method eq 'PUT' ) { $content = $formdata; } else { $url .= "?$formdata"; } $self->debug("URL: $url") if $self->{'debug'}; if ( !ref $headers ) { my @lines = split /\r\n/, $headers; $headers = {}; foreach my $line (@lines) { last unless length $line; my ( $key, $value ) = split /:\s*/, $line, 2; next unless length $key; $headers->{$key} ||= []; push @{ $headers->{$key} }, $value; } } if ($self->{'operating_mode'} eq 'accesshash') { my $token_app = ($service eq 'whostmgr') ? 'whm' : $service; $headers->{'Authorization'} = sprintf( '%s %s:%s', $token_app, $self->{'user'}, $self->{'accesshash'}, ); } my $options = { headers => $headers, }; $options->{'content'} = $content if defined $content; my $ua = $self->{'ua'}; while ( ++$attempts < 3 ) { $hassigpipe = 0; my $response = $ua->request( $method, $url, $options ); if ( $response->{'status'} == 599 ) { $self->error("Could not connect to $url: $response->{'content'}"); die $self->{'error'}; #exit eval } if ($hassigpipe) { next; } # http spec says to reconnect my %HEADERS; if ( $self->{'debug'} ) { %HEADERS = %{ $response->{'headers'} }; foreach my $header ( keys %HEADERS ) { $self->debug("HEADER[$header]=[$HEADERS{$header}]"); } if ( exists $HEADERS{'transfer-encoding'} && $HEADERS{'transfer-encoding'} =~ /chunked/i ) { $self->debug("READ TYPE=chunked"); } elsif ( defined $HEADERS{'content-length'} ) { $self->debug("READ TYPE=content-length"); } else { $self->debug("READ TYPE=close"); } } if ( !$response->{'success'} ) { $self->error("Server Error from $remote_server: $response->{'status'} $response->{'reason'}"); } $page = $response->{'content'}; $finished_request = 1; last; } if ( !$finished_request && !$self->{'error'} ) { $self->error("The request could not be completed after the maximum attempts"); } }; if ( $self->{'debug'} && $@ ) { warn $@; } alarm($orig_alarm); # Reset with parent's alarm value return ( $self->{'error'} ? 0 : 1, $self->{'error'}, \$page ); } sub establish_tfa_session { my ( $self, $service, $tfa_token ) = @_; if ( $self->{'operating_mode'} ne 'session' ) { $self->error("2FA-authenticated sessions are not supported when using accesshash keys or API tokens"); die $self->{'error'}; } if ( !( $service && $tfa_token ) ) { $self->error("You must specify the service name, and the 2FA token in order to establish a 2FA-authenticated session"); die $self->{'error'}; } undef $self->{'cookie_jars'}->{$service}; undef $self->{'security_tokens'}->{$service}; return $self->_establish_session( $service, $tfa_token ); } sub _validate_connection_settings { my $self = shift; if ( !$self->{'user'} ) { $self->error("You must specify a user to login as."); die $self->{'error'}; } if ( !$self->{'remote_server'} ) { $self->error("You must set a host to connect to. (missing 'host' and 'ip' parameter)"); die $self->{'error'}; } } sub _update_operating_mode { my $self = shift; if ( exists $self->{'accesshash'} ) { $self->{'accesshash'} =~ s/[\r\n]//g; $self->{'operating_mode'} = 'accesshash'; } elsif ( exists $self->{'pass'} ) { $self->{'operating_mode'} = 'session'; # This is called whenever the pass or accesshash is changed, # so we reset the cookie jars, and tokens on such changes $self->{'cookie_jars'} = { map { $_ => undef } keys %PORT_DB }; $self->{'security_tokens'} = { map { $_ => undef } keys %PORT_DB }; } else { $self->error('You must specify an accesshash, API token, or password'); die $self->{'error'}; } } sub _establish_session { my ( $self, $service, $tfa_token ) = @_; return if $self->{'operating_mode'} ne 'session'; return if $self->{'security_tokens'}->{$service} && $self->{'cookie_jars'}->{$service}; $self->{'cookie_jars'}->{$service} = HTTP::CookieJar->new(); $self->{'ua'}->cookie_jar( $self->{'cookie_jars'}->{$service} ); my $port = $self->_determine_port_for_service($service); my $scheme = $self->{'usessl'} ? "https" : "http"; my $url = "$scheme://$self->{'remote_server'}:$port/login"; my $resp = $self->{'ua'}->post_form( $url, { 'user' => $self->{'user'}, 'pass' => $self->{'pass'}, ( $tfa_token ? ( 'tfa_token' => $tfa_token ) : () ), }, ); if ( my $security_token = ( split /\//, $resp->{'headers'}->{'location'} )[1] ) { $self->{'security_tokens'}->{$service} = $security_token; $self->debug("Established $service session"); return 1; } my $details = $resp->{'reason'}; $details .= " ($resp->{'content'})" if $resp->{'status'} == 599; $self->error("Failed to establish session and parse security token: $resp->{'status'} $details"); die $self->{'error'}; } sub _determine_port_for_service { my ( $self, $service ) = @_; my $port; if ( $self->{'usessl'} ) { $port = $service =~ /^\d+$/ ? $service : $PORT_DB{$service}{'ssl'}; } else { $port = $service =~ /^\d+$/ ? $service : $PORT_DB{$service}{'plaintext'}; } return $port; } sub cpanel_api1_request { my ( $self, $service, $cfg, $formdata, $format ) = @_; my $query_format; if ( defined $format ) { $query_format = $format; } else { $query_format = $CFG{'serializer'}; } $self->_init_serializer() if !exists $cPanel::PublicAPI::CFG{'serializer'}; my $count = 0; if ( ref $formdata eq 'ARRAY' ) { $formdata = { map { ( 'arg-' . $count++ ) => $_ } @{$formdata} }; } foreach my $cfg_item ( keys %{$cfg} ) { $formdata->{ 'cpanel_' . $query_format . 'api_' . $cfg_item } = $cfg->{$cfg_item}; } $formdata->{ 'cpanel_' . $query_format . 'api_apiversion' } = 1; my ( $status, $statusmsg, $data ) = $self->api_request( $service, '/' . $query_format . '-api/cpanel', ( ( scalar keys %$formdata < 10 && _total_form_length( $formdata, 1024 ) < 1024 ) ? 'GET' : 'POST' ), $formdata ); return $self->_parse_returndata( { 'caller' => 'cpanel_api1', 'data' => $data, 'format' => $format, } ); } sub cpanel_api2_request { my ( $self, $service, $cfg, $formdata, $format ) = @_; $self->_init_serializer() if !exists $cPanel::PublicAPI::CFG{'serializer'}; my $query_format; if ( defined $format ) { $query_format = $format; } else { $query_format = $CFG{'serializer'}; } foreach my $cfg_item ( keys %{$cfg} ) { $formdata->{ 'cpanel_' . $query_format . 'api_' . $cfg_item } = $cfg->{$cfg_item}; } $formdata->{ 'cpanel_' . $query_format . 'api_apiversion' } = 2; my ( $status, $statusmsg, $data ) = $self->api_request( $service, '/' . $query_format . '-api/cpanel', ( ( scalar keys %$formdata < 10 && _total_form_length( $formdata, 1024 ) < 1024 ) ? 'GET' : 'POST' ), $formdata ); return $self->_parse_returndata( { 'caller' => 'cpanel_api2', 'data' => $data, 'format' => $format, } ); } sub _parse_returndata { my ( $self, $opts_hr ) = @_; if ( $self->{'error'} ) { die $self->{'error'}; } elsif ( ${ $opts_hr->{'data'} } =~ m/tfa_login_form/ ) { $self->error("Two-Factor Authentication enabled on the account. Establish a session with the security token, or disable 2FA on the account"); die $self->{'error'}; } if ( defined $opts_hr->{'format'} && ( $opts_hr->{'format'} eq 'json' || $opts_hr->{'format'} eq 'xml' ) ) { return ${ $opts_hr->{'data'} }; } else { my $parsed_data; eval { $parsed_data = $CFG{'api_decode_func'}->( ${ $opts_hr->{'data'} } ); }; if ( !ref $parsed_data ) { $self->error("There was an issue with parsing the following response from cPanel or WHM: [data=[${$opts_hr->{'data'}}]]"); die $self->{'error'}; } my $error_check_dt = { 'whm_api' => \&_check_whm_api_errors, 'cpanel_api1' => \&_check_cpanel_api1_errors, 'cpanel_api2' => \&_check_cpanel_api2_errors, }; return $error_check_dt->{ $opts_hr->{'caller'} }->( $self, $opts_hr->{'call'}, $parsed_data ); } } sub _check_whm_api_errors { my ( $self, $call, $parsed_data ) = @_; if ( ( exists $parsed_data->{'error'} && $parsed_data->{'error'} =~ /Unknown App Requested/ ) || # xml-api v0 version ( exists $parsed_data->{'metadata'}->{'reason'} && $parsed_data->{'metadata'}->{'reason'} =~ /Unknown app\s+(?:\(.+\))?\s+requested/ ) # xml-api v1 version ) { $self->error("cPanel::PublicAPI::whm_api was called with the invalid API call of: $call."); return; } return $parsed_data; } sub _check_cpanel_api1_errors { my ( $self, undef, $parsed_data ) = @_; if ( exists $parsed_data->{'event'}->{'reason'} && ( $parsed_data->{'event'}->{'reason'} =~ /failed: Undefined subroutine/ || # pre-11.44 error message $parsed_data->{'event'}->{'reason'} =~ m/failed: Can\'t use string/ # 11.44+ error message ) ) { $self->error( "cPanel::PublicAPI::cpanel_api1_request was called with the invalid API1 call of: " . $parsed_data->{'module'} . '::' . $parsed_data->{'func'} ); return; } return $parsed_data; } sub _check_cpanel_api2_errors { my ( $self, undef, $parsed_data ) = @_; if ( exists $parsed_data->{'cpanelresult'}->{'error'} && $parsed_data->{'cpanelresult'}->{'error'} =~ /Could not find function/ ) { # xml-api v1 version $self->error( "cPanel::PublicAPI::cpanel_api2_request was called with the invalid API2 call of: " . $parsed_data->{'cpanelresult'}->{'module'} . '::' . $parsed_data->{'cpanelresult'}->{'func'} ); return; } return $parsed_data; } sub _total_form_length { my $data = shift; my $max = shift; my $size = 0; foreach my $key ( keys %{$data} ) { return 1024 if ( ( $size += ( length($key) + 2 + length( $data->{$key} ) ) ) >= 1024 ); } return $size; } sub _init_serializer { return if exists $CFG{'serializer'}; my $self = shift; #not required foreach my $serializer ( #module, key (cpanel api uri), deserializer function name [ 'JSON::Syck', 'json', 'Load' ], [ 'JSON', 'json', 'decode_json' ], [ 'JSON::XS', 'json', 'decode_json' ], [ 'JSON::PP', 'json', 'decode_json' ], ) { my $serializer_module = $serializer->[0]; my $serializer_key = $serializer->[1]; eval " require $serializer_module; "; if ( !$@ ) { $self->debug("loaded serializer: $serializer_module") if $self && ref $self && $self->{'debug'}; $CFG{'serializer'} = $CFG{'parser_key'} = $serializer_key; $CFG{'serializer_module'} = $CFG{'parser_module'} = $serializer_module; $CFG{'api_decode_func'} = $serializer_module->can($serializer->[2]); last; } else { $self->debug("Failed to load serializer: $serializer_module: @_") if $self && ref $self && $self->{'debug'}; } } if ($@) { Carp::confess("Unable to find a module capable of deserializing the api response."); } } sub _init { return if exists $CFG{'init'}; my $self = shift; #not required $CFG{'init'} = 1; # moved this over to a pattern to allow easy change of deps foreach my $encoder ( [ 'Cpanel/Encoder/URI.pm', 'Cpanel::Encoder::URI', 'uri_encode_str' ], [ 'URI/Escape.pm', 'URI::Escape', 'uri_escape' ], ) { my $module_path = $encoder->[0]; my $module = $encoder->[1]; my $funcname = $encoder->[2]; eval { require $module_path; }; if ( !$@ ) { $self->debug("loaded encoder: $module_path") if $self && ref $self && $self->{'debug'}; $CFG{'uri_encoder_func'} = $module->can($funcname); last; } else { $self->debug("failed to load encoder: $module_path") if $self && ref $self && $self->{'debug'}; } } if ($@) { Carp::confess("Unable to find a module capable of encoding api requests."); } } sub error { my ( $self, $msg ) = @_; print { $self->{'error_fh'} } $msg . "\n"; $self->{'error'} = $msg; } sub debug { my ( $self, $msg ) = @_; print { $self->{'error_fh'} } "debug: " . $msg . "\n"; } sub format_http_headers { my ( $self, $headers ) = @_; if ( ref $headers ) { return '' if !scalar keys %{$headers}; return join( "\r\n", map { $_ ? ( $_ . ': ' . $headers->{$_} ) : () } keys %{$headers} ) . "\r\n"; } return $headers; } sub format_http_query { my ( $self, $formdata ) = @_; if ( ref $formdata ) { return join( '&', map { $CFG{'uri_encoder_func'}->($_) . '=' . $CFG{'uri_encoder_func'}->( $formdata->{$_} ) } sort keys %{$formdata} ); } return $formdata; } PK � �[�R�*�F �F lib/cPanel/PublicAPI.podnu ��6�$ =encoding UTF-8 =head1 NAME cPanel::PublicAPI - A perl interface for interacting with cPanel =head1 SYNOPSIS use cPanel::PublicAPI; # Auto detect authentication information my $cp = cPanel::PublicAPI->new(); # or specify a user/password my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'pass' => 'somepass' ); # or specify an accesshash my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'accesshash' => $accesshash ); # or specify an API token my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'api_token' => $api_token ); # Perform an xml-api query $cp->whm_api('listaccts'); # Pass parameters to the xml-api $cp->whm_api('createacct', {'username' => 'someuser', 'password' => 's0m3P4$$w()Rd' } ); # Return JSON from xml-api (rather than a hash reference) $cp->whm_api('version', undef, 'json'); # Perform an API2 query $cp->cpanel_api2_request('whostmgr', { 'module' => 'Email', 'func' => 'listpopswithdisk', 'user' => 'someuser', } ); # Perform an API2 query when authenticated as a user $cp->cpanel_api2_request('cpanel', { 'module' => 'Email', 'func' => 'listpopswithdisk', } ); # Pass parameters to an API2 call $cp->cpanel_api2_request('cpanel' { 'module' => 'Email', 'func' => 'addpop', }, { 'domain' => 'domain.com', 'email' => 'username', 'password' => 'SojmASDM(#(Jinasifodanosd', 'quota' => 200 }, ); # Perform an API1 query $cp->cpanel_api1_request('whostmgr', { 'module' => 'LastLogin', 'func' => 'lastlogin', 'user' => 'someuser' } ); # Pass parameters to an API1 query $cp->cpanel_api1_request('cpanel', { 'module' => 'Mysql', 'func' => 'adduserdb', }, [ 'somedb', 'somedbuser', 'ALL' ] ); # perform an HTTP GET request against a URL $cp->api_request('whostmgr', '/xml-api/loadavg', 'GET'); # perform an HTTP GET request with parameters $cp->api_request('whostmgr', '/xml-api/createacct', 'GET', {'username' => 'someuser', domain => 'domain.com'} ); # perform an HTTP POST request (with parameters) $cp->api_request('whostmgr', '/xml-api/createacct', 'POST', {'username' => 'someuser', domain => 'domain.com'} ); =head1 DESCRIPTION cPanel::PublicAPI is a supported interface for interacting with cPanel's APIs over HTTP. This allows you to query either WHM or cPanel accounts from a perl interface. The purpose of this module is to provide an easy-to-use interface into cPanel's various APIs without requiring much knowledge of how they work. =head2 Object Construction a cPanel::PublicAPI object is constructed with the new() method. my $publicapi = cPanel::PublicAPI->new(); When passed no parameters, this will create the object using the accesshash in ~/.accesshash. If no .accesshash file exists, it will attempt to use the REMOTE_PASS environment variable. If the REMOTE_PASS variable is not defined, object creation will error out. =head3 new() parameters options for new() are specified as a hash reference, the following parameters are supported: =over =item * user - The username to authenticate as. =item * pass - The password to use for authentication. =item * accesshash - The accesshash to use for authentication (WHM only). =item * api_token - The API token to use for authentication. =item * timeout - The length of time (in seconds) before an http request should time out. Default to 300. =item * ip - The IP to be queried. defaults to 127.0.0.1, if host is defined it will take precedence over the 'ip' parameter. =item * host - The hostname to be queried. This will take precedence over the 'ip' parameter. =item * usessl - 1 or 0, Indicates whether communication should be performed over SSL or not (default to 1). =item * ssl_verify_mode - 1 or 0, Indicates whether to verify SSL certificates or not. (default to 1). =item * error_log - Path to where you want debug and error logging information to be written to. If this is not defined or the module is unable to open the path in question, it will default to STDERR. =item * debug - Enables debug logging, which will place considerably more information into the error_log. =item * http_tiny_creator - An optional code reference that receives the list of key/value pairs that normally goes into L<HTTP::Tiny>’s constructor to create an instance of that class for this module’s internal use. The code reference, when called, should return an object that implements an HTTP::Tiny-compatible interface. This parameter is useful for customizing that internal HTTP::Tiny instance that cPanel::PublicAPI uses. Handle with care, though: this parameter may break cPanel::PublicAPI in various ways—some subtle, others less so. For example, if you want a custom User-Agent header, you might do: http_tiny_creator => sub { return HTTP::Tiny->new( @_, agent => 'My Custom UA String', ); }, =back =head3 Authentication methods This module supports three authentication methods: =over =item 1. Username & Password use cPanel::PublicAPI; my $pubapi = cPanel::PublicAPI->new( 'user' => 'foo', 'pass' => 'bar' ); =item 2. API Token (Note: This method does not work with Webmail.) To create an API token, visit "Manage API Tokens" in cPanel or WHM, and follow the appropriate prompts. Your token will appear in a special notice. Make certain that you save your API token in a safe location, as this is the only time the token will be shown to you. To use an API token with this module, do the following: use cPanel::PublicAPI; my $pubapi = cPanel::PublicAPI->new( 'user' => 'foo', 'api_token' => $string_containing_api_token ); =item 3. WHM Access Hash B<NOTE:> Accesshash authentication is deprecated as of cPanel & WHM version 64. To configure accesshashes, you can either: =over =item * In cPanel & WHM version 66 and earlier, visit “Setup remote access key” in WHM which will generate an accesshash for your server if one does not already exist. =item * Run F</usr/local/cpanel/bin/mkaccesshash>. This will overwrite any existing access hash. =back The generated accesshash is stored in F<~/.accesshash>. To use an accesshash with this module, do the following: use cPanel::PublicAPI; my $pubapi = cPanel::PublicAPI->new( 'user' => 'foo', 'accesshash' => $string_containing_access_hash ); It should be noted that the accesshash can contain newlines in it. Newlines will be stripped by the object when it attempts to perform a query. =back =head3 Dependencies This module will fall back on different modules if one fails to load. This allows for compatibility with cPanel & WHM's internal perl parser and maintain compatibility with a standard perl implementation. The order that it will fall back on serialization modules is: =over =item * JSON::Syck =item * JSON =item * JSON::XS =item * JSON::PP =back If you installed this module via CPAN, this should never be an issue. If you are wishing to use this module on a system where you do not have access to compiled modules, JSON::PP is the recommended serializer. =head1 Two-Factor Authentication (2FA) cPanel version 54 and above allows users to configure 2FA on their accounts - this security policy requires that the API queries are performed after authenticating and establishing a session. The workflow to accomodate 2FA will be as so: use cPanel::PublicAPI; use lib '/usr/local/cpanel'; use Cpanel::Security::Authn::TwoFactorAuth::Google (); # only available in 11.54+ my $pubapi = cPanel::PublicAPI->new( 'user' => 'foo', 'pass' => 'bar' ); my $google_auth = Cpanel::Security::Authn::TwoFactorAuth::Google->new( { 'account_name' => 'foo', 'secret' => $user_2fa_secret, 'issuer' => '' } ); $pubapi->establish_tfa_session('whostmgr', $google_auth->generate_code()); $pubapi->whm_api('applist'); Anytime you change services (e.g. from 'whostmgr' to 'cpanel'), you must establish the 2FA session for the new service. eval { $pubapi->cpanel_api2_request('cpanel', { 'user' => 'foo', 'module' => 'MysqlFE', 'func' => 'listdbs' }, {} ); }; print "failed cause 2fa session wasn't established\n" if $@; $pubapi->establish_tfa_session('cpanel', $google_auth->generate_code()); eval { $pubapi->cpanel_api2_request('cpanel', { 'user' => 'foo', 'module' => 'MysqlFE', 'func' => 'listdbs' }, {} ); }; print "success\n" if not $@; B<NOTE>: Additionally, since accesshash authentication is not allowed to establish sessions, you must use the 'user'/'pass' authentication in order to make API requests as a user with 2FA configured. =head1 Important Methods =head2 Querying the xml-api - whm_api() The XML-API is WHM's API used for administrative functions is handled via the whm_api() method. The syntax for whmapi is: $cp->whm_api($call [, \%formdata, $format ] ); The meaning of these parameters is: =over =item * $call - The XML-API call you wish to query =item * $formdata - The parameters for the XML-API call in question, f.ex. for suspendacct, here you would pass in a hashref containing “user” and “reason”. If there are no parameters, this can be undef or a blank hash. =item * $format - The requested response format. The valid values here are “xml”, “json” or “ref” (perl hash reference). This will default to returning a perl hash reference when the value is undef. =back By default, WHM API v1 is used. If, for legacy reasons, you need to use v0, please set the C<api.version> key to 0 in the formdata parameter. For more information on what calls are available and how they can be referenced, please see the xml-api documentation at L<http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/XmlApi>. =head2 Querying cPanel's APIs cPanel supports two APIs, designated "API1" and "API2". cPanel API calls are seperate into Modules, these module names relate to modules within the Cpanel namespace on a cPanel server. Each module defines a set of functions that are from either API1 or API2 (or both). There are two distinct differences between API1 and API2: =over =item * API1 Takes in ordered parameters and returns strings =item * API2 uses named parameters and returns hashes or arrays of hashes =back Within the context of the public api, calling a function from API1 or API2 will always return a hash, but the specific data returned from the API call will be contained within the 'data' key of the response. For more information on the differences between API1 and API2 please see the documentation: L<http://docs.cpanel.net/twiki/bin/view/DeveloperResources/ApiBasics/WebHome> For information on calling API1 and API2 direct via HTTP, please see: L<http://docs.cpanel.net/twiki/bin/view/AllDocumentation/AutomationIntegration/CallingAPIFunctions> =head3 cpanel_api1_request() C<cpanel_api1_request()> is used to query cPanel's API1, the function used for querying API1 has the following syntax: $cp->cpanel_api1_request($service, \%cfg [, \@params, $format ] ); =over =item * $service - The service that you wish to query. This can be 'cpanel' 'whostmgr', or 'webmail'. It is important to note that what services you are able to query depends on the user you are authenticated as. Only a user with reseller or root access can use the whostmgr service. If you are authenticated as root, you will not be able to query the 'cpanel' service. When the service is set to 'whostmgr' a 'user' must be set in the $cfg hash. =item * $cfg - A hash reference describing the call you wish to make. Required parameters are 'module' and 'func', which correspond to the module and function of the API call you wish to query. If you are querying the "whostmgr" service, you will need to specify 'user' as well. =item * $params - An array reference containing the parameters you wish to pass to the API call. =item * $format - The format for the xml-api to respond in. The valid values here are “xml”, “json” or “ref” (perl hash reference). This will default to returning a perl hash reference. =back To see what modules and functions are available for making API1 calls, please see: L<http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api1/WebHome> =head3 cpanel_api2_request() C<cpanel_api2_request()> is used to query cPanel's API2, the function use for querying API2 has the following syntax: $cp->cpanel_api2_request( $service, \%cfg [, \%params, $format ] ); =over =item * $service - The service that you wish to query. This can be 'cpanel' 'whostmgr', or 'webmail'. It is important to note that what services you are able to query depends on the user you are authenticated as. A user that does not have reseller or root access will not be able to use the whostmgr service. If you are authenticated as root, you will not be able to query the 'cpanel' service. When the service is set to 'whostmgr' a 'user' must be set in the $cfg hash. =item * $cfg - A hash reference describing the call you wish to make. required parameters here are 'module' and 'func', which correspond to the module and function of the API call you wish to query. If you are querying the "whostmgr" service, you will need to specify 'user' as well. =item * $params - An hash reference containing the parameters you wish to pass to the API call. =item * $format - The format for the xml-api to respond in. The valid values here are “xml”, “json” or “ref” (perl hash reference). This will default to returning a perl hash reference when the value is undef. =back To see what modules and functions are available for making API2 calls, please see: L<http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api2/WebHome> =head2 api_request() - Making direct URL requests to cPanel & WHM. There are some situations where you will need to query cPanel and WHM URLs directly. This should ONLY be done when there is not an API call available for the function you wish to query. The function used for querying URLs directly is api_request(). It will always return a string rather than converting the response into a hash reference. It uses the following syntax: $cp->api_request( $service, $uri, $method, \%formdata, $headers) =over =item * $service - The service that you wish to query. This can be 'cpanel' 'whostmgr', or 'webmail', when passed an numerical value, PublicAPI will query that port directly. =item * $uri - The URL you wish to query, e.g. '/xml-api/cpanel' =item * $method - 'GET' or 'POST' =item * $formdata - The data you wish to pass to the URL =item * $headers - Any additional headers are to be passed with the request. These can be either a flat string or as a hashref like {'headertitle' =E<gt> 'headerdata'} =back =head1 Other Features =over =item C<establish_tfa_session()> =back See L</Two-Factor Authentication (2FA)> above. =over =item C<set_debug()> =back This function allows you to enable/disable debug mode by passing a value that evaluates to 'true' or 'false'. =over =item C<user()> =back Allows you to change the user that your PublicAPI object is authenticating with. =over =item C<pass()> =back Allows you to change the password that your PublicAPI object is authenticating with, this will remove the stored accesshash from the object. =over =item C<accesshash()> =back Allows you to change the accesshash that your PublicAPI object is authenticating with, this will remove the stored password from the object. =over =item C<api_token()> =back Allows you to change the API token that your PublicAPI object is authenticating with, this will remove the stored password from the object. =over =item C<format_http_query()> =back Allows you to construct formdata for an http query from a hash. For Example: $pubapi->format_http_query( { 'one' => '1', 'two' => 2 } ); would return: 'one=1&two=2' =over =item C<format_http_headers()> =back Allows you to construct headers for an http query from a hash. For Example: $pubapi->format_http_headers( { 'Authorization' => 'Basic cm9vdDpsMGx1cnNtNHJ0IQ=='} ); would return: 'Authorization: Basic cm9vdDpsMGx1cnNtNHJ0IQ==\r\n' =over =item C<$pubapi-E<gt>{'error'}> =back Errors encountered within the class are stored here before being written out to the error_fh filehandle. This can be used for checking the existance of query errors. =head1 Bugs see http://rt.cpan.org to report and view bugs =head1 License Copyright (c) 2015, cPanel, Inc. All rights reserved. http://cpanel.net Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PK � �[ ! lib/auto/cPanel/PublicAPI/.existsnu �[��� PK �[OFCn�E �E man3/Capture::Tiny.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Capture::Tiny 3" .TH Capture::Tiny 3 "2018-04-22" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Capture::Tiny \- Capture STDOUT and STDERR from Perl, XS or external programs .SH "VERSION" .IX Header "VERSION" version 0.48 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Capture::Tiny \*(Aq:all\*(Aq; \& \& # capture from external command \& \& ($stdout, $stderr, $exit) = capture { \& system( $cmd, @args ); \& }; \& \& # capture from arbitrary code (Perl or external) \& \& ($stdout, $stderr, @result) = capture { \& # your code here \& }; \& \& # capture partial or merged output \& \& $stdout = capture_stdout { ... }; \& $stderr = capture_stderr { ... }; \& $merged = capture_merged { ... }; \& \& # tee output \& \& ($stdout, $stderr) = tee { \& # your code here \& }; \& \& $stdout = tee_stdout { ... }; \& $stderr = tee_stderr { ... }; \& $merged = tee_merged { ... }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Capture::Tiny provides a simple, portable way to capture almost anything sent to \s-1STDOUT\s0 or \s-1STDERR,\s0 regardless of whether it comes from Perl, from \s-1XS\s0 code or from an external program. Optionally, output can be teed so that it is captured while being passed through to the original filehandles. Yes, it even works on Windows (usually). Stop guessing which of a dozen capturing modules to use in any particular situation and just use this one. .SH "USAGE" .IX Header "USAGE" The following functions are available. None are exported by default. .SS "capture" .IX Subsection "capture" .Vb 2 \& ($stdout, $stderr, @result) = capture \e&code; \& $stdout = capture \e&code; .Ve .PP The \f(CW\*(C`capture\*(C'\fR function takes a code reference and returns what is sent to \&\s-1STDOUT\s0 and \s-1STDERR\s0 as well as any return values from the code reference. In scalar context, it returns only \s-1STDOUT.\s0 If no output was received for a filehandle, it returns an empty string for that filehandle. Regardless of calling context, all output is captured \*(-- nothing is passed to the existing filehandles. .PP It is prototyped to take a subroutine reference as an argument. Thus, it can be called in block form: .PP .Vb 3 \& ($stdout, $stderr) = capture { \& # your code here ... \& }; .Ve .PP Note that the coderef is evaluated in list context. If you wish to force scalar context on the return value, you must use the \f(CW\*(C`scalar\*(C'\fR keyword. .PP .Vb 4 \& ($stdout, $stderr, $count) = capture { \& my @list = qw/one two three/; \& return scalar @list; # $count will be 3 \& }; .Ve .PP Also note that within the coderef, the \f(CW@_\fR variable will be empty. So don't use arguments from a surrounding subroutine without copying them to an array first: .PP .Vb 4 \& sub wont_work { \& my ($stdout, $stderr) = capture { do_stuff( @_ ) }; # WRONG \& ... \& } \& \& sub will_work { \& my @args = @_; \& my ($stdout, $stderr) = capture { do_stuff( @args ) }; # RIGHT \& ... \& } .Ve .PP Captures are normally done to an anonymous temporary filehandle. To capture via a named file (e.g. to externally monitor a long-running capture), provide custom filehandles as a trailing list of option pairs: .PP .Vb 3 \& my $out_fh = IO::File\->new("out.txt", "w+"); \& my $err_fh = IO::File\->new("out.txt", "w+"); \& capture { ... } stdout => $out_fh, stderr => $err_fh; .Ve .PP The filehandles must be read/write and seekable. Modifying the files or filehandles during a capture operation will give unpredictable results. Existing \s-1IO\s0 layers on them may be changed by the capture. .PP When called in void context, \f(CW\*(C`capture\*(C'\fR saves memory and time by not reading back from the capture handles. .SS "capture_stdout" .IX Subsection "capture_stdout" .Vb 2 \& ($stdout, @result) = capture_stdout \e&code; \& $stdout = capture_stdout \e&code; .Ve .PP The \f(CW\*(C`capture_stdout\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR except only \&\s-1STDOUT\s0 is captured. \s-1STDERR\s0 is not captured. .SS "capture_stderr" .IX Subsection "capture_stderr" .Vb 2 \& ($stderr, @result) = capture_stderr \e&code; \& $stderr = capture_stderr \e&code; .Ve .PP The \f(CW\*(C`capture_stderr\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR except only \&\s-1STDERR\s0 is captured. \s-1STDOUT\s0 is not captured. .SS "capture_merged" .IX Subsection "capture_merged" .Vb 2 \& ($merged, @result) = capture_merged \e&code; \& $merged = capture_merged \e&code; .Ve .PP The \f(CW\*(C`capture_merged\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR except \s-1STDOUT\s0 and \&\s-1STDERR\s0 are merged. (Technically, \s-1STDERR\s0 is redirected to the same capturing handle as \s-1STDOUT\s0 before executing the function.) .PP Caution: \s-1STDOUT\s0 and \s-1STDERR\s0 output in the merged result are not guaranteed to be properly ordered due to buffering. .SS "tee" .IX Subsection "tee" .Vb 2 \& ($stdout, $stderr, @result) = tee \e&code; \& $stdout = tee \e&code; .Ve .PP The \f(CW\*(C`tee\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR, except that output is captured as well as passed on to the original \s-1STDOUT\s0 and \s-1STDERR.\s0 .PP When called in void context, \f(CW\*(C`tee\*(C'\fR saves memory and time by not reading back from the capture handles, except when the original \s-1STDOUT OR STDERR\s0 were tied or opened to a scalar handle. .SS "tee_stdout" .IX Subsection "tee_stdout" .Vb 2 \& ($stdout, @result) = tee_stdout \e&code; \& $stdout = tee_stdout \e&code; .Ve .PP The \f(CW\*(C`tee_stdout\*(C'\fR function works just like \f(CW\*(C`tee\*(C'\fR except only \&\s-1STDOUT\s0 is teed. \s-1STDERR\s0 is not teed (output goes to \s-1STDERR\s0 as usual). .SS "tee_stderr" .IX Subsection "tee_stderr" .Vb 2 \& ($stderr, @result) = tee_stderr \e&code; \& $stderr = tee_stderr \e&code; .Ve .PP The \f(CW\*(C`tee_stderr\*(C'\fR function works just like \f(CW\*(C`tee\*(C'\fR except only \&\s-1STDERR\s0 is teed. \s-1STDOUT\s0 is not teed (output goes to \s-1STDOUT\s0 as usual). .SS "tee_merged" .IX Subsection "tee_merged" .Vb 2 \& ($merged, @result) = tee_merged \e&code; \& $merged = tee_merged \e&code; .Ve .PP The \f(CW\*(C`tee_merged\*(C'\fR function works just like \f(CW\*(C`capture_merged\*(C'\fR except that output is captured as well as passed on to \s-1STDOUT.\s0 .PP Caution: \s-1STDOUT\s0 and \s-1STDERR\s0 output in the merged result are not guaranteed to be properly ordered due to buffering. .SH "LIMITATIONS" .IX Header "LIMITATIONS" .SS "Portability" .IX Subsection "Portability" Portability is a goal, not a guarantee. \f(CW\*(C`tee\*(C'\fR requires fork, except on Windows where \f(CW\*(C`system(1, @cmd)\*(C'\fR is used instead. Not tested on any particularly esoteric platforms yet. See the \&\s-1CPAN\s0 Testers Matrix <http://matrix.cpantesters.org/?dist=Capture-Tiny> for test result by platform. .SS "PerlIO layers" .IX Subsection "PerlIO layers" Capture::Tiny does its best to preserve PerlIO layers such as ':utf8' or \&':crlf' when capturing (only for Perl 5.8.1+) . Layers should be applied to \&\s-1STDOUT\s0 or \s-1STDERR\s0 \fIbefore\fR the call to \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR. This may not work for tied filehandles (see below). .SS "Modifying filehandles before capturing" .IX Subsection "Modifying filehandles before capturing" Generally speaking, you should do little or no manipulation of the standard \s-1IO\s0 filehandles prior to using Capture::Tiny. In particular, closing, reopening, localizing or tying standard filehandles prior to capture may cause a variety of unexpected, undesirable and/or unreliable behaviors, as described below. Capture::Tiny does its best to compensate for these situations, but the results may not be what you desire. .PP \fIClosed filehandles\fR .IX Subsection "Closed filehandles" .PP Capture::Tiny will work even if \s-1STDIN, STDOUT\s0 or \s-1STDERR\s0 have been previously closed. However, since they will be reopened to capture or tee output, any code within the captured block that depends on finding them closed will, of course, not find them to be closed. If they started closed, Capture::Tiny will close them again when the capture block finishes. .PP Note that this reopening will happen even for \s-1STDIN\s0 or a filehandle not being captured to ensure that the filehandle used for capture is not opened to file descriptor 0, as this causes problems on various platforms. .PP Prior to Perl 5.12, closed \s-1STDIN\s0 combined with PERL_UNICODE=D leaks filehandles and also breaks \fBtee()\fR for undiagnosed reasons. So don't do that. .PP \fILocalized filehandles\fR .IX Subsection "Localized filehandles" .PP If code localizes any of Perl's standard filehandles before capturing, the capture will affect the localized filehandles and not the original ones. External system calls are not affected by localizing a filehandle in Perl and will continue to send output to the original filehandles (which will thus not be captured). .PP \fIScalar filehandles\fR .IX Subsection "Scalar filehandles" .PP If \s-1STDOUT\s0 or \s-1STDERR\s0 are reopened to scalar filehandles prior to the call to \&\f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR, then Capture::Tiny will override the output filehandle for the duration of the \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR call and then, for \f(CW\*(C`tee\*(C'\fR, send captured output to the output filehandle after the capture is complete. (Requires Perl 5.8) .PP Capture::Tiny attempts to preserve the semantics of \s-1STDIN\s0 opened to a scalar reference, but note that external processes will not be able to read from such a handle. Capture::Tiny tries to ensure that external processes will read from the null device instead, but this is not guaranteed. .PP \fITied output filehandles\fR .IX Subsection "Tied output filehandles" .PP If \s-1STDOUT\s0 or \s-1STDERR\s0 are tied prior to the call to \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR, then Capture::Tiny will attempt to override the tie for the duration of the \&\f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR call and then send captured output to the tied filehandle after the capture is complete. (Requires Perl 5.8) .PP Capture::Tiny may not succeed resending \s-1UTF\-8\s0 encoded data to a tied \&\s-1STDOUT\s0 or \s-1STDERR\s0 filehandle. Characters may appear as bytes. If the tied filehandle is based on Tie::StdHandle, then Capture::Tiny will attempt to determine appropriate layers like \f(CW\*(C`:utf8\*(C'\fR from the underlying filehandle and do the right thing. .PP \fITied input filehandle\fR .IX Subsection "Tied input filehandle" .PP Capture::Tiny attempts to preserve the semantics of tied \s-1STDIN,\s0 but this requires Perl 5.8 and is not entirely predictable. External processes will not be able to read from such a handle. .PP Unless having \s-1STDIN\s0 tied is crucial, it may be safest to localize \s-1STDIN\s0 when capturing: .PP .Vb 1 \& my ($out, $err) = do { local *STDIN; capture { ... } }; .Ve .SS "Modifying filehandles during a capture" .IX Subsection "Modifying filehandles during a capture" Attempting to modify \s-1STDIN, STDOUT\s0 or \s-1STDERR\s0 \fIduring\fR \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR is almost certainly going to cause problems. Don't do that. .PP \fIForking inside a capture\fR .IX Subsection "Forking inside a capture" .PP Forks aren't portable. The behavior of filehandles during a fork is even less so. If Capture::Tiny detects that a fork has occurred within a capture, it will shortcut in the child process and return empty strings for captures. Other problems may occur in the child or parent, as well. Forking in a capture block is not recommended. .PP \fIUsing threads\fR .IX Subsection "Using threads" .PP Filehandles are global. Mixing up I/O and captures in different threads without coordination is going to cause problems. Besides, threads are officially discouraged. .PP \fIDropping privileges during a capture\fR .IX Subsection "Dropping privileges during a capture" .PP If you drop privileges during a capture, temporary files created to facilitate the capture may not be cleaned up afterwards. .SS "No support for Perl 5.8.0" .IX Subsection "No support for Perl 5.8.0" It's just too buggy when it comes to layers and \s-1UTF\-8.\s0 Perl 5.8.1 or later is recommended. .SS "Limited support for Perl 5.6" .IX Subsection "Limited support for Perl 5.6" Perl 5.6 predates PerlIO. \s-1UTF\-8\s0 data may not be captured correctly. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .SS "\s-1PERL_CAPTURE_TINY_TIMEOUT\s0" .IX Subsection "PERL_CAPTURE_TINY_TIMEOUT" Capture::Tiny uses subprocesses internally for \f(CW\*(C`tee\*(C'\fR. By default, Capture::Tiny will timeout with an error if such subprocesses are not ready to receive data within 30 seconds (or whatever is the value of \&\f(CW$Capture::Tiny::TIMEOUT\fR). An alternate timeout may be specified by setting the \f(CW\*(C`PERL_CAPTURE_TINY_TIMEOUT\*(C'\fR environment variable. Setting it to zero will disable timeouts. \fB\s-1NOTE\s0\fR, this does not timeout the code reference being captured \*(-- this only prevents Capture::Tiny itself from hanging your process waiting for its child processes to be ready to proceed. .SH "SEE ALSO" .IX Header "SEE ALSO" This module was inspired by IO::CaptureOutput, which provides similar functionality without the ability to tee output and with more complicated code and \s-1API.\s0 IO::CaptureOutput does not handle layers or most of the unusual cases described in the \*(L"Limitations\*(R" section and I no longer recommend it. .PP There are many other \s-1CPAN\s0 modules that provide some sort of output capture, albeit with various limitations that make them appropriate only in particular circumstances. I'm probably missing some. The long list is provided to show why I felt Capture::Tiny was necessary. .IP "\(bu" 4 IO::Capture .IP "\(bu" 4 IO::Capture::Extended .IP "\(bu" 4 IO::CaptureOutput .IP "\(bu" 4 IPC::Capture .IP "\(bu" 4 IPC::Cmd .IP "\(bu" 4 IPC::Open2 .IP "\(bu" 4 IPC::Open3 .IP "\(bu" 4 IPC::Open3::Simple .IP "\(bu" 4 IPC::Open3::Utils .IP "\(bu" 4 IPC::Run .IP "\(bu" 4 IPC::Run::SafeHandles .IP "\(bu" 4 IPC::Run::Simple .IP "\(bu" 4 IPC::Run3 .IP "\(bu" 4 IPC::System::Simple .IP "\(bu" 4 Tee .IP "\(bu" 4 IO::Tee .IP "\(bu" 4 File::Tee .IP "\(bu" 4 Filter::Handle .IP "\(bu" 4 Tie::STDERR .IP "\(bu" 4 Tie::STDOUT .IP "\(bu" 4 Test::Output .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/Capture\-Tiny/issues>. You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP <https://github.com/dagolden/Capture\-Tiny> .PP .Vb 1 \& git clone https://github.com/dagolden/Capture\-Tiny.git .Ve .SH "AUTHOR" .IX Header "AUTHOR" David Golden <dagolden@cpan.org> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> .IP "\(bu" 4 David E. Wheeler <david@justatheory.com> .IP "\(bu" 4 fecundf <not.com+github@gmail.com> .IP "\(bu" 4 Graham Knop <haarg@haarg.org> .IP "\(bu" 4 Peter Rabbitson <ribasushi@cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2009 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve PK �[ arch/auto/Capture/Tiny/.existsnu �[��� PK �[ lib/auto/Capture/Tiny/.existsnu �[��� PK �[ lib/Capture/.existsnu �[��� PK �[��!G�s �s lib/Capture/Tiny.pmnu ��6�$ use 5.006; use strict; use warnings; package Capture::Tiny; # ABSTRACT: Capture STDOUT and STDERR from Perl, XS or external programs our $VERSION = '0.48'; use Carp (); use Exporter (); use IO::Handle (); use File::Spec (); use File::Temp qw/tempfile tmpnam/; use Scalar::Util qw/reftype blessed/; # Get PerlIO or fake it BEGIN { local $@; eval { require PerlIO; PerlIO->can('get_layers') } or *PerlIO::get_layers = sub { return () }; } #--------------------------------------------------------------------------# # create API subroutines and export them # [do STDOUT flag, do STDERR flag, do merge flag, do tee flag] #--------------------------------------------------------------------------# my %api = ( capture => [1,1,0,0], capture_stdout => [1,0,0,0], capture_stderr => [0,1,0,0], capture_merged => [1,1,1,0], tee => [1,1,0,1], tee_stdout => [1,0,0,1], tee_stderr => [0,1,0,1], tee_merged => [1,1,1,1], ); for my $sub ( keys %api ) { my $args = join q{, }, @{$api{$sub}}; eval "sub $sub(&;@) {unshift \@_, $args; goto \\&_capture_tee;}"; ## no critic } our @ISA = qw/Exporter/; our @EXPORT_OK = keys %api; our %EXPORT_TAGS = ( 'all' => \@EXPORT_OK ); #--------------------------------------------------------------------------# # constants and fixtures #--------------------------------------------------------------------------# my $IS_WIN32 = $^O eq 'MSWin32'; ##our $DEBUG = $ENV{PERL_CAPTURE_TINY_DEBUG}; ## ##my $DEBUGFH; ##open $DEBUGFH, "> DEBUG" if $DEBUG; ## ##*_debug = $DEBUG ? sub(@) { print {$DEBUGFH} @_ } : sub(){0}; our $TIMEOUT = 30; #--------------------------------------------------------------------------# # command to tee output -- the argument is a filename that must # be opened to signal that the process is ready to receive input. # This is annoying, but seems to be the best that can be done # as a simple, portable IPC technique #--------------------------------------------------------------------------# my @cmd = ($^X, '-C0', '-e', <<'HERE'); use Fcntl; $SIG{HUP}=sub{exit}; if ( my $fn=shift ) { sysopen(my $fh, qq{$fn}, O_WRONLY|O_CREAT|O_EXCL) or die $!; print {$fh} $$; close $fh; } my $buf; while (sysread(STDIN, $buf, 2048)) { syswrite(STDOUT, $buf); syswrite(STDERR, $buf); } HERE #--------------------------------------------------------------------------# # filehandle manipulation #--------------------------------------------------------------------------# sub _relayer { my ($fh, $apply_layers) = @_; # _debug("# requested layers (@{$layers}) for @{[fileno $fh]}\n"); # eliminate pseudo-layers binmode( $fh, ":raw" ); # strip off real layers until only :unix is left while ( 1 < ( my $layers =()= PerlIO::get_layers( $fh, output => 1 ) ) ) { binmode( $fh, ":pop" ); } # apply other layers my @to_apply = @$apply_layers; shift @to_apply; # eliminate initial :unix # _debug("# applying layers (unix @to_apply) to @{[fileno $fh]}\n"); binmode($fh, ":" . join(":",@to_apply)); } sub _name { my $glob = shift; no strict 'refs'; ## no critic return *{$glob}{NAME}; } sub _open { open $_[0], $_[1] or Carp::confess "Error from open(" . join(q{, }, @_) . "): $!"; # _debug( "# open " . join( ", " , map { defined $_ ? _name($_) : 'undef' } @_ ) . " as " . fileno( $_[0] ) . "\n" ); } sub _close { # _debug( "# closing " . ( defined $_[0] ? _name($_[0]) : 'undef' ) . " on " . fileno( $_[0] ) . "\n" ); close $_[0] or Carp::confess "Error from close(" . join(q{, }, @_) . "): $!"; } my %dup; # cache this so STDIN stays fd0 my %proxy_count; sub _proxy_std { my %proxies; if ( ! defined fileno STDIN ) { $proxy_count{stdin}++; if (defined $dup{stdin}) { _open \*STDIN, "<&=" . fileno($dup{stdin}); # _debug( "# restored proxy STDIN as " . (defined fileno STDIN ? fileno STDIN : 'undef' ) . "\n" ); } else { _open \*STDIN, "<" . File::Spec->devnull; # _debug( "# proxied STDIN as " . (defined fileno STDIN ? fileno STDIN : 'undef' ) . "\n" ); _open $dup{stdin} = IO::Handle->new, "<&=STDIN"; } $proxies{stdin} = \*STDIN; binmode(STDIN, ':utf8') if $] >= 5.008; ## no critic } if ( ! defined fileno STDOUT ) { $proxy_count{stdout}++; if (defined $dup{stdout}) { _open \*STDOUT, ">&=" . fileno($dup{stdout}); # _debug( "# restored proxy STDOUT as " . (defined fileno STDOUT ? fileno STDOUT : 'undef' ) . "\n" ); } else { _open \*STDOUT, ">" . File::Spec->devnull; # _debug( "# proxied STDOUT as " . (defined fileno STDOUT ? fileno STDOUT : 'undef' ) . "\n" ); _open $dup{stdout} = IO::Handle->new, ">&=STDOUT"; } $proxies{stdout} = \*STDOUT; binmode(STDOUT, ':utf8') if $] >= 5.008; ## no critic } if ( ! defined fileno STDERR ) { $proxy_count{stderr}++; if (defined $dup{stderr}) { _open \*STDERR, ">&=" . fileno($dup{stderr}); # _debug( "# restored proxy STDERR as " . (defined fileno STDERR ? fileno STDERR : 'undef' ) . "\n" ); } else { _open \*STDERR, ">" . File::Spec->devnull; # _debug( "# proxied STDERR as " . (defined fileno STDERR ? fileno STDERR : 'undef' ) . "\n" ); _open $dup{stderr} = IO::Handle->new, ">&=STDERR"; } $proxies{stderr} = \*STDERR; binmode(STDERR, ':utf8') if $] >= 5.008; ## no critic } return %proxies; } sub _unproxy { my (%proxies) = @_; # _debug( "# unproxying: " . join(" ", keys %proxies) . "\n" ); for my $p ( keys %proxies ) { $proxy_count{$p}--; # _debug( "# unproxied " . uc($p) . " ($proxy_count{$p} left)\n" ); if ( ! $proxy_count{$p} ) { _close $proxies{$p}; _close $dup{$p} unless $] < 5.008; # 5.6 will have already closed this as dup delete $dup{$p}; } } } sub _copy_std { my %handles; for my $h ( qw/stdout stderr stdin/ ) { next if $h eq 'stdin' && ! $IS_WIN32; # WIN32 hangs on tee without STDIN copied my $redir = $h eq 'stdin' ? "<&" : ">&"; _open $handles{$h} = IO::Handle->new(), $redir . uc($h); # ">&STDOUT" or "<&STDIN" } return \%handles; } # In some cases we open all (prior to forking) and in others we only open # the output handles (setting up redirection) sub _open_std { my ($handles) = @_; _open \*STDIN, "<&" . fileno $handles->{stdin} if defined $handles->{stdin}; _open \*STDOUT, ">&" . fileno $handles->{stdout} if defined $handles->{stdout}; _open \*STDERR, ">&" . fileno $handles->{stderr} if defined $handles->{stderr}; } #--------------------------------------------------------------------------# # private subs #--------------------------------------------------------------------------# sub _start_tee { my ($which, $stash) = @_; # $which is "stdout" or "stderr" # setup pipes $stash->{$_}{$which} = IO::Handle->new for qw/tee reader/; pipe $stash->{reader}{$which}, $stash->{tee}{$which}; # _debug( "# pipe for $which\: " . _name($stash->{tee}{$which}) . " " . fileno( $stash->{tee}{$which} ) . " => " . _name($stash->{reader}{$which}) . " " . fileno( $stash->{reader}{$which}) . "\n" ); select((select($stash->{tee}{$which}), $|=1)[0]); # autoflush # setup desired redirection for parent and child $stash->{new}{$which} = $stash->{tee}{$which}; $stash->{child}{$which} = { stdin => $stash->{reader}{$which}, stdout => $stash->{old}{$which}, stderr => $stash->{capture}{$which}, }; # flag file is used to signal the child is ready $stash->{flag_files}{$which} = scalar( tmpnam() ) . $$; # execute @cmd as a separate process if ( $IS_WIN32 ) { my $old_eval_err=$@; undef $@; eval "use Win32API::File qw/GetOsFHandle SetHandleInformation fileLastError HANDLE_FLAG_INHERIT INVALID_HANDLE_VALUE/ "; # _debug( "# Win32API::File loaded\n") unless $@; my $os_fhandle = GetOsFHandle( $stash->{tee}{$which} ); # _debug( "# Couldn't get OS handle: " . fileLastError() . "\n") if ! defined $os_fhandle || $os_fhandle == INVALID_HANDLE_VALUE(); my $result = SetHandleInformation( $os_fhandle, HANDLE_FLAG_INHERIT(), 0); # _debug( $result ? "# set no-inherit flag on $which tee\n" : ("# can't disable tee handle flag inherit: " . fileLastError() . "\n")); _open_std( $stash->{child}{$which} ); $stash->{pid}{$which} = system(1, @cmd, $stash->{flag_files}{$which}); # not restoring std here as it all gets redirected again shortly anyway $@=$old_eval_err; } else { # use fork _fork_exec( $which, $stash ); } } sub _fork_exec { my ($which, $stash) = @_; # $which is "stdout" or "stderr" my $pid = fork; if ( not defined $pid ) { Carp::confess "Couldn't fork(): $!"; } elsif ($pid == 0) { # child # _debug( "# in child process ...\n" ); untie *STDIN; untie *STDOUT; untie *STDERR; _close $stash->{tee}{$which}; # _debug( "# redirecting handles in child ...\n" ); _open_std( $stash->{child}{$which} ); # _debug( "# calling exec on command ...\n" ); exec @cmd, $stash->{flag_files}{$which}; } $stash->{pid}{$which} = $pid } my $have_usleep = eval "use Time::HiRes 'usleep'; 1"; sub _files_exist { return 1 if @_ == grep { -f } @_; Time::HiRes::usleep(1000) if $have_usleep; return 0; } sub _wait_for_tees { my ($stash) = @_; my $start = time; my @files = values %{$stash->{flag_files}}; my $timeout = defined $ENV{PERL_CAPTURE_TINY_TIMEOUT} ? $ENV{PERL_CAPTURE_TINY_TIMEOUT} : $TIMEOUT; 1 until _files_exist(@files) || ($timeout && (time - $start > $timeout)); Carp::confess "Timed out waiting for subprocesses to start" if ! _files_exist(@files); unlink $_ for @files; } sub _kill_tees { my ($stash) = @_; if ( $IS_WIN32 ) { # _debug( "# closing handles\n"); close($_) for values %{ $stash->{tee} }; # _debug( "# waiting for subprocesses to finish\n"); my $start = time; 1 until wait == -1 || (time - $start > 30); } else { _close $_ for values %{ $stash->{tee} }; waitpid $_, 0 for values %{ $stash->{pid} }; } } sub _slurp { my ($name, $stash) = @_; my ($fh, $pos) = map { $stash->{$_}{$name} } qw/capture pos/; # _debug( "# slurping captured $name from " . fileno($fh) . " at pos $pos with layers: @{[PerlIO::get_layers($fh)]}\n"); seek( $fh, $pos, 0 ) or die "Couldn't seek on capture handle for $name\n"; my $text = do { local $/; scalar readline $fh }; return defined($text) ? $text : ""; } #--------------------------------------------------------------------------# # _capture_tee() -- generic main sub for capturing or teeing #--------------------------------------------------------------------------# sub _capture_tee { # _debug( "# starting _capture_tee with (@_)...\n" ); my ($do_stdout, $do_stderr, $do_merge, $do_tee, $code, @opts) = @_; my %do = ($do_stdout ? (stdout => 1) : (), $do_stderr ? (stderr => 1) : ()); Carp::confess("Custom capture options must be given as key/value pairs\n") unless @opts % 2 == 0; my $stash = { capture => { @opts } }; for ( keys %{$stash->{capture}} ) { my $fh = $stash->{capture}{$_}; Carp::confess "Custom handle for $_ must be seekable\n" unless ref($fh) eq 'GLOB' || (blessed($fh) && $fh->isa("IO::Seekable")); } # save existing filehandles and setup captures local *CT_ORIG_STDIN = *STDIN ; local *CT_ORIG_STDOUT = *STDOUT; local *CT_ORIG_STDERR = *STDERR; # find initial layers my %layers = ( stdin => [PerlIO::get_layers(\*STDIN) ], stdout => [PerlIO::get_layers(\*STDOUT, output => 1)], stderr => [PerlIO::get_layers(\*STDERR, output => 1)], ); # _debug( "# existing layers for $_\: @{$layers{$_}}\n" ) for qw/stdin stdout stderr/; # get layers from underlying glob of tied filehandles if we can # (this only works for things that work like Tie::StdHandle) $layers{stdout} = [PerlIO::get_layers(tied *STDOUT)] if tied(*STDOUT) && (reftype tied *STDOUT eq 'GLOB'); $layers{stderr} = [PerlIO::get_layers(tied *STDERR)] if tied(*STDERR) && (reftype tied *STDERR eq 'GLOB'); # _debug( "# tied object corrected layers for $_\: @{$layers{$_}}\n" ) for qw/stdin stdout stderr/; # bypass scalar filehandles and tied handles # localize scalar STDIN to get a proxy to pick up FD0, then restore later to CT_ORIG_STDIN my %localize; $localize{stdin}++, local(*STDIN) if grep { $_ eq 'scalar' } @{$layers{stdin}}; $localize{stdout}++, local(*STDOUT) if $do_stdout && grep { $_ eq 'scalar' } @{$layers{stdout}}; $localize{stderr}++, local(*STDERR) if ($do_stderr || $do_merge) && grep { $_ eq 'scalar' } @{$layers{stderr}}; $localize{stdin}++, local(*STDIN), _open( \*STDIN, "<&=0") if tied *STDIN && $] >= 5.008; $localize{stdout}++, local(*STDOUT), _open( \*STDOUT, ">&=1") if $do_stdout && tied *STDOUT && $] >= 5.008; $localize{stderr}++, local(*STDERR), _open( \*STDERR, ">&=2") if ($do_stderr || $do_merge) && tied *STDERR && $] >= 5.008; # _debug( "# localized $_\n" ) for keys %localize; # proxy any closed/localized handles so we don't use fds 0, 1 or 2 my %proxy_std = _proxy_std(); # _debug( "# proxy std: @{ [%proxy_std] }\n" ); # update layers after any proxying $layers{stdout} = [PerlIO::get_layers(\*STDOUT, output => 1)] if $proxy_std{stdout}; $layers{stderr} = [PerlIO::get_layers(\*STDERR, output => 1)] if $proxy_std{stderr}; # _debug( "# post-proxy layers for $_\: @{$layers{$_}}\n" ) for qw/stdin stdout stderr/; # store old handles and setup handles for capture $stash->{old} = _copy_std(); $stash->{new} = { %{$stash->{old}} }; # default to originals for ( keys %do ) { $stash->{new}{$_} = ($stash->{capture}{$_} ||= File::Temp->new); seek( $stash->{capture}{$_}, 0, 2 ) or die "Could not seek on capture handle for $_\n"; $stash->{pos}{$_} = tell $stash->{capture}{$_}; # _debug("# will capture $_ on " . fileno($stash->{capture}{$_})."\n" ); _start_tee( $_ => $stash ) if $do_tee; # tees may change $stash->{new} } _wait_for_tees( $stash ) if $do_tee; # finalize redirection $stash->{new}{stderr} = $stash->{new}{stdout} if $do_merge; # _debug( "# redirecting in parent ...\n" ); _open_std( $stash->{new} ); # execute user provided code my ($exit_code, $inner_error, $outer_error, $orig_pid, @result); { $orig_pid = $$; local *STDIN = *CT_ORIG_STDIN if $localize{stdin}; # get original, not proxy STDIN # _debug( "# finalizing layers ...\n" ); _relayer(\*STDOUT, $layers{stdout}) if $do_stdout; _relayer(\*STDERR, $layers{stderr}) if $do_stderr; # _debug( "# running code $code ...\n" ); my $old_eval_err=$@; undef $@; eval { @result = $code->(); $inner_error = $@ }; $exit_code = $?; # save this for later $outer_error = $@; # save this for later STDOUT->flush if $do_stdout; STDERR->flush if $do_stderr; $@ = $old_eval_err; } # restore prior filehandles and shut down tees # _debug( "# restoring filehandles ...\n" ); _open_std( $stash->{old} ); _close( $_ ) for values %{$stash->{old}}; # don't leak fds # shouldn't need relayering originals, but see rt.perl.org #114404 _relayer(\*STDOUT, $layers{stdout}) if $do_stdout; _relayer(\*STDERR, $layers{stderr}) if $do_stderr; _unproxy( %proxy_std ); # _debug( "# killing tee subprocesses ...\n" ) if $do_tee; _kill_tees( $stash ) if $do_tee; # return captured output, but shortcut in void context # unless we have to echo output to tied/scalar handles; my %got; if ( $orig_pid == $$ and ( defined wantarray or ($do_tee && keys %localize) ) ) { for ( keys %do ) { _relayer($stash->{capture}{$_}, $layers{$_}); $got{$_} = _slurp($_, $stash); # _debug("# slurped " . length($got{$_}) . " bytes from $_\n"); } print CT_ORIG_STDOUT $got{stdout} if $do_stdout && $do_tee && $localize{stdout}; print CT_ORIG_STDERR $got{stderr} if $do_stderr && $do_tee && $localize{stderr}; } $? = $exit_code; $@ = $inner_error if $inner_error; die $outer_error if $outer_error; # _debug( "# ending _capture_tee with (@_)...\n" ); return unless defined wantarray; my @return; push @return, $got{stdout} if $do_stdout; push @return, $got{stderr} if $do_stderr && ! $do_merge; push @return, @result; return wantarray ? @return : $return[0]; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external programs =head1 VERSION version 0.48 =head1 SYNOPSIS use Capture::Tiny ':all'; # capture from external command ($stdout, $stderr, $exit) = capture { system( $cmd, @args ); }; # capture from arbitrary code (Perl or external) ($stdout, $stderr, @result) = capture { # your code here }; # capture partial or merged output $stdout = capture_stdout { ... }; $stderr = capture_stderr { ... }; $merged = capture_merged { ... }; # tee output ($stdout, $stderr) = tee { # your code here }; $stdout = tee_stdout { ... }; $stderr = tee_stderr { ... }; $merged = tee_merged { ... }; =head1 DESCRIPTION Capture::Tiny provides a simple, portable way to capture almost anything sent to STDOUT or STDERR, regardless of whether it comes from Perl, from XS code or from an external program. Optionally, output can be teed so that it is captured while being passed through to the original filehandles. Yes, it even works on Windows (usually). Stop guessing which of a dozen capturing modules to use in any particular situation and just use this one. =head1 USAGE The following functions are available. None are exported by default. =head2 capture ($stdout, $stderr, @result) = capture \&code; $stdout = capture \&code; The C<capture> function takes a code reference and returns what is sent to STDOUT and STDERR as well as any return values from the code reference. In scalar context, it returns only STDOUT. If no output was received for a filehandle, it returns an empty string for that filehandle. Regardless of calling context, all output is captured -- nothing is passed to the existing filehandles. It is prototyped to take a subroutine reference as an argument. Thus, it can be called in block form: ($stdout, $stderr) = capture { # your code here ... }; Note that the coderef is evaluated in list context. If you wish to force scalar context on the return value, you must use the C<scalar> keyword. ($stdout, $stderr, $count) = capture { my @list = qw/one two three/; return scalar @list; # $count will be 3 }; Also note that within the coderef, the C<@_> variable will be empty. So don't use arguments from a surrounding subroutine without copying them to an array first: sub wont_work { my ($stdout, $stderr) = capture { do_stuff( @_ ) }; # WRONG ... } sub will_work { my @args = @_; my ($stdout, $stderr) = capture { do_stuff( @args ) }; # RIGHT ... } Captures are normally done to an anonymous temporary filehandle. To capture via a named file (e.g. to externally monitor a long-running capture), provide custom filehandles as a trailing list of option pairs: my $out_fh = IO::File->new("out.txt", "w+"); my $err_fh = IO::File->new("out.txt", "w+"); capture { ... } stdout => $out_fh, stderr => $err_fh; The filehandles must be read/write and seekable. Modifying the files or filehandles during a capture operation will give unpredictable results. Existing IO layers on them may be changed by the capture. When called in void context, C<capture> saves memory and time by not reading back from the capture handles. =head2 capture_stdout ($stdout, @result) = capture_stdout \&code; $stdout = capture_stdout \&code; The C<capture_stdout> function works just like C<capture> except only STDOUT is captured. STDERR is not captured. =head2 capture_stderr ($stderr, @result) = capture_stderr \&code; $stderr = capture_stderr \&code; The C<capture_stderr> function works just like C<capture> except only STDERR is captured. STDOUT is not captured. =head2 capture_merged ($merged, @result) = capture_merged \&code; $merged = capture_merged \&code; The C<capture_merged> function works just like C<capture> except STDOUT and STDERR are merged. (Technically, STDERR is redirected to the same capturing handle as STDOUT before executing the function.) Caution: STDOUT and STDERR output in the merged result are not guaranteed to be properly ordered due to buffering. =head2 tee ($stdout, $stderr, @result) = tee \&code; $stdout = tee \&code; The C<tee> function works just like C<capture>, except that output is captured as well as passed on to the original STDOUT and STDERR. When called in void context, C<tee> saves memory and time by not reading back from the capture handles, except when the original STDOUT OR STDERR were tied or opened to a scalar handle. =head2 tee_stdout ($stdout, @result) = tee_stdout \&code; $stdout = tee_stdout \&code; The C<tee_stdout> function works just like C<tee> except only STDOUT is teed. STDERR is not teed (output goes to STDERR as usual). =head2 tee_stderr ($stderr, @result) = tee_stderr \&code; $stderr = tee_stderr \&code; The C<tee_stderr> function works just like C<tee> except only STDERR is teed. STDOUT is not teed (output goes to STDOUT as usual). =head2 tee_merged ($merged, @result) = tee_merged \&code; $merged = tee_merged \&code; The C<tee_merged> function works just like C<capture_merged> except that output is captured as well as passed on to STDOUT. Caution: STDOUT and STDERR output in the merged result are not guaranteed to be properly ordered due to buffering. =head1 LIMITATIONS =head2 Portability Portability is a goal, not a guarantee. C<tee> requires fork, except on Windows where C<system(1, @cmd)> is used instead. Not tested on any particularly esoteric platforms yet. See the L<CPAN Testers Matrix|http://matrix.cpantesters.org/?dist=Capture-Tiny> for test result by platform. =head2 PerlIO layers Capture::Tiny does its best to preserve PerlIO layers such as ':utf8' or ':crlf' when capturing (only for Perl 5.8.1+) . Layers should be applied to STDOUT or STDERR I<before> the call to C<capture> or C<tee>. This may not work for tied filehandles (see below). =head2 Modifying filehandles before capturing Generally speaking, you should do little or no manipulation of the standard IO filehandles prior to using Capture::Tiny. In particular, closing, reopening, localizing or tying standard filehandles prior to capture may cause a variety of unexpected, undesirable and/or unreliable behaviors, as described below. Capture::Tiny does its best to compensate for these situations, but the results may not be what you desire. =head3 Closed filehandles Capture::Tiny will work even if STDIN, STDOUT or STDERR have been previously closed. However, since they will be reopened to capture or tee output, any code within the captured block that depends on finding them closed will, of course, not find them to be closed. If they started closed, Capture::Tiny will close them again when the capture block finishes. Note that this reopening will happen even for STDIN or a filehandle not being captured to ensure that the filehandle used for capture is not opened to file descriptor 0, as this causes problems on various platforms. Prior to Perl 5.12, closed STDIN combined with PERL_UNICODE=D leaks filehandles and also breaks tee() for undiagnosed reasons. So don't do that. =head3 Localized filehandles If code localizes any of Perl's standard filehandles before capturing, the capture will affect the localized filehandles and not the original ones. External system calls are not affected by localizing a filehandle in Perl and will continue to send output to the original filehandles (which will thus not be captured). =head3 Scalar filehandles If STDOUT or STDERR are reopened to scalar filehandles prior to the call to C<capture> or C<tee>, then Capture::Tiny will override the output filehandle for the duration of the C<capture> or C<tee> call and then, for C<tee>, send captured output to the output filehandle after the capture is complete. (Requires Perl 5.8) Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar reference, but note that external processes will not be able to read from such a handle. Capture::Tiny tries to ensure that external processes will read from the null device instead, but this is not guaranteed. =head3 Tied output filehandles If STDOUT or STDERR are tied prior to the call to C<capture> or C<tee>, then Capture::Tiny will attempt to override the tie for the duration of the C<capture> or C<tee> call and then send captured output to the tied filehandle after the capture is complete. (Requires Perl 5.8) Capture::Tiny may not succeed resending UTF-8 encoded data to a tied STDOUT or STDERR filehandle. Characters may appear as bytes. If the tied filehandle is based on L<Tie::StdHandle>, then Capture::Tiny will attempt to determine appropriate layers like C<:utf8> from the underlying filehandle and do the right thing. =head3 Tied input filehandle Capture::Tiny attempts to preserve the semantics of tied STDIN, but this requires Perl 5.8 and is not entirely predictable. External processes will not be able to read from such a handle. Unless having STDIN tied is crucial, it may be safest to localize STDIN when capturing: my ($out, $err) = do { local *STDIN; capture { ... } }; =head2 Modifying filehandles during a capture Attempting to modify STDIN, STDOUT or STDERR I<during> C<capture> or C<tee> is almost certainly going to cause problems. Don't do that. =head3 Forking inside a capture Forks aren't portable. The behavior of filehandles during a fork is even less so. If Capture::Tiny detects that a fork has occurred within a capture, it will shortcut in the child process and return empty strings for captures. Other problems may occur in the child or parent, as well. Forking in a capture block is not recommended. =head3 Using threads Filehandles are global. Mixing up I/O and captures in different threads without coordination is going to cause problems. Besides, threads are officially discouraged. =head3 Dropping privileges during a capture If you drop privileges during a capture, temporary files created to facilitate the capture may not be cleaned up afterwards. =head2 No support for Perl 5.8.0 It's just too buggy when it comes to layers and UTF-8. Perl 5.8.1 or later is recommended. =head2 Limited support for Perl 5.6 Perl 5.6 predates PerlIO. UTF-8 data may not be captured correctly. =head1 ENVIRONMENT =head2 PERL_CAPTURE_TINY_TIMEOUT Capture::Tiny uses subprocesses internally for C<tee>. By default, Capture::Tiny will timeout with an error if such subprocesses are not ready to receive data within 30 seconds (or whatever is the value of C<$Capture::Tiny::TIMEOUT>). An alternate timeout may be specified by setting the C<PERL_CAPTURE_TINY_TIMEOUT> environment variable. Setting it to zero will disable timeouts. B<NOTE>, this does not timeout the code reference being captured -- this only prevents Capture::Tiny itself from hanging your process waiting for its child processes to be ready to proceed. =head1 SEE ALSO This module was inspired by L<IO::CaptureOutput>, which provides similar functionality without the ability to tee output and with more complicated code and API. L<IO::CaptureOutput> does not handle layers or most of the unusual cases described in the L</Limitations> section and I no longer recommend it. There are many other CPAN modules that provide some sort of output capture, albeit with various limitations that make them appropriate only in particular circumstances. I'm probably missing some. The long list is provided to show why I felt Capture::Tiny was necessary. =over 4 =item * L<IO::Capture> =item * L<IO::Capture::Extended> =item * L<IO::CaptureOutput> =item * L<IPC::Capture> =item * L<IPC::Cmd> =item * L<IPC::Open2> =item * L<IPC::Open3> =item * L<IPC::Open3::Simple> =item * L<IPC::Open3::Utils> =item * L<IPC::Run> =item * L<IPC::Run::SafeHandles> =item * L<IPC::Run::Simple> =item * L<IPC::Run3> =item * L<IPC::System::Simple> =item * L<Tee> =item * L<IO::Tee> =item * L<File::Tee> =item * L<Filter::Handle> =item * L<Tie::STDERR> =item * L<Tie::STDOUT> =item * L<Test::Output> =back =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan =head1 SUPPORT =head2 Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at L<https://github.com/dagolden/Capture-Tiny/issues>. You will be notified automatically of any progress on your issue. =head2 Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. L<https://github.com/dagolden/Capture-Tiny> git clone https://github.com/dagolden/Capture-Tiny.git =head1 AUTHOR David Golden <dagolden@cpan.org> =head1 CONTRIBUTORS =for stopwords Dagfinn Ilmari Mannsåker David E. Wheeler fecundf Graham Knop Peter Rabbitson =over 4 =item * Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> =item * David E. Wheeler <david@justatheory.com> =item * fecundf <not.com+github@gmail.com> =item * Graham Knop <haarg@haarg.org> =item * Peter Rabbitson <ribasushi@cpan.org> =back =head1 COPYRIGHT AND LICENSE This software is Copyright (c) 2009 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 =cut PK ) �[���Q' Q' man3/HTTP::CookieJar.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::CookieJar 3" .TH HTTP::CookieJar 3 "2022-07-25" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::CookieJar \- A minimalist HTTP user agent cookie jar .SH "VERSION" .IX Header "VERSION" version 0.014 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use HTTP::CookieJar; \& \& my $jar = HTTP::CookieJar\->new; \& \& # add cookie received from a request \& $jar\->add( "http://www.example.com/", "CUSTOMER=WILE_E_COYOTE; Path=/; Domain=example.com" ); \& \& # extract cookie header for a given request \& my $cookie = $jar\->cookie_header( "http://www.example.com/" ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a minimalist \s-1HTTP\s0 user agent cookie jar in conformance with \s-1RFC 6265\s0 <http://tools.ietf.org/html/rfc6265>. .PP Unlike the commonly used HTTP::Cookies module, this module does not require use of HTTP::Request and HTTP::Response objects. An LWP-compatible adapter is available as HTTP::CookieJar::LWP. .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" .SS "new" .IX Subsection "new" .Vb 1 \& my $jar = HTTP::CookieJar\->new; .Ve .PP Return a new, empty cookie jar .SH "METHODS" .IX Header "METHODS" .SS "add" .IX Subsection "add" .Vb 3 \& $jar\->add( \& "http://www.example.com/", "lang=en\-US; Path=/; Domain=example.com" \& ); .Ve .PP Given a request \s-1URL\s0 and a \f(CW\*(C`Set\-Cookie\*(C'\fR header string, attempts to adds the cookie to the jar. If the cookie is expired, instead it deletes any matching cookie from the jar. A \f(CW\*(C`Max\-Age\*(C'\fR attribute will be converted to an absolute \&\f(CW\*(C`Expires\*(C'\fR attribute. .PP It will throw an exception if the request \s-1URL\s0 is missing or invalid. Returns true if successful cookie processing or undef/empty\-list on failure. .SS "clear" .IX Subsection "clear" .Vb 1 \& $jar\->clear .Ve .PP Empties the cookie jar. .SS "cookies_for" .IX Subsection "cookies_for" .Vb 1 \& my @cookies = $jar\->cookies_for("http://www.example.com/foo/bar"); .Ve .PP Given a request \s-1URL,\s0 returns a list of hash references representing cookies that should be sent. The hash references are copies \*(-- changing values will not change the cookies in the jar. .PP Cookies set \f(CW\*(C`secure\*(C'\fR will only be returned if the request scheme is \f(CW\*(C`https\*(C'\fR. Expired cookies will not be returned. .PP Keys of a cookie hash reference might include: .IP "\(bu" 4 name \*(-- the name of the cookie .IP "\(bu" 4 value \*(-- the value of the cookie .IP "\(bu" 4 domain \*(-- the domain name to which the cookie applies .IP "\(bu" 4 path \*(-- the path to which the cookie applies .IP "\(bu" 4 expires \*(-- if present, when the cookie expires in epoch seconds .IP "\(bu" 4 secure \*(-- if present, the cookie was set \f(CW\*(C`Secure\*(C'\fR .IP "\(bu" 4 httponly \*(-- if present, the cookie was set \f(CW\*(C`HttpOnly\*(C'\fR .IP "\(bu" 4 hostonly \*(-- if present, the cookie may only be used with the domain as a host .IP "\(bu" 4 creation_time \*(-- epoch time when the cookie was first stored .IP "\(bu" 4 last_access_time \*(-- epoch time when the cookie was last accessed (i.e. \*(L"now\*(R") .PP Keep in mind that \f(CW\*(C`httponly\*(C'\fR means it should only be used in requests and not made available via Javascript, etc. This is pretty meaningless for Perl user agents. .PP Generally, user agents should use the \f(CW\*(C`cookie_header\*(C'\fR method instead. .PP It will throw an exception if the request \s-1URL\s0 is missing or invalid. .SS "cookie_header" .IX Subsection "cookie_header" .Vb 1 \& my $header = $jar\->cookie_header("http://www.example.com/foo/bar"); .Ve .PP Given a request \s-1URL,\s0 returns a correctly-formatted string with all relevant cookies for the request. This string is ready to be used in a \f(CW\*(C`Cookie\*(C'\fR header in an \s-1HTTP\s0 request. E.g.: .PP .Vb 1 \& SID=31d4d96e407aad42; lang=en\-US .Ve .PP It follows the same exclusion rules as \f(CW\*(C`cookies_for\*(C'\fR. .PP If the request is invalid or no cookies apply, it will return an empty string. .SS "dump_cookies" .IX Subsection "dump_cookies" .Vb 2 \& my @list = $jar\->dump_cookies; \& my @list = $jar\->dump_cookies( { persistent => 1 } ); .Ve .PP Returns a list of raw cookies in string form. The strings resemble what would be received from \f(CW\*(C`Set\-Cookie\*(C'\fR headers, but with additional internal fields. The list is only intended for use with \f(CW\*(C`load_cookies\*(C'\fR to allow cookie jar persistence. .PP If a hash reference with a true \f(CW\*(C`persistent\*(C'\fR key is given as an argument, cookies without an \f(CW\*(C`Expires\*(C'\fR time (i.e. \*(L"session cookies\*(R") will be omitted. .PP Here is a trivial example of saving a cookie jar file with Path::Tiny: .PP .Vb 1 \& path("jar.txt")\->spew( join "\en", $jar\->dump_cookies ); .Ve .SS "load_cookies" .IX Subsection "load_cookies" .Vb 1 \& $jar\->load_cookies( @cookies ); .Ve .PP Given a list of cookie strings from \f(CW\*(C`dump_cookies\*(C'\fR, it adds them to the cookie jar. Cookies added in this way will supersede any existing cookies with similar domain, path and name. .PP It returns the jar object for convenience when loading a new object: .PP .Vb 1 \& my $jar = HTTP::CookieJar\->new\->load_cookies( @cookies ); .Ve .PP Here is a trivial example of loading a cookie jar file with Path::Tiny: .PP .Vb 3 \& my $jar = HTTP::CookieJar\->new\->load_cookies( \& path("jar.txt")\->lines \& ); .Ve .SH "LIMITATIONS AND CAVEATS" .IX Header "LIMITATIONS AND CAVEATS" .SS "\s-1RFC 6265\s0 vs prior standards" .IX Subsection "RFC 6265 vs prior standards" This modules adheres as closely as possible to the user-agent rules of \s-1RFC 6265.\s0 Therefore, it does not handle nor generate \f(CW\*(C`Set\-Cookie2\*(C'\fR and \f(CW\*(C`Cookie2\*(C'\fR headers, implement \f(CW\*(C`.local\*(C'\fR suffixes, or do path/domain matching in accord with prior \s-1RFC\s0's. .SS "Internationalized domain names" .IX Subsection "Internationalized domain names" Internationalized domain names given in requests must be properly encoded in \s-1ASCII\s0 form. .SS "Public suffixes" .IX Subsection "Public suffixes" If Mozilla::PublicSuffix is installed, cookie domains will be checked against the public suffix list. Public suffix cookies are only allowed as host-only cookies. .SS "Third-party cookies" .IX Subsection "Third-party cookies" According to \s-1RFC 6265,\s0 a cookie may be accepted only if has no \f(CW\*(C`Domain\*(C'\fR attribute (in which case it is \*(L"host-only\*(R") or if the \f(CW\*(C`Domain\*(C'\fR attribute is a suffix of the request \s-1URL.\s0 This effectively prohibits Site A from setting a cookie for unrelated Site B, which is one potential third-party cookie vector. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 HTTP::Cookies .IP "\(bu" 4 Mojo::UserAgent::CookieJar .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/HTTP\-CookieJar/issues>. You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP <https://github.com/dagolden/HTTP\-CookieJar> .PP .Vb 1 \& git clone https://github.com/dagolden/HTTP\-CookieJar.git .Ve .SH "AUTHOR" .IX Header "AUTHOR" David Golden <dagolden@cpan.org> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Dan Book <grinnz@grinnz.com> .IP "\(bu" 4 David Golden <xdg@xdg.me> .IP "\(bu" 4 jvolkening <jdv@base2bio.com> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2013 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve PK ) �[��CA A man3/HTTP::CookieJar::LWP.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::CookieJar::LWP 3" .TH HTTP::CookieJar::LWP 3 "2022-07-25" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::CookieJar::LWP \- LWP adapter for HTTP::CookieJar .SH "VERSION" .IX Header "VERSION" version 0.014 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use LWP::UserAgent; \& use HTTP::CookieJar::LWP; \& \& my $ua = LWP::UserAgent\->new( \& cookie_jar => HTTP::CookieJar::LWP\->new \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is an experimental adapter to make HTTP::CookieJar work with \&\s-1LWP\s0. It implements the two methods that \f(CW\*(C`LWP\*(C'\fR calls from HTTP::Cookies. .PP It is not a general-purpose drop-in replacement for \f(CW\*(C`HTTP::Cookies\*(C'\fR in any other way. .SH "AUTHOR" .IX Header "AUTHOR" David Golden <dagolden@cpan.org> .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2013 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve PK ) �[ arch/auto/HTTP/CookieJar/.existsnu �[��� PK ) �[Q���sK sK lib/HTTP/CookieJar.pmnu ��6�$ use 5.008001; use strict; use warnings; package HTTP::CookieJar; # ABSTRACT: A minimalist HTTP user agent cookie jar our $VERSION = '0.014'; use Carp (); use HTTP::Date (); my $HAS_MPS = eval { require Mozilla::PublicSuffix; 1 }; #pod =construct new #pod #pod my $jar = HTTP::CookieJar->new; #pod #pod Return a new, empty cookie jar #pod #pod =cut sub new { my ($class) = @_; bless { store => {} }, $class; } #pod =method add #pod #pod $jar->add( #pod "http://www.example.com/", "lang=en-US; Path=/; Domain=example.com" #pod ); #pod #pod Given a request URL and a C<Set-Cookie> header string, attempts to adds the #pod cookie to the jar. If the cookie is expired, instead it deletes any matching #pod cookie from the jar. A C<Max-Age> attribute will be converted to an absolute #pod C<Expires> attribute. #pod #pod It will throw an exception if the request URL is missing or invalid. Returns true if #pod successful cookie processing or undef/empty-list on failure. #pod #pod =cut sub add { my ( $self, $request, $cookie ) = @_; return unless defined $cookie and length $cookie; my ( $scheme, $host, $port, $request_path ) = eval { _split_url($request) }; Carp::croak($@) if $@; return unless my $parse = _parse_cookie($cookie); my $name = $parse->{name}; # check and normalize domain if ( exists $parse->{domain} ) { _normalize_domain( $host, $parse ) or return; } else { $parse->{domain} = $host; $parse->{hostonly} = 1; } my $domain = $parse->{domain}; # normalize path if ( !exists $parse->{path} || substr( $parse->{path}, 0, 1 ) ne "/" ) { $parse->{path} = _default_path($request_path); } my $path = $parse->{path}; # set timestamps and normalize expires my $now = $parse->{creation_time} = $parse->{last_access_time} = time; if ( exists $parse->{'max-age'} ) { # "If delta-seconds is less than or equal to zero (0), let expiry-time # be the earliest representable date and time." $parse->{expires} = $parse->{'max-age'} <= 0 ? 0 : $now + $parse->{'max-age'}; delete $parse->{'max-age'}; } # update creation time from old cookie, if exists if ( my $old = $self->{store}{$domain}{$path}{$name} ) { $parse->{creation_time} = $old->{creation_time}; } # if cookie has expired, purge any old matching cookie, too if ( defined $parse->{expires} && $parse->{expires} < $now ) { delete $self->{store}{$domain}{$path}{$name}; } else { $self->{store}{$domain}{$path}{$name} = $parse; } return 1; } #pod =method clear #pod #pod $jar->clear #pod #pod Empties the cookie jar. #pod #pod =cut sub clear { my ($self) = @_; $self->{store} = {}; return 1; } #pod =method cookies_for #pod #pod my @cookies = $jar->cookies_for("http://www.example.com/foo/bar"); #pod #pod Given a request URL, returns a list of hash references representing cookies #pod that should be sent. The hash references are copies -- changing values #pod will not change the cookies in the jar. #pod #pod Cookies set C<secure> will only be returned if the request scheme is C<https>. #pod Expired cookies will not be returned. #pod #pod Keys of a cookie hash reference might include: #pod #pod =for :list #pod * name -- the name of the cookie #pod * value -- the value of the cookie #pod * domain -- the domain name to which the cookie applies #pod * path -- the path to which the cookie applies #pod * expires -- if present, when the cookie expires in epoch seconds #pod * secure -- if present, the cookie was set C<Secure> #pod * httponly -- if present, the cookie was set C<HttpOnly> #pod * hostonly -- if present, the cookie may only be used with the domain as a host #pod * creation_time -- epoch time when the cookie was first stored #pod * last_access_time -- epoch time when the cookie was last accessed (i.e. "now") #pod #pod Keep in mind that C<httponly> means it should only be used in requests and not #pod made available via Javascript, etc. This is pretty meaningless for Perl user #pod agents. #pod #pod Generally, user agents should use the C<cookie_header> method instead. #pod #pod It will throw an exception if the request URL is missing or invalid. #pod #pod =cut sub cookies_for { my ( $self, $request ) = @_; my @found = $self->_cookies_for($request); return map { {%$_} } @found; } # _cookies_for returns originals, not copies, which helps in testing sub _cookies_for { my ( $self, $request ) = @_; my ( $scheme, $host, $port, $request_path ) = eval { _split_url($request) }; Carp::croak($@) if $@; my @found; my $now = time; for my $cookie ( $self->_all_cookies ) { next if $cookie->{hostonly} && $host ne $cookie->{domain}; next if $cookie->{secure} && $scheme ne 'https'; next if defined( $cookie->{expires} ) && $cookie->{expires} < $now; next unless _domain_match( $host, $cookie->{domain} ); next unless _path_match( $request_path, $cookie->{path} ); $cookie->{last_access_time} = time; push @found, $cookie; } @found = sort { length( $b->{path} ) <=> length( $a->{path} ) || $a->{creation_time} <=> $b->{creation_time} } @found; return @found; } #pod =method cookie_header #pod #pod my $header = $jar->cookie_header("http://www.example.com/foo/bar"); #pod #pod Given a request URL, returns a correctly-formatted string with all relevant #pod cookies for the request. This string is ready to be used in a C<Cookie> header #pod in an HTTP request. E.g.: #pod #pod SID=31d4d96e407aad42; lang=en-US #pod #pod It follows the same exclusion rules as C<cookies_for>. #pod #pod If the request is invalid or no cookies apply, it will return an empty string. #pod #pod =cut sub cookie_header { my ( $self, $req ) = @_; return join( "; ", map { "$_->{name}=$_->{value}" } $self->cookies_for($req) ); } #pod =method dump_cookies #pod #pod my @list = $jar->dump_cookies; #pod my @list = $jar->dump_cookies( { persistent => 1 } ); #pod #pod Returns a list of raw cookies in string form. The strings resemble what #pod would be received from C<Set-Cookie> headers, but with additional internal #pod fields. The list is only intended for use with C<load_cookies> to allow #pod cookie jar persistence. #pod #pod If a hash reference with a true C<persistent> key is given as an argument, #pod cookies without an C<Expires> time (i.e. "session cookies") will be omitted. #pod #pod Here is a trivial example of saving a cookie jar file with L<Path::Tiny>: #pod #pod path("jar.txt")->spew( join "\n", $jar->dump_cookies ); #pod #pod =cut sub dump_cookies { my ( $self, $args ) = @_; my @list; for my $c ( $self->_all_cookies ) { my @parts = "$c->{name}=$c->{value}"; if ( defined $c->{expires} ) { push @parts, 'Expires=' . HTTP::Date::time2str( $c->{expires} ); } else { next if $args->{persistent}; } for my $attr (qw/Domain Path Creation_Time Last_Access_Time/) { push @parts, "$attr=$c->{lc $attr}" if defined $c->{ lc $attr }; } for my $attr (qw/Secure HttpOnly HostOnly/) { push @parts, $attr if $c->{ lc $attr }; } push @list, join( "; ", @parts ); } return @list; } #pod =method load_cookies #pod #pod $jar->load_cookies( @cookies ); #pod #pod Given a list of cookie strings from C<dump_cookies>, it adds them to #pod the cookie jar. Cookies added in this way will supersede any existing #pod cookies with similar domain, path and name. #pod #pod It returns the jar object for convenience when loading a new object: #pod #pod my $jar = HTTP::CookieJar->new->load_cookies( @cookies ); #pod #pod Here is a trivial example of loading a cookie jar file with L<Path::Tiny>: #pod #pod my $jar = HTTP::CookieJar->new->load_cookies( #pod path("jar.txt")->lines #pod ); #pod #pod =cut sub load_cookies { my ( $self, @cookies ) = @_; for my $cookie (@cookies) { my $p = _parse_cookie( $cookie, 1 ); next unless exists $p->{domain} && exists $p->{path}; $p->{$_} = time for grep { !defined $p->{$_} } qw/creation_time last_access_time/; $self->{store}{ $p->{domain} }{ $p->{path} }{ $p->{name} } = $p; } return $self; } #--------------------------------------------------------------------------# # private methods #--------------------------------------------------------------------------# # return flattened list of all cookies sub _all_cookies { return map { values %$_ } map { values %$_ } values %{ $_[0]->{store} }; } #--------------------------------------------------------------------------# # Helper subroutines #--------------------------------------------------------------------------# my $pub_re = qr/(?:domain|path|expires|max-age|httponly|secure)/; my $pvt_re = qr/(?:$pub_re|creation_time|last_access_time|hostonly)/; sub _parse_cookie { my ( $cookie, $private ) = @_; $cookie = '' unless defined $cookie; my ( $kvp, @attrs ) = split /;/, $cookie; $kvp = '' unless defined $kvp; my ( $name, $value ) = map { s/^\s*//; s/\s*$//; $_ } split( /=/, $kvp, 2 ); ## no critic return unless defined $name and length $name; $value = '' unless defined $value; my $parse = { name => $name, value => $value }; for my $s (@attrs) { next unless defined $s && $s =~ /\S/; my ( $k, $v ) = map { s/^\s*//; s/\s*$//; $_ } split( /=/, $s, 2 ); ## no critic $k = lc $k; next unless $private ? ( $k =~ m/^$pvt_re$/ ) : ( $k =~ m/^$pub_re$/ ); $v = 1 if $k =~ m/^(?:httponly|secure|hostonly)$/; # boolean flag if present $v = HTTP::Date::str2time($v) || 0 if $k eq 'expires'; # convert to epoch next unless length $v; $v =~ s{^\.}{} if $k eq 'domain'; # strip leading dot $v =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg if $k eq 'path'; # unescape $parse->{$k} = $v; } return $parse; } sub _domain_match { my ( $string, $dom_string ) = @_; return 1 if $dom_string eq $string; return unless $string =~ /[a-z]/i; # non-numeric if ( $string =~ s{\Q$dom_string\E$}{} ) { return substr( $string, -1, 1 ) eq '.'; # "foo." } return; } sub _normalize_domain { my ( $host, $parse ) = @_; if ($HAS_MPS) { my $host_pub_suff = eval { Mozilla::PublicSuffix::public_suffix($host) }; $host_pub_suff = '' unless defined $host_pub_suff; if ( _domain_match( $host_pub_suff, $parse->{domain} ) ) { if ( $parse->{domain} eq $host ) { return $parse->{hostonly} = 1; } else { return; } } } if ( $parse->{domain} !~ m{\.} && $parse->{domain} eq $host ) { return $parse->{hostonly} = 1; } return _domain_match( $host, $parse->{domain} ); } sub _default_path { my ($path) = @_; return "/" if !length $path || substr( $path, 0, 1 ) ne "/"; my ($default) = $path =~ m{^(.*)/}; # greedy to last / return length($default) ? $default : "/"; } sub _path_match { my ( $req_path, $cookie_path ) = @_; return 1 if $req_path eq $cookie_path; if ( $req_path =~ m{^\Q$cookie_path\E(.*)} ) { my $rest = $1; return 1 if substr( $cookie_path, -1, 1 ) eq '/'; return 1 if substr( $rest, 0, 1 ) eq '/'; } return; } sub _split_url { my $url = shift; die(qq/No URL provided\n/) unless defined $url and length $url; # URI regex adapted from the URI module # XXX path_query here really chops at ? or # to get just the path and not the query my ( $scheme, $authority, $path_query ) = $url =~ m<\A([^:/?#]+)://([^/?#]*)([^#?]*)> or die(qq/Cannot parse URL: '$url'\n/); $scheme = lc $scheme; $path_query = "/$path_query" unless $path_query =~ m<\A/>; $path_query =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; my $host = ( length($authority) ) ? lc $authority : 'localhost'; $host =~ s/\A[^@]*@//; # userinfo my $port = do { $host =~ s/:([0-9]*)\z// && length $1 ? $1 : ( $scheme eq 'http' ? 80 : $scheme eq 'https' ? 443 : undef ); }; return ( $scheme, $host, $port, $path_query ); } 1; # vim: ts=4 sts=4 sw=4 et: __END__ =pod =encoding UTF-8 =head1 NAME HTTP::CookieJar - A minimalist HTTP user agent cookie jar =head1 VERSION version 0.014 =head1 SYNOPSIS use HTTP::CookieJar; my $jar = HTTP::CookieJar->new; # add cookie received from a request $jar->add( "http://www.example.com/", "CUSTOMER=WILE_E_COYOTE; Path=/; Domain=example.com" ); # extract cookie header for a given request my $cookie = $jar->cookie_header( "http://www.example.com/" ); =head1 DESCRIPTION This module implements a minimalist HTTP user agent cookie jar in conformance with L<RFC 6265|http://tools.ietf.org/html/rfc6265>. Unlike the commonly used L<HTTP::Cookies> module, this module does not require use of L<HTTP::Request> and L<HTTP::Response> objects. An LWP-compatible adapter is available as L<HTTP::CookieJar::LWP>. =head1 CONSTRUCTORS =head2 new my $jar = HTTP::CookieJar->new; Return a new, empty cookie jar =head1 METHODS =head2 add $jar->add( "http://www.example.com/", "lang=en-US; Path=/; Domain=example.com" ); Given a request URL and a C<Set-Cookie> header string, attempts to adds the cookie to the jar. If the cookie is expired, instead it deletes any matching cookie from the jar. A C<Max-Age> attribute will be converted to an absolute C<Expires> attribute. It will throw an exception if the request URL is missing or invalid. Returns true if successful cookie processing or undef/empty-list on failure. =head2 clear $jar->clear Empties the cookie jar. =head2 cookies_for my @cookies = $jar->cookies_for("http://www.example.com/foo/bar"); Given a request URL, returns a list of hash references representing cookies that should be sent. The hash references are copies -- changing values will not change the cookies in the jar. Cookies set C<secure> will only be returned if the request scheme is C<https>. Expired cookies will not be returned. Keys of a cookie hash reference might include: =over 4 =item * name -- the name of the cookie =item * value -- the value of the cookie =item * domain -- the domain name to which the cookie applies =item * path -- the path to which the cookie applies =item * expires -- if present, when the cookie expires in epoch seconds =item * secure -- if present, the cookie was set C<Secure> =item * httponly -- if present, the cookie was set C<HttpOnly> =item * hostonly -- if present, the cookie may only be used with the domain as a host =item * creation_time -- epoch time when the cookie was first stored =item * last_access_time -- epoch time when the cookie was last accessed (i.e. "now") =back Keep in mind that C<httponly> means it should only be used in requests and not made available via Javascript, etc. This is pretty meaningless for Perl user agents. Generally, user agents should use the C<cookie_header> method instead. It will throw an exception if the request URL is missing or invalid. =head2 cookie_header my $header = $jar->cookie_header("http://www.example.com/foo/bar"); Given a request URL, returns a correctly-formatted string with all relevant cookies for the request. This string is ready to be used in a C<Cookie> header in an HTTP request. E.g.: SID=31d4d96e407aad42; lang=en-US It follows the same exclusion rules as C<cookies_for>. If the request is invalid or no cookies apply, it will return an empty string. =head2 dump_cookies my @list = $jar->dump_cookies; my @list = $jar->dump_cookies( { persistent => 1 } ); Returns a list of raw cookies in string form. The strings resemble what would be received from C<Set-Cookie> headers, but with additional internal fields. The list is only intended for use with C<load_cookies> to allow cookie jar persistence. If a hash reference with a true C<persistent> key is given as an argument, cookies without an C<Expires> time (i.e. "session cookies") will be omitted. Here is a trivial example of saving a cookie jar file with L<Path::Tiny>: path("jar.txt")->spew( join "\n", $jar->dump_cookies ); =head2 load_cookies $jar->load_cookies( @cookies ); Given a list of cookie strings from C<dump_cookies>, it adds them to the cookie jar. Cookies added in this way will supersede any existing cookies with similar domain, path and name. It returns the jar object for convenience when loading a new object: my $jar = HTTP::CookieJar->new->load_cookies( @cookies ); Here is a trivial example of loading a cookie jar file with L<Path::Tiny>: my $jar = HTTP::CookieJar->new->load_cookies( path("jar.txt")->lines ); =for Pod::Coverage method_names_here =head1 LIMITATIONS AND CAVEATS =head2 RFC 6265 vs prior standards This modules adheres as closely as possible to the user-agent rules of RFC 6265. Therefore, it does not handle nor generate C<Set-Cookie2> and C<Cookie2> headers, implement C<.local> suffixes, or do path/domain matching in accord with prior RFC's. =head2 Internationalized domain names Internationalized domain names given in requests must be properly encoded in ASCII form. =head2 Public suffixes If L<Mozilla::PublicSuffix> is installed, cookie domains will be checked against the public suffix list. Public suffix cookies are only allowed as host-only cookies. =head2 Third-party cookies According to RFC 6265, a cookie may be accepted only if has no C<Domain> attribute (in which case it is "host-only") or if the C<Domain> attribute is a suffix of the request URL. This effectively prohibits Site A from setting a cookie for unrelated Site B, which is one potential third-party cookie vector. =head1 SEE ALSO =over 4 =item * L<HTTP::Cookies> =item * L<Mojo::UserAgent::CookieJar> =back =for :stopwords cpan testmatrix url bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan =head1 SUPPORT =head2 Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at L<https://github.com/dagolden/HTTP-CookieJar/issues>. You will be notified automatically of any progress on your issue. =head2 Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. L<https://github.com/dagolden/HTTP-CookieJar> git clone https://github.com/dagolden/HTTP-CookieJar.git =head1 AUTHOR David Golden <dagolden@cpan.org> =head1 CONTRIBUTORS =for stopwords Dan Book David Golden jvolkening =over 4 =item * Dan Book <grinnz@grinnz.com> =item * David Golden <xdg@xdg.me> =item * jvolkening <jdv@base2bio.com> =back =head1 COPYRIGHT AND LICENSE This software is Copyright (c) 2013 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 =cut PK ) �[T�M�+ + lib/HTTP/CookieJar/LWP.pmnu ��6�$ use 5.008001; use strict; use warnings; package HTTP::CookieJar::LWP; # ABSTRACT: LWP adapter for HTTP::CookieJar our $VERSION = '0.014'; use parent 'HTTP::CookieJar'; sub add_cookie_header { my ( $self, $request ) = @_; my $url = _get_url( $request, $request->uri ); return unless ( $url->scheme =~ /^https?\z/ ); my $header = $self->cookie_header($url); $request->header( Cookie => $header ); return $request; } sub extract_cookies { my ( $self, $response ) = @_; my $request = $response->request or return; my $url = _get_url( $request, $request->uri ); $self->add( $url, $_ ) for $response->_header("Set-Cookie"); return $response; } #--------------------------------------------------------------------------# # helper subroutines #--------------------------------------------------------------------------# sub _get_url { my ( $request, $url ) = @_; my $new_url = $url->clone; if ( my $h = $request->header("Host") ) { $h =~ s/:\d+$//; # might have a port as well $new_url->host($h); } return $new_url; } sub _url_path { my $url = shift; my $path; if ( $url->can('epath') ) { $path = $url->epath; # URI::URL method } else { $path = $url->path; # URI::_generic method } $path = "/" unless length $path; $path; } sub _normalize_path # so that plain string compare can be used { my $x; $_[0] =~ s/%([0-9a-fA-F][0-9a-fA-F])/ $x = uc($1); $x eq "2F" || $x eq "25" ? "%$x" : pack("C", hex($x)); /eg; $_[0] =~ s/([\0-\x20\x7f-\xff])/sprintf("%%%02X",ord($1))/eg; } 1; # vim: ts=4 sts=4 sw=4 et: __END__ =pod =encoding UTF-8 =head1 NAME HTTP::CookieJar::LWP - LWP adapter for HTTP::CookieJar =head1 VERSION version 0.014 =head1 SYNOPSIS use LWP::UserAgent; use HTTP::CookieJar::LWP; my $ua = LWP::UserAgent->new( cookie_jar => HTTP::CookieJar::LWP->new ); =head1 DESCRIPTION This module is an experimental adapter to make L<HTTP::CookieJar> work with L<LWP>. It implements the two methods that C<LWP> calls from L<HTTP::Cookies>. It is not a general-purpose drop-in replacement for C<HTTP::Cookies> in any other way. =for Pod::Coverage method_names_here add_cookie_header extract_cookies =head1 AUTHOR David Golden <dagolden@cpan.org> =head1 COPYRIGHT AND LICENSE This software is Copyright (c) 2013 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 =cut PK ) �[ lib/auto/HTTP/CookieJar/.existsnu �[��� PK 0 �[E���= �= man3/Test::Warnings.3pmnu �[��� .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Warnings 3" .TH Test::Warnings 3 "2024-01-23" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Warnings \- Test for warnings and the lack of them .SH "VERSION" .IX Header "VERSION" version 0.033 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Test::More; \& use Test::Warnings; \& \& pass(\*(Aqyay!\*(Aq); \& done_testing; .Ve .PP emits \s-1TAP:\s0 .PP .Vb 3 \& ok 1 \- yay! \& ok 2 \- no (unexpected) warnings (via done_testing) \& 1..2 .Ve .PP and: .PP .Vb 2 \& use Test::More tests => 3; \& use Test::Warnings 0.005 \*(Aq:all\*(Aq; \& \& pass(\*(Aqyay!\*(Aq); \& like(warning { warn "oh noes!" }, qr/^oh noes/, \*(Aqwe warned\*(Aq); .Ve .PP emits \s-1TAP:\s0 .PP .Vb 4 \& ok 1 \- yay! \& ok 2 \- we warned \& ok 3 \- no (unexpected) warnings (via END block) \& 1..3 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" If you've ever tried to use Test::NoWarnings to confirm there are no warnings generated by your tests, combined with the convenience of \f(CW\*(C`done_testing\*(C'\fR to not have to declare a test count, you'll have discovered that these two features do not play well together, as the test count will be calculated \fIbefore\fR the warnings test is run, resulting in a \s-1TAP\s0 error. (See \f(CW\*(C`examples/test_nowarnings.pl\*(C'\fR in this distribution for a demonstration.) .PP This module is intended to be used as a drop-in replacement for Test::NoWarnings: it also adds an extra test, but runs this test \fIbefore\fR \&\f(CW\*(C`done_testing\*(C'\fR calculates the test count, rather than after. It does this by hooking into \f(CW\*(C`done_testing\*(C'\fR as well as via an \f(CW\*(C`END\*(C'\fR block. You can declare a plan, or not, and things will still Just Work. .PP It is actually equivalent to: .PP .Vb 1 \& use Test::NoWarnings 1.04 \*(Aq:early\*(Aq; .Ve .PP as warnings are still printed normally as they occur. You are safe, and enthusiastically encouraged, to perform a global search-replace of the above with \f(CW\*(C`use Test::Warnings;\*(C'\fR whether or not your tests have a plan. .PP It can also be used as a replacement for Test::Warn, if you wish to test the content of expected warnings; read on to find out how. .SH "FUNCTIONS" .IX Header "FUNCTIONS" The following functions are available for import (not included by default; you can also get all of them by importing the tag \f(CW\*(C`:all\*(C'\fR): .ie n .SS """allow_warnings([bool])"" \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0" .el .SS "\f(CWallow_warnings([bool])\fP \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0" .IX Subsection "allow_warnings([bool]) - EXPERIMENTAL - MAY BE REMOVED" When passed a true value, or no value at all, subsequent warnings will not result in a test failure; when passed a false value, subsequent warnings will result in a test failure. Initial value is \f(CW\*(C`false\*(C'\fR. .PP When warnings are allowed, any warnings will instead be emitted via Test::Builder::note. .ie n .SS """allowing_warnings"" \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0" .el .SS "\f(CWallowing_warnings\fP \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0" .IX Subsection "allowing_warnings - EXPERIMENTAL - MAY BE REMOVED" Returns whether we are currently allowing warnings (set by \f(CW\*(C`allow_warnings\*(C'\fR as described above). .ie n .SS """had_no_warnings(<optional test name>)""" .el .SS "\f(CWhad_no_warnings(<optional test name>)\fP" .IX Subsection "had_no_warnings(<optional test name>)" Tests whether there have been any warnings so far, not preceded by an \&\f(CW\*(C`allowing_warnings\*(C'\fR call. It is run automatically at the end of all tests, but can also be called manually at any time, as often as desired. .ie n .SS """warnings( { code } )""" .el .SS "\f(CWwarnings( { code } )\fP" .IX Subsection "warnings( { code } )" Given a code block, runs the block and returns a list of all the (not previously allowed via \f(CW\*(C`allow_warnings\*(C'\fR) warnings issued within. This lets you test for the presence of warnings that you not only would \fIallow\fR, but \fImust\fR be issued. Testing functions are not provided; given the strings returned, you can test these yourself using your favourite testing functions, such as Test::More::is or Test::Deep::cmp_deeply. .PP You can use this construct as a replacement for Test::Warn::warnings_are: .PP .Vb 8 \& is_deeply( \& [ warnings { ... } ], \& [ \& \*(Aqwarning message 1\*(Aq, \& \*(Aqwarning message 2\*(Aq, \& ], \& \*(Aqgot expected warnings\*(Aq, \& ); .Ve .PP or, to replace Test::Warn::warnings_like: .PP .Vb 8 \& cmp_deeply( \& [ warnings { ... } ], \& bag( # ordering of messages doesn\*(Aqt matter \& re(qr/warning message 1/), \& re(qr/warning message 2/), \& ), \& \*(Aqgot expected warnings (in any order)\*(Aq, \& ); .Ve .PP Warnings generated by this code block are \fI\s-1NOT\s0\fR propagated further. However, since they are returned from this function with their filename and line numbers intact, you can re-issue them yourself immediately after calling \&\f(CW\*(C`warnings(...)\*(C'\fR, if desired. .PP Note that \f(CW\*(C`use Test::Warnings \*(Aqwarnings\*(Aq\*(C'\fR will give you a \f(CW\*(C`warnings\*(C'\fR subroutine in your namespace (most likely \f(CW\*(C`main\*(C'\fR, if you're writing a test), so you (or things you load) can't subsequently do \f(CW\*(C`warnings\->import\*(C'\fR \*(-- it will result in the error: \*(L"Not enough arguments for Test::Warnings::warnings at ..., near \*(R"warnings\->import"". To work around this, either use the fully-qualified form (\f(CW\*(C`Test::warnings\*(C'\fR) or make your calls to the \f(CW\*(C`warnings\*(C'\fR package first. .ie n .SS """warning( { code } )""" .el .SS "\f(CWwarning( { code } )\fP" .IX Subsection "warning( { code } )" Same as \f(CW\*(C`warnings( { code } )\*(C'\fR, except a scalar is always returned \- the single warning produced, if there was one, or an arrayref otherwise \*(-- which can be more convenient to use than \f(CW\*(C`warnings()\*(C'\fR if you are expecting exactly one warning. .PP However, you are advised to capture the result from \f(CW\*(C`warning()\*(C'\fR into a temp variable so you can dump its value if it doesn't contain what you expect. e.g. with this test: .PP .Vb 5 \& like( \& warning { foo() }, \& qr/^this is a warning/, \& \*(Aqgot a warning from foo()\*(Aq, \& ); .Ve .PP if you get two warnings (or none) back instead of one, you'll get an arrayref, which will result in an unhelpful test failure message like: .PP .Vb 4 \& # Failed test \*(Aqgot a warning from foo()\*(Aq \& # at t/mytest.t line 10. \& # \*(AqARRAY(0xdeadbeef)\*(Aq \& # doesn\*(Aqt match \*(Aq(?^:^this is a warning)\*(Aq .Ve .PP So instead, change your test to: .PP .Vb 6 \& my $warning = warning { foo() }; \& like( \& $warning, \& qr/^this is a warning/, \& \*(Aqgot a warning from foo()\*(Aq, \& ) or diag \*(Aqgot warning(s): \*(Aq, explain($warning); .Ve .SS "allow_patterns" .IX Subsection "allow_patterns" .Vb 5 \& allow_patterns(qr/always allow this warning/); \& { \& my $temp = allow_patterns(qr/only allow in this scope/, qr/another temporary warning/); \& ... stuff ... \& } .Ve .PP Given one or more regular expressions, in \f(CW\*(C`qr/.../\*(C'\fR form, add them to the allow-list (warnings will be emitted with \f(CW\*(C`note\*(C'\fR rather than triggering the warning handler). If the return value is saved in a local variable, the warning exemption will only be in effect for that local scope (the addition is reversed at the end of the scope); otherwise, the effect is global. .SS "disallow_patterns" .IX Subsection "disallow_patterns" Given one or more regular expressions, in \f(CW\*(C`qr/.../\*(C'\fR form, remove it from the allow-list. The pattern must exactly match a pattern previously provided to \*(L"allow_patterns\*(R". .SH "IMPORT OPTIONS" .IX Header "IMPORT OPTIONS" .ie n .SS """:all""" .el .SS "\f(CW:all\fP" .IX Subsection ":all" Imports all functions listed above .ie n .SS """:no_end_test""" .el .SS "\f(CW:no_end_test\fP" .IX Subsection ":no_end_test" Disables the addition of a \f(CW\*(C`had_no_warnings\*(C'\fR test via \f(CW\*(C`END\*(C'\fR or \f(CW\*(C`done_testing\*(C'\fR .ie n .SS """:fail_on_warning""" .el .SS "\f(CW:fail_on_warning\fP" .IX Subsection ":fail_on_warning" When used, fail immediately when an unexempted warning is generated (as opposed to waiting until \&\*(L"had_no_warnings\*(R" or \f(CW\*(C`done_testing\*(C'\fR is called). .PP I recommend you only turn this option on when debugging a test, to see where a surprise warning is coming from, and rely on the end-of-tests check otherwise. .ie n .SS """:report_warnings""" .el .SS "\f(CW:report_warnings\fP" .IX Subsection ":report_warnings" When used, \f(CW\*(C`had_no_warnings()\*(C'\fR will print all the unexempted warning content, in case it had been suppressed earlier by other captures (such as \*(L"stderr_like\*(R" in Test::Output or \*(L"capture\*(R" in Capture::Tiny). .SH "OTHER OPTIONS" .IX Header "OTHER OPTIONS" You can temporarily turn off the failure behaviour of this module, swapping it out for reporting (see \f(CW\*(C`:report_warnings\*(C'\fR above) with: .PP .Vb 1 \& $ENV{PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS} = 1; .Ve .PP This can be useful for working around problematic modules that have warnings in newer Perl versions. .SH "CAVEATS" .IX Header "CAVEATS" Sometimes new warnings can appear in Perl that should \fBnot\fR block installation \*(-- for example, smartmatch was recently deprecated in perl 5.17.11, so now any distribution that uses smartmatch and also tests for warnings cannot be installed under 5.18.0. You might want to consider only making warnings fail tests in an author environment \*(-- you can do this with the if pragma: .PP .Vb 1 \& use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, \*(AqTest::Warnings\*(Aq; .Ve .PP In future versions of this module, when interfaces are added to test the content of warnings, there will likely be additional sugar available to indicate that warnings should be checked only in author tests (or \s-1TODO\s0 when not in author testing), but will still provide exported subs. Comments are enthusiastically solicited \- drop me an email, write up an \s-1RT\s0 ticket, or come by \f(CW\*(C`#perl\-qa\*(C'\fR on irc! .PP \&\fBAchtung!\fR This is not a great idea: .PP .Vb 4 \& sub warning_like(&$;$) { \& my ($code, $pattern, $name) = @_; \& like( &warning($code), $pattern, $name ); \& } \& \& warning_like( { ... }, qr/foo/, \*(Aqfoo appears in the warning\*(Aq ); .Ve .PP If the code in the \f(CW\*(C`{ ... }\*(C'\fR is going to warn with a stack trace with the arguments to each subroutine in its call stack (for example via \f(CW\*(C`Carp::cluck\*(C'\fR), the test name, \*(L"foo appears in the warning\*(R" will itself be matched by the regex (see \fIexamples/warning_like.t\fR). Instead, write this: .PP .Vb 1 \& like( warning { ... }, qr/foo/, \*(Aqfoo appears in the warning\*(Aq ); .Ve .SH "CAVEATS" .IX Header "CAVEATS" If you are using another module that sets its own warning handler (for example Devel::Confess or diagnostics) your results may be mixed, as those handlers will interfere with this module's ability to properly detect and capture warnings in their original form. .SH "TO DO (or: POSSIBLE FEATURES COMING IN FUTURE RELEASES)" .IX Header "TO DO (or: POSSIBLE FEATURES COMING IN FUTURE RELEASES)" .IP "\(bu" 4 \&\f(CW\*(C`allow_warnings(qr/.../)\*(C'\fR \- allow some warnings and not others .IP "\(bu" 4 more sophisticated handling in subtests \- if we save some state on the Test::Builder object itself, we can allow warnings in a subtest and then the state will revert when the subtest ends, as well as check for warnings at the end of every subtest via \f(CW\*(C`done_testing\*(C'\fR. .IP "\(bu" 4 sugar for making failures \s-1TODO\s0 when testing outside an author environment .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 Test::NoWarnings .IP "\(bu" 4 Test::FailWarnings .IP "\(bu" 4 blogs.perl.org: \s-1YANWT\s0 (Yet Another No-Warnings Tester) <http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-warnings-tester.html> .IP "\(bu" 4 strictures \- which makes all warnings fatal in tests, hence lessening the need for special warning testing .IP "\(bu" 4 Test::Warn .IP "\(bu" 4 Test::Fatal .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Warnings> (or bug\-Test\-Warnings@rt.cpan.org <mailto:bug-Test-Warnings@rt.cpan.org>). .PP There is also a mailing list available for users of this distribution, at <http://lists.perl.org/list/perl\-qa.html>. .PP There is also an irc channel available for users of this distribution, at \&\f(CW\*(C`#perl\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR <irc://irc.perl.org/#perl-qa>. .PP I am also usually active on irc, as 'ether' at \f(CW\*(C`irc.perl.org\*(C'\fR and \f(CW\*(C`irc.libera.chat\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Karen Etheridge <ether@cpan.org> .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Graham Knop <haarg@haarg.org> .IP "\(bu" 4 A. Sinan Unur <nanis@cpan.org> .IP "\(bu" 4 Leon Timmermans <fawaka@gmail.com> .IP "\(bu" 4 Tina Mueller <cpan2@tinita.de> .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is copyright (c) 2013 by Karen Etheridge. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK 0 �[ arch/auto/Test/Warnings/.existsnu �[��� PK 0 �[lt��F F lib/Test/Warnings.pmnu ��6�$ use strict; use warnings; package Test::Warnings; # git description: v0.032-4-ge6f3f36 # vim: set ts=8 sts=2 sw=2 tw=100 et : # ABSTRACT: Test for warnings and the lack of them # KEYWORDS: testing tests warnings our $VERSION = '0.033'; use parent 'Exporter'; use Test::Builder; our @EXPORT_OK = qw( allow_warnings allowing_warnings had_no_warnings warnings warning allow_patterns disallow_patterns ); our %EXPORT_TAGS = ( all => \@EXPORT_OK ); my $warnings_allowed; my $forbidden_warnings_found; my $done_testing_called; my $no_end_test; my $fail_on_warning; my $report_warnings; my @collected_warnings; my @allowed_patterns; sub import { my $class = shift @_; my %names; @names{@_} = (); # END block will check for this status $no_end_test = exists $names{':no_end_test'}; # __WARN__ handler will check for this status $fail_on_warning = exists $names{':fail_on_warning'}; # Collect and report warnings at the end $report_warnings = exists $names{':report_warnings'}; delete @names{qw(:no_end_test :fail_on_warning :report_warnings)}; __PACKAGE__->export_to_level(1, $class, keys %names); } # swap this out for testing this module only! my $tb; sub _builder(;$) { if (not @_) { $tb ||= Test::Builder->new; return $tb; } $tb = shift; } my $_orig_warn_handler = $SIG{__WARN__}; $SIG{__WARN__} = sub { if ($warnings_allowed or grep +($_[0] =~ $_), @allowed_patterns) { Test::Builder->new->note($_[0]); } else { $forbidden_warnings_found++; push @collected_warnings, $_[0] if $report_warnings; # TODO: this doesn't handle blessed coderefs... does anyone care? goto &$_orig_warn_handler if $_orig_warn_handler and ( (ref $_orig_warn_handler eq 'CODE') or ($_orig_warn_handler ne 'DEFAULT' and $_orig_warn_handler ne 'IGNORE' and defined &$_orig_warn_handler)); if ($_[0] =~ /\n$/) { warn $_[0]; } else { require Carp; Carp::carp($_[0]); } _builder->ok(0, 'unexpected warning') if $fail_on_warning; } }; sub warnings(;&) { # if someone manually does warnings->import in the same namespace this is # imported into, this sub will be called. in that case, just return the # string "warnings" so it calls the correct method. if (!@_) { return 'warnings'; } my $code = shift; my @warnings; local $SIG{__WARN__} = sub { push @warnings, shift; }; $code->(); @warnings; } sub warning(&) { my @warnings = &warnings(@_); return @warnings == 1 ? $warnings[0] : \@warnings; } if (Test::Builder->can('done_testing')) { # monkeypatch Test::Builder::done_testing: # check for any forbidden warnings, and record that we have done so # so we do not check again via END no strict 'refs'; my $orig = *{'Test::Builder::done_testing'}{CODE}; no warnings 'redefine'; *{'Test::Builder::done_testing'} = sub { # only do this at the end of all tests, not at the end of a subtest my $builder = _builder; my $in_subtest_sub = $builder->can('in_subtest'); if (not $no_end_test and not ($in_subtest_sub ? $builder->$in_subtest_sub : $builder->parent)) { local $Test::Builder::Level = $Test::Builder::Level + 3; had_no_warnings('no (unexpected) warnings (via done_testing)'); $done_testing_called = 1; } $orig->(@_); }; } if ($INC{'Test2/Tools/Basic.pm'}) { # monkeypatch Test2::Tools::Basic::done_testing: # check for any forbidden warnings, and record that we have done so # so we do not check again via END no strict 'refs'; my $orig = *{'Test2::Tools::Basic::done_testing'}{CODE}; no warnings 'redefine'; *{'Test2::Tools::Basic::done_testing'} = sub { if (not $no_end_test) { # we could use $ctx to create the test, which means not having to adjust Level, # but then we need to make _builder Test2-compatible, which seems like a PITA. local $Test::Builder::Level = $Test::Builder::Level + 3; had_no_warnings('no (unexpected) warnings (via done_testing)'); $done_testing_called = 1; } $orig->(@_); }; } END { if (not $no_end_test and not $done_testing_called # skip this if there is no plan and no tests have been run (e.g. # compilation tests of this module!) and (_builder->expected_tests or _builder->current_test > 0) ) { local $Test::Builder::Level = $Test::Builder::Level + 1; had_no_warnings('no (unexpected) warnings (via END block)'); } } # setter sub allow_warnings(;$) { $warnings_allowed = @_ || defined $_[0] ? $_[0] : 1; } # getter sub allowing_warnings() { $warnings_allowed } # call at any time to assert no (unexpected) warnings so far sub had_no_warnings(;$) { if ($ENV{PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS}) { $forbidden_warnings_found and _builder->diag("Found $forbidden_warnings_found warnings but allowing them because PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS is set"); } else { _builder->ok(!$forbidden_warnings_found, shift || 'no (unexpected) warnings'); } if (($report_warnings or $ENV{PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS}) and $forbidden_warnings_found) { _builder->diag("Got the following unexpected warnings:"); for my $i (1 .. @collected_warnings) { _builder->diag(" $i: $collected_warnings[ $i - 1 ]"); } } } # pass one or more regexes (in qr format) # when called in void context, lasting effect is universal # otherwise, returns objects: when they go out of scope, the effect is removed # (warning disallowed again). sub allow_patterns(@) { push @allowed_patterns, @_; return if not defined wantarray; return [ map +Test::Warnings::TemporaryWarning->new($_), @_ ]; } sub disallow_patterns(@) { foreach my $pattern (@_) { @allowed_patterns = grep +($_ ne $pattern), @allowed_patterns; } } package # hide from PAUSE Test::Warnings::TemporaryWarning; sub new { my ($class, $pattern) = @_; bless \$pattern, $class; } sub DESTROY { Test::Warnings::disallow_patterns(${$_[0]}); } 1; __END__ =pod =encoding UTF-8 =head1 NAME Test::Warnings - Test for warnings and the lack of them =head1 VERSION version 0.033 =head1 SYNOPSIS use Test::More; use Test::Warnings; pass('yay!'); done_testing; emits TAP: ok 1 - yay! ok 2 - no (unexpected) warnings (via done_testing) 1..2 and: use Test::More tests => 3; use Test::Warnings 0.005 ':all'; pass('yay!'); like(warning { warn "oh noes!" }, qr/^oh noes/, 'we warned'); emits TAP: ok 1 - yay! ok 2 - we warned ok 3 - no (unexpected) warnings (via END block) 1..3 =head1 DESCRIPTION If you've ever tried to use L<Test::NoWarnings> to confirm there are no warnings generated by your tests, combined with the convenience of C<done_testing> to not have to declare a L<test count|Test::More/I love it-when-a-plan-comes-together>, you'll have discovered that these two features do not play well together, as the test count will be calculated I<before> the warnings test is run, resulting in a TAP error. (See C<examples/test_nowarnings.pl> in this distribution for a demonstration.) This module is intended to be used as a drop-in replacement for L<Test::NoWarnings>: it also adds an extra test, but runs this test I<before> C<done_testing> calculates the test count, rather than after. It does this by hooking into C<done_testing> as well as via an C<END> block. You can declare a plan, or not, and things will still Just Work. It is actually equivalent to: use Test::NoWarnings 1.04 ':early'; as warnings are still printed normally as they occur. You are safe, and enthusiastically encouraged, to perform a global search-replace of the above with C<use Test::Warnings;> whether or not your tests have a plan. It can also be used as a replacement for L<Test::Warn>, if you wish to test the content of expected warnings; read on to find out how. =head1 FUNCTIONS The following functions are available for import (not included by default; you can also get all of them by importing the tag C<:all>): =head2 C<< allow_warnings([bool]) >> - EXPERIMENTAL - MAY BE REMOVED When passed a true value, or no value at all, subsequent warnings will not result in a test failure; when passed a false value, subsequent warnings will result in a test failure. Initial value is C<false>. When warnings are allowed, any warnings will instead be emitted via L<Test::Builder::note|Test::Builder/Output>. =head2 C<allowing_warnings> - EXPERIMENTAL - MAY BE REMOVED Returns whether we are currently allowing warnings (set by C<allow_warnings> as described above). =head2 C<< had_no_warnings(<optional test name>) >> Tests whether there have been any warnings so far, not preceded by an C<allowing_warnings> call. It is run automatically at the end of all tests, but can also be called manually at any time, as often as desired. =head2 C<< warnings( { code } ) >> Given a code block, runs the block and returns a list of all the (not previously allowed via C<allow_warnings>) warnings issued within. This lets you test for the presence of warnings that you not only would I<allow>, but I<must> be issued. Testing functions are not provided; given the strings returned, you can test these yourself using your favourite testing functions, such as L<Test::More::is|Test::More/is> or L<Test::Deep::cmp_deeply|Test::Deep/cmp_deeply>. You can use this construct as a replacement for L<Test::Warn::warnings_are|Test::Warn/warnings_are>: is_deeply( [ warnings { ... } ], [ 'warning message 1', 'warning message 2', ], 'got expected warnings', ); or, to replace L<Test::Warn::warnings_like|Test::Warn/warnings_like>: cmp_deeply( [ warnings { ... } ], bag( # ordering of messages doesn't matter re(qr/warning message 1/), re(qr/warning message 2/), ), 'got expected warnings (in any order)', ); Warnings generated by this code block are I<NOT> propagated further. However, since they are returned from this function with their filename and line numbers intact, you can re-issue them yourself immediately after calling C<warnings(...)>, if desired. Note that C<use Test::Warnings 'warnings'> will give you a C<warnings> subroutine in your namespace (most likely C<main>, if you're writing a test), so you (or things you load) can't subsequently do C<< warnings->import >> -- it will result in the error: "Not enough arguments for Test::Warnings::warnings at ..., near "warnings->import"". To work around this, either use the fully-qualified form (C<Test::warnings>) or make your calls to the C<warnings> package first. =head2 C<< warning( { code } ) >> Same as C<< warnings( { code } ) >>, except a scalar is always returned - the single warning produced, if there was one, or an arrayref otherwise -- which can be more convenient to use than C<warnings()> if you are expecting exactly one warning. However, you are advised to capture the result from C<warning()> into a temp variable so you can dump its value if it doesn't contain what you expect. e.g. with this test: like( warning { foo() }, qr/^this is a warning/, 'got a warning from foo()', ); if you get two warnings (or none) back instead of one, you'll get an arrayref, which will result in an unhelpful test failure message like: # Failed test 'got a warning from foo()' # at t/mytest.t line 10. # 'ARRAY(0xdeadbeef)' # doesn't match '(?^:^this is a warning)' So instead, change your test to: my $warning = warning { foo() }; like( $warning, qr/^this is a warning/, 'got a warning from foo()', ) or diag 'got warning(s): ', explain($warning); =head2 allow_patterns allow_patterns(qr/always allow this warning/); { my $temp = allow_patterns(qr/only allow in this scope/, qr/another temporary warning/); ... stuff ... } Given one or more regular expressions, in C<qr/.../> form, add them to the allow-list (warnings will be emitted with C<note> rather than triggering the warning handler). If the return value is saved in a local variable, the warning exemption will only be in effect for that local scope (the addition is reversed at the end of the scope); otherwise, the effect is global. =head2 disallow_patterns Given one or more regular expressions, in C<qr/.../> form, remove it from the allow-list. The pattern must exactly match a pattern previously provided to L</allow_patterns>. =head1 IMPORT OPTIONS =head2 C<:all> Imports all functions listed above =head2 C<:no_end_test> Disables the addition of a C<had_no_warnings> test via C<END> or C<done_testing> =head2 C<:fail_on_warning> =for stopwords unexempted When used, fail immediately when an unexempted warning is generated (as opposed to waiting until L</had_no_warnings> or C<done_testing> is called). I recommend you only turn this option on when debugging a test, to see where a surprise warning is coming from, and rely on the end-of-tests check otherwise. =head2 C<:report_warnings> When used, C<had_no_warnings()> will print all the unexempted warning content, in case it had been suppressed earlier by other captures (such as L<Test::Output/stderr_like> or L<Capture::Tiny/capture>). =head1 OTHER OPTIONS You can temporarily turn off the failure behaviour of this module, swapping it out for reporting (see C<:report_warnings> above) with: $ENV{PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS} = 1; This can be useful for working around problematic modules that have warnings in newer Perl versions. =head1 CAVEATS =for stopwords smartmatch TODO irc Sometimes new warnings can appear in Perl that should B<not> block installation -- for example, smartmatch was recently deprecated in perl 5.17.11, so now any distribution that uses smartmatch and also tests for warnings cannot be installed under 5.18.0. You might want to consider only making warnings fail tests in an author environment -- you can do this with the L<if> pragma: use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, 'Test::Warnings'; In future versions of this module, when interfaces are added to test the content of warnings, there will likely be additional sugar available to indicate that warnings should be checked only in author tests (or TODO when not in author testing), but will still provide exported subs. Comments are enthusiastically solicited - drop me an email, write up an RT ticket, or come by C<#perl-qa> on irc! =for stopwords Achtung B<Achtung!> This is not a great idea: sub warning_like(&$;$) { my ($code, $pattern, $name) = @_; like( &warning($code), $pattern, $name ); } warning_like( { ... }, qr/foo/, 'foo appears in the warning' ); If the code in the C<{ ... }> is going to warn with a stack trace with the arguments to each subroutine in its call stack (for example via C<Carp::cluck>), the test name, "foo appears in the warning" will itself be matched by the regex (see F<examples/warning_like.t>). Instead, write this: like( warning { ... }, qr/foo/, 'foo appears in the warning' ); =head1 CAVEATS If you are using another module that sets its own warning handler (for example L<Devel::Confess> or L<diagnostics>) your results may be mixed, as those handlers will interfere with this module's ability to properly detect and capture warnings in their original form. =head1 TO DO (or: POSSIBLE FEATURES COMING IN FUTURE RELEASES) =over =item * C<< allow_warnings(qr/.../) >> - allow some warnings and not others =for stopwords subtest subtests =item * more sophisticated handling in subtests - if we save some state on the L<Test::Builder> object itself, we can allow warnings in a subtest and then the state will revert when the subtest ends, as well as check for warnings at the end of every subtest via C<done_testing>. =item * sugar for making failures TODO when testing outside an author environment =back =head1 SEE ALSO =for stopwords YANWT =over 4 =item * L<Test::NoWarnings> =item * L<Test::FailWarnings> =item * L<blogs.perl.org: YANWT (Yet Another No-Warnings Tester)|http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-warnings-tester.html> =item * L<strictures> - which makes all warnings fatal in tests, hence lessening the need for special warning testing =item * L<Test::Warn> =item * L<Test::Fatal> =back =head1 SUPPORT Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Warnings> (or L<bug-Test-Warnings@rt.cpan.org|mailto:bug-Test-Warnings@rt.cpan.org>). There is also a mailing list available for users of this distribution, at L<http://lists.perl.org/list/perl-qa.html>. There is also an irc channel available for users of this distribution, at L<C<#perl> on C<irc.perl.org>|irc://irc.perl.org/#perl-qa>. I am also usually active on irc, as 'ether' at C<irc.perl.org> and C<irc.libera.chat>. =head1 AUTHOR Karen Etheridge <ether@cpan.org> =head1 CONTRIBUTORS =for stopwords Graham Knop A. Sinan Unur Leon Timmermans Tina Mueller =over 4 =item * Graham Knop <haarg@haarg.org> =item * A. Sinan Unur <nanis@cpan.org> =item * Leon Timmermans <fawaka@gmail.com> =item * Tina Mueller <cpan2@tinita.de> =back =head1 COPYRIGHT AND LICENCE This software is copyright (c) 2013 by Karen Etheridge. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut PK 0 �[ lib/auto/Test/Warnings/.existsnu �[��� PK T �[ AQ� � man3/Test::Pod.3pmnu �[��� PK T �[ � man3/.existsnu �[��� PK T �[ $ man1/.existsnu �[��� PK T �[ ` arch/.existsnu �[��� PK T �[ � arch/auto/Test/Pod/.existsnu �[��� PK T �[ � bin/.existsnu �[��� PK T �[ ! script/.existsnu �[��� PK T �[vB~� � _ lib/Test/Pod.pmnu ��6�$ PK T �[ �< lib/Test/.existsnu �[��� PK T �[ �< lib/auto/Test/Pod/.existsnu �[��� PK W �[�3zd. d. " = man3/Template::Toolkit::Simple.3pmnu �[��� PK W �[ ) �k arch/auto/Template/Toolkit/Simple/.existsnu �[��� PK W �[�fe e ,l script/tt-rendernu ȯ�� PK W �[ �l lib/Template/Toolkit/.existsnu �[��� PK W �[N?�� m lib/Template/Toolkit/Simple.podnu ��6�$ PK W �[�w� � � �� lib/Template/Toolkit/Simple.pmnu ��6�$ PK W �[ ( �� lib/auto/Template/Toolkit/Simple/.existsnu �[��� PK d �[ -�.�� �� � man3/Storable.3pmnu �[��� PK d �[ �P arch/auto/Storable/.existsnu �[��� PK d �[�{� - - Q arch/auto/Storable/Storable.sonu ȯ�� PK d �[c7�� � q~ lib/Storable.pmnu ��6�$ PK d �[ �A lib/.existsnu �[��� PK d �[ �A lib/auto/Storable/.existsnu �[��� PK � �[� .� 7B man3/Test::Needs.3pmnu �[��� PK � �[ �X arch/auto/Test/Needs/.existsnu �[��� PK � �[P��Y�! �! �X lib/Test/Needs.pmnu ��6�$ PK � �[ �z lib/auto/Test/Needs/.existsnu �[��� PK � �[��q� � { man3/Template::Plugin::Math.3pmnu �[��� PK � �[ �#��2 �2 /� man3/Template::Service.3pmnu �[��� PK � �[�+��z z � man3/Template::Plugin::URL.3pmnu �[��� PK � �[�:'�-T -T $ �� man3/Template::Manual::Internals.3pmnu �[��� PK � �[��cUp p S. man3/Template::Plugin::HTML.3pmnu �[��� PK � �[E���j �j # F man3/Template::Manual::VMethods.3pmnu �[��� PK � �[�� �] �] Z� man3/Template::Manual::Views.3pmnu �[��� PK � �[�s�sy y L man3/Template::Tools.3pmnu �[��� PK � �[�I��7 7 ! man3/Template::Plugin::Assert.3pmnu �[��� PK � �[��n�+ �+ �* man3/Template::Plugin::File.3pmnu �[��� PK � �[��4� � ! |V man3/Template::Plugin::Dumper.3pmnu �[��� PK � �[��M M {g man3/Template::Modules.3pmnu �[��� PK � �[ V�� � � man3/Template::Manual.3pmnu �[��� PK � �[NE@$5 5 � man3/Template::Test.3pmnu �[��� PK � �[����. �. " N� man3/Template::Manual::Plugins.3pmnu �[��� PK � �[�t�s s %� man3/Template::Constants.3pmnu �[��� PK � �[�Cs�^ ^ " � man3/Template::Manual::Credits.3pmnu �[��� PK � �[��>�n n # �0 man3/Template::Plugin::Datafile.3pmnu �[��� PK � �[+��h�' �' $ UD man3/Template::Plugin::Directory.3pmnu �[��� PK � �[���/ �/ -l man3/Template::Manual::Intro.3pmnu �[��� PK � �[���;� � 2� man3/Template::Tools::tpage.3pmnu �[��� PK � �[��|�' �' � man3/Template::Plugin::Image.3pmnu �[��� PK � �[� �b� � � man3/Template::Toolkit.3pmnu �[��� PK � �[�qz�' �' G� man3/Template::Document.3pmnu �[��� PK � �[�wD� ~ ~ & man3/Template::Tutorial::Web.3pmnu �[��� PK � �[�9�� � �� man3/Template::Stash::XS.3pmnu �[��� PK � �[A4i��1 �1 �� man3/Template::FAQ.3pmnu �[��� PK � �[�b@GJ GJ " �� man3/Template::Manual::Filters.3pmnu �[��� PK � �[Z4E� � ! {' man3/Template::Plugin::Scalar.3pmnu �[��� PK � �[�G�� � ]4 man3/Template::Plugin::Wrap.3pmnu �[��� PK � �["���� � �F man3/Template::Base.3pmnu �[��� PK � �[S.ZCE CE % s_ man3/Template::Tutorial::Datafile.3pmnu �[��� PK � �[-5SK�9 �9 � man3/Template::Tools::ttree.3pmnu �[��� PK � �[W�72 72 � man3/Template::Provider.3pmnu �[��� PK � �[�@]�� � � man3/Template::Tutorial.3pmnu �[��� PK � �[ɱTDZ Z ' � man3/Template::Namespace::Constants.3pmnu �[��� PK � �[_�*�pi pi E- man3/Template.3pmnu �[��� PK � �[���i� � �� man3/Template::Plugin::Date.3pmnu �[��� PK � �[$X~50 50 ! ƶ man3/Template::Manual::Config.3pmnu �[��� PK � �[ɞ�,� � # L� man3/Template::Plugin::Iterator.3pmnu �[��� PK � �[z��A A O� man3/Template::Plugin::View.3pmnu �[��� PK � �[T%� � man3/Template::App::ttree.3pmnu �[��� PK � �[=�r�2 2 2 man3/Template::Filters.3pmnu �[��� PK � �[���L< L< ! �. man3/Template::Plugin::String.3pmnu �[��� PK � �[��'�* �* ! Kk man3/Template::Plugin::Filter.3pmnu �[��� PK � �[�% � � D� man3/Template::Config.3pmnu �[��� PK � �[����� � % j� man3/Template::Plugin::Procedural.3pmnu �[��� PK � �[r�m� � ! �� man3/Template::Stash::Context.3pmnu �[��� PK � �[��Vlj` �` �� man3/Template::Context.3pmnu �[��� PK � �[y�^+S$ S$ �6 man3/Template::Plugin::Table.3pmnu �[��� PK � �[K](�z �z $ 0[ man3/Template::Manual::Variables.3pmnu �[��� PK � �[�|�"e' e' V� man3/Template::Stash.3pmnu �[��� PK � �[ޚh� � � man3/Template::Plugin::Pod.3pmnu �[��� PK � �[�nf� ! � man3/Template::Plugin::Format.3pmnu �[��� PK � �[o���@ @ I man3/Template::VMethods.3pmnu �[��� PK � �[ q� N N �! man3/Template::Exception.3pmnu �[��� PK � �[L<�� � n5 man3/Template::Plugins.3pmnu �[��� PK � �[ʬ�DQ# Q# �T man3/Template::Plugin.3pmnu �[��� PK � �[�S&� � 1x man3/Template::Parser.3pmnu �[��� PK � �[ôc�� � '� man3/Template::Directive.3pmnu �[��� PK � �[H����% �% 7� man3/Template::Iterator.3pmnu �[��� PK � �[��>2�% �% % U� man3/Template::Manual::Directives.3pmnu �[��� PK � �[�I��'* '* _� man3/Template::View.3pmnu �[��� PK � �[svC�1 �1 ! � man3/Template::Manual::Syntax.3pmnu �[��� PK � �[���i� � �L man3/Template::Grammar.3pmnu �[��� PK � �[� �Y man1/tpage.1nu �[��� PK � �[Ue�B\; \; &j man1/ttree.1nu �[��� PK � �[ �� arch/auto/Template/.existsnu �[��� PK � �[ # � arch/auto/Template/Stash/XS/.existsnu �[��� PK � �[I� iP P ! [� arch/auto/Template/Stash/XS/XS.sonu ȯ�� PK � �[̇�<�0 �0 �� script/ttreenu ȯ�� PK � �[��l# l# 2� script/tpagenu ȯ�� PK � �[� ��ie ie � lib/Template.pmnu ��6�$ PK � �[�zSiN N �s lib/Template/Manual/Credits.podnu ��6�$ PK � �[� �ܑ% �% � lib/Template/Manual/Intro.podnu ��6�$ PK � �[��2�\G \G ! �� lib/Template/Manual/Internals.podnu ��6�$ PK � �[���U# U# �� lib/Template/Manual/Plugins.podnu ��6�$ PK � �[l�OQ�6 �6 N lib/Template/Manual/Filters.podnu ��6�$ PK � �[��v� � �P lib/Template/Manual/Config.podnu ��6�$ PK � �[�v�# �# �K lib/Template/Manual/Syntax.podnu ��6�$ PK � �[�J�e5b 5b ! p lib/Template/Manual/Variables.podnu ��6�$ PK � �[ �R�J �J �� lib/Template/Manual/Views.podnu ��6�$ PK � �[�H} R R x lib/Template/Manual/VMethods.podnu ��6�$ PK � �[�Y�P�� �� " �o lib/Template/Manual/Directives.podnu ��6�$ PK � �[B ���a �a �` lib/Template/Filters.pmnu ��6�$ PK � �[ �? �? �� lib/Template/Document.pmnu ��6�$ PK � �[�� ;^ ^ lib/Template/Toolkit.pmnu ��6�$ PK � �[���,| | � lib/Template/Manual.podnu ��6�$ PK � �[��K�e e # w# lib/Template/Namespace/Constants.pmnu ��6�$ PK � �[A Z�] �] /5 lib/Template/View.pmnu ��6�$ PK � �[�N�Ctp tp ?� lib/Template/Stash.pmnu ��6�$ PK � �[� ҄�� �� � lib/Template/Parser.pmnu ��6�$ PK � �[�Xn�7 7 � lib/Template/Plugins.pmnu ��6�$ PK � �[ny��� � B� lib/Template/Exception.pmnu ��6�$ PK � �[�>K�0s 0s n� lib/Template/Directive.pmnu ��6�$ PK � �[<ni i �f lib/Template/Tutorial/Web.podnu ��6�$ PK � �[���>48 48 " F� lib/Template/Tutorial/Datafile.podnu ��6�$ PK � �[�{�� � � lib/Template/Plugin/Math.pmnu ��6�$ PK � �[���� � lib/Template/Plugin/Datafile.pmnu ��6�$ PK � �[�6@� � �* lib/Template/Plugin/View.pmnu ��6�$ PK � �[���& �& �4 lib/Template/Plugin/Filter.pmnu ��6�$ PK � �[ng��r r �[ lib/Template/Plugin/Pod.pmnu ��6�$ PK � �[]>&��+ �+ kb lib/Template/Plugin/File.pmnu ��6�$ PK � �[���1 �1 a� lib/Template/Plugin/Table.pmnu ��6�$ PK � �[7��- �- P� lib/Template/Plugin/Image.pmnu ��6�$ PK � �[��V� � W� lib/Template/Plugin/Assert.pmnu ��6�$ PK � �[)�N�+ �+ X� lib/Template/Plugin/Directory.pmnu ��6�$ PK � �[>{ �{ { @( lib/Template/Plugin/HTML.pmnu ��6�$ PK � �[)Kg �, �, @ lib/Template/Plugin/Date.pmnu ��6�$ PK � �[����� � 1m lib/Template/Plugin/Iterator.pmnu ��6�$ PK � �[�4�ӵ � Qu lib/Template/Plugin/Wrap.pmnu ��6�$ PK � �[��+� � Q� lib/Template/Plugin/URL.pmnu ��6�$ PK � �[��La a ! D� lib/Template/Plugin/Procedural.pmnu ��6�$ PK � �[��K��F �F �� lib/Template/Plugin/String.pmnu ��6�$ PK � �[F��� � � lib/Template/Plugin/Scalar.pmnu ��6�$ PK � �[��v$� � � lib/Template/Plugin/Dumper.pmnu ��6�$ PK � �[�b�( ( � ! lib/Template/Plugin/Format.pmnu ��6�$ PK � �[��5X1= 1= i! lib/Template/VMethods.pmnu ��6�$ PK � �[��ō �Q! lib/Template/Tutorial.podnu ��6�$ PK � �[��[�� �� =V! lib/Template/Provider.pmnu ��6�$ PK � �[BL*0t� t� @ " lib/Template/App/ttree.pmnu ��6�$ PK � �[ �jh h ��" lib/Template/Stash/XS.pmnu ��6�$ PK � �[ ��" lib/Template/Stash/.existsnu �[��� PK � �[�c��f �f ��" lib/Template/Stash/Context.pmnu ��6�$ PK � �[�&fL�� �� � # lib/Template/Context.pmnu ��6�$ PK � �[��.N� � ��# lib/Template/Tools.podnu ��6�$ PK � �[TW�6h h #�# lib/Template/Tools/tpage.podnu ��6�$ PK � �[��0�H) H) ��# lib/Template/Tools/ttree.podnu ��6�$ PK � �[�����4 �4 k$ lib/Template/Iterator.pmnu ��6�$ PK � �[�-G_�% �% P9$ lib/Template/Constants.pmnu ��6�$ PK � �[�O���" �" ,_$ lib/Template/Plugin.pmnu ��6�$ PK � �[݇�5 �5 j�$ lib/Template/Config.pmnu ��6�$ PK � �[��E+E +E 7�$ lib/Template/Service.pmnu ��6�$ PK � �[Zcjy y ��$ lib/Template/Modules.podnu ��6�$ PK � �[��H�V �V j% lib/Template/Test.pmnu ��6�$ PK � �[¬�jx" x" /j% lib/Template/FAQ.podnu ��6�$ PK � �[��`1h h �% lib/Template/Base.pmnu ��6�$ PK � �[�@�� � ��% lib/Template/Grammar.pmnu ��6�$ PK � �[ �,' lib/auto/Template/.existsnu �[��� PK � �[ " 9-' lib/auto/Template/Stash/XS/.existsnu �[��� PK � �[1�m �& �& �-' man3/Devel::CheckLib.3pmnu �[��� PK � �[���Ep p �T' man1/use-devel-checklib.1nu �[��� PK � �[ Fb' arch/auto/Devel/CheckLib/.existsnu �[��� PK � �[�Ŗ� � �b' script/use-devel-checklibnu ȯ�� PK � �[ �m' lib/auto/Devel/CheckLib/.existsnu �[��� PK � �[ n' lib/Devel/.existsnu �[��� PK � �[��]�`I `I Gn' lib/Devel/CheckLib.pmnu ��6�$ PK � �[� �K�3 �3 �' man3/NetAddr::IP::InetBase.3pmnu �[��� PK � �[�o%�V �V ��' man3/NetAddr::IP::Util.3pmnu �[��� PK � �[�� % % �B( man3/NetAddr::IP::UtilPP.3pmnu �[��� PK � �[� �厑 �� Xh( man3/NetAddr::IP.3pmnu �[��� PK � �[]g� �d �d *�( man3/NetAddr::IP::Lite.3pmnu �[��� PK � �[ ! _) arch/auto/NetAddr/IP/Lite/.existsnu �[��� PK � �[ Q_) arch/auto/NetAddr/IP/.existsnu �[��� PK � �[q~$� � ! �_) arch/auto/NetAddr/IP/Util/Util.sonu ȯ�� PK � �[ ! �+ arch/auto/NetAddr/IP/Util/.existsnu �[��� PK � �[)| 4i= i= O+ lib/NetAddr/IP/UtilPP.pmnu ��6�$ PK � �[ag�r�� �� T+ lib/NetAddr/IP/Lite.pmnu ��6�$ PK � �[:�W �W �+ lib/NetAddr/IP/Util.pmnu ��6�$ PK � �[�I� � "X, lib/NetAddr/IP/Util_IS.pmnu ��6�$ PK � �[ C[, lib/NetAddr/IP/.existsnu �[��� PK � �[� K K �[, lib/NetAddr/IP/InetBase.pmnu ��6�$ PK � �[O���C� C� �, lib/NetAddr/IP.pmnu ��6�$ PK � �[ hQ- lib/NetAddr/.existsnu �[��� PK � �[~t�� � ! �Q- lib/auto/NetAddr/IP/compactref.alnu �[��� PK � �[y���I I �X- lib/auto/NetAddr/IP/hostenum.alnu �[��� PK � �[ @Z- lib/auto/NetAddr/IP/Lite/.existsnu �[��� PK � �[C�� � � �Z- lib/auto/NetAddr/IP/_splitref.alnu �[��� PK � �[�_��V V �^- lib/auto/NetAddr/IP/re6.alnu �[��� PK � �[Ed�f f (f- lib/auto/NetAddr/IP/coalesce.alnu �[��� PK � �[�� � � " �k- lib/auto/NetAddr/IP/mod_version.alnu �[��� PK � �[â � ! �m- lib/auto/NetAddr/IP/_splitplan.alnu �[��� PK � �[�'�e� � �y- lib/auto/NetAddr/IP/wildcard.alnu �[��� PK � �[綵�� � * |- lib/auto/NetAddr/IP/InetBase/inet_any2n.alnu �[��� PK � �[ ܥ�� � ) <~- lib/auto/NetAddr/IP/InetBase/inet_ntoa.alnu �[��� PK � �[�B B * ,�- lib/auto/NetAddr/IP/InetBase/_inet_pton.alnu �[��� PK � �[G�~V� � ) ȃ- lib/auto/NetAddr/IP/InetBase/inet_n2dx.alnu �[��� PK � �[1�Д � * �- lib/auto/NetAddr/IP/InetBase/_inet_ntop.alnu �[��� PK � �[��1F F * �- lib/auto/NetAddr/IP/InetBase/_packzeros.alnu �[��� PK � �[7�X�� � ) ��- lib/auto/NetAddr/IP/InetBase/inet_n2ad.alnu �[��� PK � �[�'�=� � ) �- lib/auto/NetAddr/IP/InetBase/ipv6_ntoa.alnu �[��� PK � �[S}a2 2 ) є- lib/auto/NetAddr/IP/InetBase/ipv6_aton.alnu �[��� PK � �[9��* * ) \�- lib/auto/NetAddr/IP/InetBase/autosplit.ixnu �[��� PK � �[(��ې � ' ߛ- lib/auto/NetAddr/IP/UtilPP/_bcdcheck.alnu �[��� PK � �[�I��� � $ Ɵ- lib/auto/NetAddr/IP/UtilPP/_sa128.alnu �[��� PK � �[�/� & ��- lib/auto/NetAddr/IP/UtilPP/mask4to6.alnu �[��� PK � �[ {�)f f ( �- lib/auto/NetAddr/IP/UtilPP/maskanyto6.alnu �[��� PK � �[M3�c� � $ ݨ- lib/auto/NetAddr/IP/UtilPP/_128x2.alnu �[��� PK � �[��ps ( �- lib/auto/NetAddr/IP/UtilPP/slowadd128.alnu �[��� PK � �[ɘ� % {�- lib/auto/NetAddr/IP/UtilPP/_128x10.alnu �[��� PK � �[�4�4 4 + ݱ- lib/auto/NetAddr/IP/UtilPP/notcontiguous.alnu �[��� PK � �[-�;� � % l�- lib/auto/NetAddr/IP/UtilPP/ipv4to6.alnu �[��� PK � �[F ,C� � & ��- lib/auto/NetAddr/IP/UtilPP/addconst.alnu �[��� PK � �[x�>B� � & Ǻ- lib/auto/NetAddr/IP/UtilPP/_deadlen.alnu �[��� PK � �[�'�� � % �- lib/auto/NetAddr/IP/UtilPP/comp128.alnu �[��� PK � �[n�dO� � % �- lib/auto/NetAddr/IP/UtilPP/ipv6to4.alnu �[��� PK � �[uc�� � ) L�- lib/auto/NetAddr/IP/UtilPP/simple_pack.alnu �[��� PK � �[����� � ' |�- lib/auto/NetAddr/IP/UtilPP/_bin2bcdn.alnu �[��� PK � �[��� � ' Y�- lib/auto/NetAddr/IP/UtilPP/shiftleft.alnu �[��� PK � �[� � & r�- lib/auto/NetAddr/IP/UtilPP/_bcd2bin.alnu �[��� PK � �[�f^�* * & ��- lib/auto/NetAddr/IP/UtilPP/ipanyto6.alnu �[��� PK � �[1V�V % R�- lib/auto/NetAddr/IP/UtilPP/hasbits.alnu �[��� PK � �[�e�0� � & ��- lib/auto/NetAddr/IP/UtilPP/bin2bcdn.alnu �[��� PK � �[k,qQN N $ �- lib/auto/NetAddr/IP/UtilPP/add128.alnu �[��� PK � �[c:N�t t & ��- lib/auto/NetAddr/IP/UtilPP/bcdn2bin.alnu �[��� PK � �[ֹKԸ � % w�- lib/auto/NetAddr/IP/UtilPP/bin2bcd.alnu �[��� PK � �[:OP�# # ' ��- lib/auto/NetAddr/IP/UtilPP/autosplit.ixnu �[��� PK � �[�)>R_ _ $ ��- lib/auto/NetAddr/IP/UtilPP/sub128.alnu �[��� PK � �[Y�z%C C & ��- lib/auto/NetAddr/IP/UtilPP/bcdn2txt.alnu �[��� PK � �[� W� � % J�- lib/auto/NetAddr/IP/UtilPP/bcd2bin.alnu �[��� PK � �[�#� " a�- lib/auto/NetAddr/IP/_compact_v6.alnu �[��� PK � �[Zj�[ [ ��- lib/auto/NetAddr/IP/nprefix.alnu �[��� PK � �[ f�- lib/auto/NetAddr/IP/.existsnu �[��� PK � �[I�2 � � ��- lib/auto/NetAddr/IP/re.alnu �[��� PK � �[�V��j j ��- lib/auto/NetAddr/IP/canon.alnu �[��� PK � �[W*��] ] N�- lib/auto/NetAddr/IP/prefix.alnu �[��� PK � �[ ��- lib/auto/NetAddr/IP/Util/.existsnu �[��� PK � �[�\��d d % H�- lib/auto/NetAddr/IP/Util/autosplit.ixnu �[��� PK � �[�ҭ� � �- lib/auto/NetAddr/IP/short.alnu �[��� PK � �[G�� � A. lib/auto/NetAddr/IP/autosplit.ixnu �[��� PK � �[uN�]{ { . lib/auto/NetAddr/IP/do_prefix.alnu �[��� PK � �[���� �. lib/auto/NetAddr/IP/_compV6.alnu �[��� PK � �[�ؚ�� � 0 . man3/URI::data.3pmnu �[��� PK � �[��G��" �" M . man3/URI::geo.3pmnu �[��� PK � �[G�4 4 8?. man3/URI::otpauth.3pmnu �[��� PK � �[�ݿ�e e �\. man3/URI::ldap.3pmnu �[��� PK � �[ u�a� � Xs. man3/URI::WithBase.3pmnu �[��� PK � �[��Yv� � 4�. man3/URI::Split.3pmnu �[��� PK � �[�RFM M O�. man3/URI::Heuristic.3pmnu �[��� PK � �[�@l ~ ~ �. man3/URI::QueryParam.3pmnu �[��� PK � �[ ���8) 8) ��. man3/URI::file.3pmnu �[��� PK � �[!�+�� � #�. man3/URI::_punycode.3pmnu �[��� PK � �[we7�.� .� ��. man3/URI.3pmnu �[��� PK � �[�0[- - X�/ man3/URI::icap.3pmnu �[��� PK � �[��c� DZ/ man3/URI::Escape.3pmnu �[��� PK � �[��)U� � �/ man3/URI::URL.3pmnu �[��� PK � �[��2q �/ man3/URI::icaps.3pmnu �[��� PK � �[ U�/ arch/auto/URI/.existsnu �[��� PK � �[�(�ܻ� �� ��/ lib/URI.pmnu ��6�$ PK � �[ ��0 lib/auto/URI/.existsnu �[��� PK � �[�L2[ ӗ0 lib/URI/urn.pmnu ��6�$ PK � �[ϡc) .�0 lib/URI/_userpass.pmnu ��6�$ PK � �[m���� � ��0 lib/URI/icap.pmnu ��6�$ PK � �[qPa6� � ��0 lib/URI/rsync.pmnu ��6�$ PK � �[I� . . ��0 lib/URI/_server.pmnu ��6�$ PK � �[��1�} } �0 lib/URI/mms.pmnu ��6�$ PK � �[���l l ѻ0 lib/URI/ldap.pmnu ��6�$ PK � �[xe� |�0 lib/URI/IRI.pmnu ��6�$ PK � �[ut��� � ��0 lib/URI/_query.pmnu ��6�$ PK � �[)��� � �0 lib/URI/QueryParam.pmnu ��6�$ PK � �[;�C� � ��0 lib/URI/snews.pmnu ��6�$ PK � �[E�:n� � ��0 lib/URI/_ldap.pmnu ��6�$ PK � �[��� ��0 lib/URI/nntp.pmnu ��6�$ PK � �[>^�#� � {�0 lib/URI/telnet.pmnu ��6�$ PK � �[�c9{� � <�0 lib/URI/news.pmnu ��6�$ PK � �[3F�/Q Q )�0 lib/URI/file/QNX.pmnu ��6�$ PK � �[����� � ��0 lib/URI/file/Mac.pmnu ��6�$ PK � �[d�I� � �1 lib/URI/file/Unix.pmnu ��6�$ PK � �[��,L� � �1 lib/URI/file/Win32.pmnu ��6�$ PK � �[c��(1 1 1 lib/URI/file/OS2.pmnu ��6�$ PK � �[c��� � �1 lib/URI/file/FAT.pmnu ��6�$ PK � �[����� � �1 lib/URI/file/Base.pmnu ��6�$ PK � �[�qG�� � �1 lib/URI/ldaps.pmnu ��6�$ PK � �[�Ftb b �1 lib/URI/sftp.pmnu ��6�$ PK � �[� � C1 lib/URI/urn/oid.pmnu ��6�$ PK � �[�B�� � �1 lib/URI/urn/isbn.pmnu ��6�$ PK � �[�1y y �$1 lib/URI/mailto.pmnu ��6�$ PK � �[~�� � �+1 lib/URI/sip.pmnu ��6�$ PK � �[|�U} } E21 lib/URI/rtsp.pmnu ��6�$ PK � �[" � � 31 lib/URI/_generic.pmnu ��6�$ PK � �[ ���� � �M1 lib/URI/pop.pmnu ��6�$ PK � �[� �t� � �R1 lib/URI/ldapi.pmnu ��6�$ PK � �[> > �T1 lib/URI/data.pmnu ��6�$ PK � �[�M��k k Sb1 lib/URI/_foreign.pmnu ��6�$ PK � �[�Q��* * c1 lib/URI/geo.pmnu ��6�$ PK � �[��"�� � A�1 lib/URI/sips.pmnu ��6�$ PK � �[ c� � �1 lib/URI/nntps.pmnu ��6�$ PK � �[��+4 ߎ1 lib/URI/WithBase.pmnu ��6�$ PK � �[@��~ ~ 8�1 lib/URI/rtspu.pmnu ��6�$ PK � �[qi|ې � ��1 lib/URI/https.pmnu ��6�$ PK � �[��M��% �% Ɵ1 lib/URI/file.pmnu ��6�$ PK � �[9c�� � ��1 lib/URI/rlogin.pmnu ��6�$ PK � �[j�Ne� � ��1 lib/URI/_login.pmnu ��6�$ PK � �[�,�Y� � ��1 lib/URI/ssh.pmnu ��6�$ PK � �[���| | ��1 lib/URI/gopher.pmnu ��6�$ PK � �[�1�� � r�1 lib/URI/tn3270.pmnu ��6�$ PK � �[ �I� � 3�1 lib/URI/http.pmnu ��6�$ PK � �[ �+L �1 lib/URI/_punycode.pmnu ��6�$ PK � �[�Dvo o _�1 lib/URI/URL.pmnu ��6�$ PK � �[d��� 2 lib/URI/ftp.pmnu ��6�$ PK � �[F�M� � j2 lib/URI/_segment.pmnu ��6�$ PK � �[�.J�=! =! M2 lib/URI/otpauth.pmnu ��6�$ PK � �[�m2M1 1 �(2 lib/URI/Split.pmnu ��6�$ PK � �[��ʰ� � =22 lib/URI/Escape.pmnu ��6�$ PK � �[�Ѳ� iQ2 lib/URI/Heuristic.pmnu ��6�$ PK � �[�G�j ,k2 lib/URI/_idna.pmnu ��6�$ PK � �[�̃_� � �s2 lib/URI/icaps.pmnu ��6�$ PK � �[�ys�S S my2 man3/Exporter::Heavy.3pmnu �[��� PK � �[�i>�U �U �2 man3/Exporter.3pmnu �[��� PK � �[ C�2 arch/auto/Exporter/.existsnu �[��� PK � �[Ӛ�� � ��2 lib/Exporter/Heavy.pmnu ��6�$ PK � �[�^C2 K K T�2 lib/Exporter.pmnu ��6�$ PK � �[ �>3 lib/auto/Exporter/.existsnu �[��� PK � �[=D�� � �>3 man3/Mock::Config.3pmnu �[��� PK � �[ W3 arch/auto/Mock/Config/.existsnu �[��� PK � �[ WW3 lib/Mock/.existsnu �[��� PK � �[�i� e e �W3 lib/Mock/Config.pmnu ��6�$ PK � �[ >j3 lib/auto/Mock/Config/.existsnu �[��� PK � �[BM�;� � % �j3 man3/JSON::backportPP::Compat5005.3pmnu �[��� PK � �[cm}��� �� cu3 man3/JSON.3pmnu �[��� PK � �[=�I h h ]p4 man3/JSON::backportPP.3pmnu �[��� PK � �[� � � % q5 man3/JSON::backportPP::Compat5006.3pmnu �[��� PK � �[�}ZT " �{5 man3/JSON::backportPP::Boolean.3pmnu �[��� PK � �[ <�5 arch/auto/JSON/.existsnu �[��� PK � �[+�d� � ! ��5 lib/JSON/backportPP/Compat5006.pmnu ��6�$ PK � �[{ ��� � Ȗ5 lib/JSON/backportPP/Boolean.pmnu ��6�$ PK � �[6! �� � ! ��5 lib/JSON/backportPP/Compat5005.pmnu ��6�$ PK � �[9� ��� �� �5 lib/JSON/backportPP.pmnu ��6�$ PK � �[ �<7 lib/auto/JSON/.existsnu �[��� PK � �[A��B6� 6� �<7 lib/JSON.pmnu ��6�$ PK � �[Z >Y� � p18 man3/Sub::Uplevel.3pmnu �[��� PK � �[ uQ8 arch/auto/Sub/Uplevel/.existsnu �[��� PK � �[ �Q8 lib/auto/Sub/Uplevel/.existsnu �[��� PK � �[ R8 lib/Sub/.existsnu �[��� PK � �[�&�5�F �F MR8 lib/Sub/Uplevel.pmnu ��6�$ PK � �[z�>P� � ;�8 man3/HTTP::Date.3pmnu �[��� PK � �[ 1�8 arch/auto/HTTP/Date/.existsnu �[��� PK � �[ |�8 lib/HTTP/.existsnu �[��� PK � �[t8��. �. ��8 lib/HTTP/Date.pmnu ��6�$ PK � �[ ��8 lib/auto/HTTP/Date/.existsnu �[��� PK � �[F���6 6 �8 man3/Test::Deep::RegexpOnly.3pmnu �[��� PK � �[T�|�- - ��8 man3/Test::Deep::Shallow.3pmnu �[��� PK � �[ t�F3 3 9 man3/Test::Deep::RegexpRef.3pmnu �[��� PK � �[�h��� � � 9 man3/Test::Deep::NoTest.3pmnu �[��� PK � �[Q� _$ $ �9 man3/Test::Deep::Hash.3pmnu �[��� PK � �[�D^�! ! �'9 man3/Test::Deep::Ref.3pmnu �[��� PK � �[�XQ�' ' Y49 man3/Test::Deep::Stack.3pmnu �[��� PK � �[r��- - �@9 man3/Test::Deep::Methods.3pmnu �[��� PK � �[����3 3 CM9 man3/Test::Deep::ArrayEach.3pmnu �[��� PK � �[��[* * �Y9 man3/Test::Deep::Number.3pmnu �[��� PK � �[J��' ' 9f9 man3/Test::Deep::Cache.3pmnu �[��� PK � �[�h8�< < ! �r9 man3/Test::Deep::HashKeysOnly.3pmnu �[��� PK � �["��n? ? " 79 man3/Test::Deep::RegexpRefOnly.3pmnu �[��� PK � �[qco! ! ȋ9 man3/Test::Deep::Set.3pmnu �[��� PK � �[�[�q' ' 1�9 man3/Test::Deep::Array.3pmnu �[��� PK � �[v�+� ��9 man3/Test::Deep::MM.3pmnu �[��� PK � �[�T * * �9 man3/Test::Deep::Regexp.3pmnu �[��� PK � �[��5? ? " |�9 man3/Test::Deep::RegexpMatches.3pmnu �[��� PK � �[��H9 9 �9 man3/Test::Deep::ListMethods.3pmnu �[��� PK � �[��ӭ? ? " ��9 man3/Test::Deep::RegexpVersion.3pmnu �[��� PK � �[ �4* * '�9 man3/Test::Deep::Ignore.3pmnu �[��� PK � �[��M- - ��9 man3/Test::Deep::Blessed.3pmnu �[��� PK � �[��l�9 9 �9 man3/Test::Deep::ArrayLength.3pmnu �[��� PK � �[�L|�3 3 �: man3/Test::Deep::ScalarRef.3pmnu �[��� PK � �[�!��! ! : man3/Test::Deep::All.3pmnu �[��� PK � �[��Lg! ! �!: man3/Test::Deep::Any.3pmnu �[��� PK � �[H�Y9< < ! �-: man3/Test::Deep::HashElements.3pmnu �[��� PK � �[���0 0 ~:: man3/Test::Deep::HashEach.3pmnu �[��� PK � �[D�q� � �F: man3/Test::Deep.3pmnu �[��� PK � �[[=s- - L; man3/Test::Deep::Boolean.3pmnu �[��� PK � �[,�L�! ! �; man3/Test::Deep::Isa.3pmnu �[��� PK � �[�'qn! ! . ; man3/Test::Deep::Obj.3pmnu �[��� PK � �[De��K K & �); man3/Test::Deep::ArrayElementsOnly.3pmnu �[��� PK � �[�ؕ* * 86; man3/Test::Deep::String.3pmnu �[��� PK � �[�F�$ $ �B; man3/Test::Deep::None.3pmnu �[��� PK � �[0NT�! ! O; man3/Test::Deep::Cmp.3pmnu �[��� PK � �[ت 1$ $ �[; man3/Test::Deep::Code.3pmnu �[��� PK � �[7N�K? ? " �g; man3/Test::Deep::ScalarRefOnly.3pmnu �[��� PK � �[�'�YE E $ �t; man3/Test::Deep::ArrayLengthOnly.3pmnu �[��� PK � �[�(� ' ' �; man3/Test::Deep::Class.3pmnu �[��� PK � �[�,hh- - ��; man3/Test::Deep::RefType.3pmnu �[��� PK � �[U�j0 0 �; man3/Test::Deep::HashKeys.3pmnu �[��� PK � �[˨Tl? ? " ��; man3/Test::Deep::Cache::Simple.3pmnu �[��� PK � �[ �; arch/auto/Test/Deep/.existsnu �[��� PK � �[��xϪo �o ]�; lib/Test/Deep.pmnu ��6�$ PK � �[� c�[ [ G#= lib/Test/Deep/ArrayEach.pmnu ��6�$ PK � �[O�ao` ` �(= lib/Test/Deep/RegexpOnly.pmnu ��6�$ PK � �[����� � �.= lib/Test/Deep/Shallow.pmnu ��6�$ PK � �[o�v�� � �4= lib/Test/Deep/Any.pmnu ��6�$ PK � �[E,]�j j �;= lib/Test/Deep/HashKeysOnly.pmnu ��6�$ PK � �[��� � _E= lib/Test/Deep/Hash.pmnu ��6�$ PK � �[?�|� � �N= lib/Test/Deep/Number.pmnu ��6�$ PK � �[[�Ae� � `V= lib/Test/Deep/MM.pmnu ��6�$ PK � �[��� � �]= lib/Test/Deep/RegexpRef.pmnu ��6�$ PK � �[ν� " �c= lib/Test/Deep/ArrayElementsOnly.pmnu ��6�$ PK � �[�# כ � j= lib/Test/Deep/HashEach.pmnu ��6�$ PK � �[��n] ] �n= lib/Test/Deep/HashElements.pmnu ��6�$ PK � �[e��,� � �w= lib/Test/Deep/RegexpMatches.pmnu ��6�$ PK � �[?5� �}= lib/Test/Deep/All.pmnu ��6�$ PK � �[>�H� � �= lib/Test/Deep/Class.pmnu ��6�$ PK � �["�f�� � !�= lib/Test/Deep/Set.pmnu ��6�$ PK � �[� �j j %�= lib/Test/Deep/Isa.pmnu ��6�$ PK � �["'V�/ / Ӡ= lib/Test/Deep/Array.pmnu ��6�$ PK � �[�5�;� � H�= lib/Test/Deep/NoTest.pmnu ��6�$ PK � �[h� sr r U�= lib/Test/Deep/RegexpVersion.pmnu ��6�$ PK � �[��� � �= lib/Test/Deep/None.pmnu ��6�$ PK � �[�e�� �= lib/Test/Deep/Ignore.pmnu ��6�$ PK � �[� =�� � d�= lib/Test/Deep/ArrayLengthOnly.pmnu ��6�$ PK � �[�TF � � ��= lib/Test/Deep/Cmp.pmnu ��6�$ PK � �[�g�Ն � ��= lib/Test/Deep/Stack.pmnu ��6�$ PK � �[�2�!� � �= lib/Test/Deep/Blessed.pmnu ��6�$ PK � �[�� � O�= lib/Test/Deep/ScalarRefOnly.pmnu ��6�$ PK � �[�g w�= lib/Test/Deep/Cache/Simple.pmnu ��6�$ PK � �[�;, ��= lib/Test/Deep/ScalarRef.pmnu ��6�$ PK � �[�6�ׂ � $�= lib/Test/Deep/Boolean.pmnu ��6�$ PK � �[���V ��= lib/Test/Deep/RegexpRefOnly.pmnu ��6�$ PK � �[���t t =�= lib/Test/Deep/Methods.pmnu ��6�$ PK � �[�k>&Z Z � > lib/Test/Deep/Cache.pmnu ��6�$ PK � �[N��: : �> lib/Test/Deep/Ref.pmnu ��6�$ PK � �[�{�"� � > lib/Test/Deep/Regexp.pmnu ��6�$ PK � �[3%D"w w 1> lib/Test/Deep/RefType.pmnu ��6�$ PK � �[�a� � > lib/Test/Deep/Code.pmnu ��6�$ PK � �[��M�� � G#> lib/Test/Deep/String.pmnu ��6�$ PK � �[c��x x R(> lib/Test/Deep/ListMethods.pmnu ��6�$ PK � �[d WH H -> lib/Test/Deep/HashKeys.pmnu ��6�$ PK � �[�d}�� � �4> lib/Test/Deep/ArrayLength.pmnu ��6�$ PK � �[�D"Z Z �9> lib/Test/Deep/Obj.pmnu ��6�$ PK � �[ _?> lib/auto/Test/Deep/.existsnu �[��� PK � �[�){o�9 �9 �?> man3/Test::LeakTrace::JA.3pmnu �[��� PK � �[ Vm �y> man3/Test::LeakTrace::Script.3pmnu �[��� PK � �[K��� Ն> man3/Test::LeakTrace.3pmnu �[��� PK � �[� ��g �g % 3�> arch/auto/Test/LeakTrace/LeakTrace.sonu ȯ�� PK � �[ `@ arch/auto/Test/LeakTrace/.existsnu �[��� PK � �[{ �H� � �@ lib/Test/LeakTrace/Script.pmnu �7��m PK � �[���( ( �@ lib/Test/LeakTrace/JA.podnu ��6�$ PK � �["#v^ ^ B<@ lib/Test/LeakTrace.pmnu ��6�$ PK � �[ �X@ lib/auto/Test/LeakTrace/.existsnu �[��� PK � �[5P�% �% 4Y@ man3/Test::Fatal.3pmnu �[��� PK � �[ '@ arch/auto/Test/Fatal/.existsnu �[��� PK � �[��x��; �; s@ lib/Test/Fatal.pmnu ��6�$ PK � �[ ��@ lib/auto/Test/Fatal/.existsnu �[��� PK � �[��bY Y ��@ man3/Test::File.3pmnu �[��� PK � �[ XA arch/auto/Test/File/.existsnu �[��� PK � �[�En�� �� �A lib/Test/File.pmnu ��6�$ PK � �[ ~�A lib/auto/Test/File/.existsnu �[��� PK � �[Eֿ�TN TN $ ��A man3/cPanel::PublicAPI::WHM::API.3pmnu �[��� PK � �[]�)$B B ! p B man3/cPanel::PublicAPI::Utils.3pmnu �[��� PK � �[�M��R �R ( 1B man3/cPanel::PublicAPI::WHM::JSONAPI.3pmnu �[��� PK � �[�"{G�Q �Q ' �B man3/cPanel::PublicAPI::WHM::XMLAPI.3pmnu �[��� PK � �[��&��] �] ��B man3/cPanel::PublicAPI.3pmnu �[��� PK � �[f8�,� � �3C man3/cPanel::PublicAPI::WHM.3pmnu �[��� PK � �[%��q q . �TC man3/cPanel::PublicAPI::WHM::CachedVersion.3pmnu �[��� PK � �[xB�( ( $ �hC man3/cPanel::PublicAPI::WHM::DNS.3pmnu �[��� PK � �[��*o o ' �C man3/cPanel::PublicAPI::WHM::Legacy.3pmnu �[��� PK � �[ " �C arch/auto/cPanel/PublicAPI/.existsnu �[��� PK � �[+` n� � 4�C lib/cPanel/PublicAPI/WHM.podnu ��6�$ PK � �[�J�� � �C lib/cPanel/PublicAPI/Utils.pmnu ��6�$ PK � �[��>�� � * �C lib/cPanel/PublicAPI/WHM/CachedVersion.podnu ��6�$ PK � �[� `�C C 8�C lib/cPanel/PublicAPI/WHM/API.pmnu ��6�$ PK � �[��SZ- Z- $ � D lib/cPanel/PublicAPI/WHM/JSONAPI.podnu ��6�$ PK � �['�n.�, �, # 6:D lib/cPanel/PublicAPI/WHM/XMLAPI.podnu ��6�$ PK � �[p�V*> > # YgD lib/cPanel/PublicAPI/WHM/Legacy.podnu ��6�$ PK � �[DoD� � " �nD lib/cPanel/PublicAPI/WHM/Legacy.pmnu ��6�$ PK � �[�Mq # �~D lib/cPanel/PublicAPI/WHM/JSONAPI.pmnu ��6�$ PK � �[���� 8�D lib/cPanel/PublicAPI/WHM/DNS.pmnu ��6�$ PK � �[�E� � " ��D lib/cPanel/PublicAPI/WHM/XMLAPI.pmnu ��6�$ PK � �[!�ϣ ��D lib/cPanel/PublicAPI/WHM/DNS.podnu ��6�$ PK � �[dM 2w w ) d�D lib/cPanel/PublicAPI/WHM/CachedVersion.pmnu ��6�$ PK � �[撺2+ 2+ 4�D lib/cPanel/PublicAPI/WHM/API.podnu ��6�$ PK � �[�7ߘ� � ��D lib/cPanel/PublicAPI/Utils.podnu ��6�$ PK � �[X�F�# # ��D lib/cPanel/PublicAPI/WHM.pmnu ��6�$ PK � �[ - E lib/cPanel/.existsnu �[��� PK � �[�r�d\ d\ o E lib/cPanel/PublicAPI.pmnu ��6�$ PK � �[�R�*�F �F fE lib/cPanel/PublicAPI.podnu ��6�$ PK � �[ ! *�E lib/auto/cPanel/PublicAPI/.existsnu �[��� PK �[OFCn�E �E {�E man3/Capture::Tiny.3pmnu �[��� PK �[ C�E arch/auto/Capture/Tiny/.existsnu �[��� PK �[ ��E lib/auto/Capture/Tiny/.existsnu �[��� PK �[ ��E lib/Capture/.existsnu �[��� PK �[��!G�s �s !�E lib/Capture/Tiny.pmnu ��6�$ PK ) �[���Q' Q' <hF man3/HTTP::CookieJar.3pmnu �[��� PK ) �[��CA A ՏF man3/HTTP::CookieJar::LWP.3pmnu �[��� PK ) �[ c�F arch/auto/HTTP/CookieJar/.existsnu �[��� PK ) �[Q���sK sK ��F lib/HTTP/CookieJar.pmnu ��6�$ PK ) �[T�M�+ + k�F lib/HTTP/CookieJar/LWP.pmnu ��6�$ PK ) �[ ��F lib/auto/HTTP/CookieJar/.existsnu �[��� PK 0 �[E���= �= .�F man3/Test::Warnings.3pmnu �[��� PK 0 �[ h1G arch/auto/Test/Warnings/.existsnu �[��� PK 0 �[lt��F F �1G lib/Test/Warnings.pmnu ��6�$ PK 0 �[ xG lib/auto/Test/Warnings/.existsnu �[��� PK ��� `xG
| ver. 1.6 |
Github
|
.
| PHP 8.2.30 | ??????????? ?????????: 0.28 |
proxy
|
phpinfo
|
???????????