lib/Catalyst/View/TT.pm

   1 package Catalyst::View::TT;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/Catalyst::View/;
   7 use Data::Dump 'dump';
   8 use Template;
   9 use Template::Timer;
  10 use MRO::Compat;
  11 use Scalar::Util qw/blessed/;
  12
  13 our $VERSION = '0.34';
  14
  15 __PACKAGE__->mk_accessors('template');
  16 __PACKAGE__->mk_accessors('expose_methods');
  17 __PACKAGE__->mk_accessors('include_path');
  18
  19 *paths = \&include_path;
  20
  21 =head1 NAME
  22
  23 Catalyst::View::TT - Template View Class
  24
  25 =head1 SYNOPSIS
  26
  27 # use the helper to create your View
  28
  29     myapp_create.pl view Web TT
  30
  31 # add custom configration in View/Web.pm
  32
  33     __PACKAGE__->config(
  34         # any TT configuration items go here
  35         INCLUDE_PATH => [
  36           MyApp->path_to( 'root', 'src' ),
  37           MyApp->path_to( 'root', 'lib' ),
  38         ],
  39         TEMPLATE_EXTENSION => '.tt',
  40         CATALYST_VAR => 'c',
  41         TIMER        => 0,
  42         # Not set by default
  43         PRE_PROCESS        => 'config/main',
  44         WRAPPER            => 'site/wrapper',
  45         render_die => 1, # Default for new apps, see render method docs
  46         expose_methods => [qw/method_in_view_class/],
  47     );
  48
  49 # render view from lib/MyApp.pm or lib/MyApp::Controller::SomeController.pm
  50
  51     sub message : Global {
  52         my ( $self, $c ) = @_;
  53         $c->stash->{template} = 'message.tt2';
  54         $c->stash->{message}  = 'Hello World!';
  55         $c->forward( $c->view('Web') );
  56     }
  57
  58 # access variables from template
  59
  60     The message is: [% message %].
  61
  62     # example when CATALYST_VAR is set to 'Catalyst'
  63     Context is [% Catalyst %]
  64     The base is [% Catalyst.req.base %]
  65     The name is [% Catalyst.config.name %]
  66
  67     # example when CATALYST_VAR isn't set
  68     Context is [% c %]
  69     The base is [% base %]
  70     The name is [% name %]
  71
  72 =cut
  73
  74 sub _coerce_paths {
  75     my ( $paths, $dlim ) = shift;
  76     return () if ( !$paths );
  77     return @{$paths} if ( ref $paths eq 'ARRAY' );
  78
  79     # tweak delim to ignore C:/
  80     unless ( defined $dlim ) {
  81         $dlim = ( $^O eq 'MSWin32' ) ? ':(?!\\/)' : ':';
  82     }
  83     return split( /$dlim/, $paths );
  84 }
  85
  86 sub new {
  87     my ( $class, $c, $arguments ) = @_;
  88     my $config = {
  89         EVAL_PERL          => 0,
  90         TEMPLATE_EXTENSION => '',
  91         %{ $class->config },
  92         %{$arguments},
  93     };
  94     if ( ! (ref $config->{INCLUDE_PATH} eq 'ARRAY') ) {
  95         my $delim = $config->{DELIMITER};
  96         my @include_path
  97             = _coerce_paths( $config->{INCLUDE_PATH}, $delim );
  98         if ( !@include_path ) {
  99             my $root = $c->config->{root};
 100             my $base = Path::Class::dir( $root, 'base' );
 101             @include_path = ( "$root", "$base" );
 102         }
 103         $config->{INCLUDE_PATH} = \@include_path;
 104     }
 105
 106     # if we're debugging and/or the TIMER option is set, then we install
 107     # Template::Timer as a custom CONTEXT object, but only if we haven't
 108     # already got a custom CONTEXT defined
 109
 110     if ( $config->{TIMER} ) {
 111         if ( $config->{CONTEXT} ) {
 112             $c->log->error(
 113                 'Cannot use Template::Timer - a TT CONTEXT is already defined'
 114             );
 115         }
 116         else {
 117             $config->{CONTEXT} = Template::Timer->new(%$config);
 118         }
 119     }
 120
 121     if ( $c->debug && $config->{DUMP_CONFIG} ) {
 122         $c->log->debug( "TT Config: ", dump($config) );
 123     }
 124
 125     my $self = $class->next::method(
 126         $c, { %$config },
 127     );
 128
 129     # Set base include paths. Local'd in render if needed
 130     $self->include_path($config->{INCLUDE_PATH});
 131
 132     $self->expose_methods($config->{expose_methods});
 133     $self->config($config);
 134
 135     # Creation of template outside of call to new so that we can pass [ $self ]
 136     # as INCLUDE_PATH config item, which then gets ->paths() called to get list
 137     # of include paths to search for templates.
 138
 139     # Use a weakend copy of self so we dont have loops preventing GC from working
 140     my $copy = $self;
 141     Scalar::Util::weaken($copy);
 142     $config->{INCLUDE_PATH} = [ sub { $copy->paths } ];
 143
 144     if ( $config->{PROVIDERS} ) {
 145         my @providers = ();
 146         if ( ref($config->{PROVIDERS}) eq 'ARRAY') {
 147             foreach my $p (@{$config->{PROVIDERS}}) {
 148                 my $pname = $p->{name};
 149                 my $prov = 'Template::Provider';
 150                 if($pname eq '_file_')
 151                 {
 152                     $p->{args} = { %$config };
 153                 }
 154                 else
 155                 {
 156                     if($pname =~ s/^\+//) {
 157                         $prov = $pname;
 158                     }
 159                     else
 160                     {
 161                         $prov .= "::$pname";
 162                     }
 163                     # We copy the args people want from the config
 164                     # to the args
 165                     $p->{args} ||= {};
 166                     if ($p->{copy_config}) {
 167                         map  { $p->{args}->{$_} = $config->{$_}  }
 168                                    grep { exists $config->{$_} }
 169                                    @{ $p->{copy_config} };
 170                     }
 171                 }
 172                 local $@;
 173                 eval "require $prov";
 174                 if(!$@) {
 175                     push @providers, "$prov"->new($p->{args});
 176                 }
 177                 else
 178                 {
 179                     $c->log->warn("Can't load $prov, ($@)");
 180                 }
 181             }
 182         }
 183         delete $config->{PROVIDERS};
 184         if(@providers) {
 185             $config->{LOAD_TEMPLATES} = \@providers;
 186         }
 187     }
 188
 189     $self->{template} =
 190         Template->new($config) || do {
 191             my $error = Template->error();
 192             $c->log->error($error);
 193             $c->error($error);
 194             return undef;
 195         };
 196
 197
 198     return $self;
 199 }
 200
 201 sub process {
 202     my ( $self, $c ) = @_;
 203
 204     my $template = $c->stash->{template}
 205       ||  $c->action . $self->config->{TEMPLATE_EXTENSION};
 206
 207     unless (defined $template) {
 208         $c->log->debug('No template specified for rendering') if $c->debug;
 209         return 0;
 210     }
 211
 212     local $@;
 213     my $output = eval { $self->render($c, $template) };
 214     if (my $err = $@) {
 215         return $self->_rendering_error($c, $template . ': ' . $err);
 216     }
 217     if (blessed($output) && $output->isa('Template::Exception')) {
 218         $self->_rendering_error($c, $output);
 219     }
 220
 221     unless ( $c->response->content_type ) {
 222         $c->response->content_type('text/html; charset=utf-8');
 223     }
 224
 225     $c->response->body($output);
 226
 227     return 1;
 228 }
 229
 230 sub _rendering_error {
 231     my ($self, $c, $err) = @_;
 232     my $error = qq/Couldn't render template "$err"/;
 233     $c->log->error($error);
 234     $c->error($error);
 235     return 0;
 236 }
 237
 238 sub render {
 239     my ($self, $c, $template, $args) = @_;
 240
 241     $c->log->debug(qq/Rendering template "$template"/) if $c && $c->debug;
 242
 243     my $output;
 244     my $vars = {
 245         (ref $args eq 'HASH' ? %$args : %{ $c->stash() }),
 246         $self->template_vars($c)
 247     };
 248
 249     local $self->{include_path} =
 250         [ @{ $vars->{additional_template_paths} }, @{ $self->{include_path} } ]
 251         if ref $vars->{additional_template_paths};
 252
 253     unless ( $self->template->process( $template, $vars, \$output ) ) {
 254         if (exists $self->{render_die}) {
 255             die $self->template->error if $self->{render_die};
 256             return $self->template->error;
 257         }
 258         $c->log->debug('The Catalyst::View::TT render() method will start dying on error in a future release. Unless you are calling the render() method manually, you probably want the new behaviour, so set render_die => 1 in config for ' . blessed($self) . '. If you wish to continue to return the exception rather than throwing it, add render_die => 0 to your config.') if $c->debug;
 259         return $self->template->error;
 260     }
 261     return $output;
 262 }
 263
 264 sub template_vars {
 265     my ( $self, $c ) = @_;
 266
 267     return  () unless $c;
 268     my $cvar = $self->config->{CATALYST_VAR};
 269
 270     my %vars = defined $cvar
 271       ? ( $cvar => $c )
 272       : (
 273         c    => $c,
 274         base => $c->req->base,
 275         name => $c->config->{name}
 276       );
 277
 278     if ($self->expose_methods) {
 279         my $meta = $self->meta;
 280         foreach my $method_name (@{$self->expose_methods}) {
 281             my $method = $meta->get_method( $method_name );
 282             unless ($method) {
 283                 Catalyst::Exception->throw( "$method_name not found in TT view" );
 284             }
 285             my $method_body = $method->body;
 286             my $sub = sub {
 287                 $self->$method_body($c, @_);
 288             };
 289             $vars{$method_name} = $sub;
 290         }
 291     }
 292     return %vars;
 293 }
 294
 295 1;
 296
 297 __END__
 298
 299 =head1 DESCRIPTION
 300
 301 This is the Catalyst view class for the L<Template Toolkit|Template>.
 302 Your application should defined a view class which is a subclass of
 303 this module. Throughout this manual it will be assumed that your application
 304 is named F<MyApp> and you are creating a TT view named F<Web>; these names
 305 are placeholders and should always be replaced with whatever name you've
 306 chosen for your application and your view. The easiest way to create a TT
 307 view class is through the F<myapp_create.pl> script that is created along
 308 with the application:
 309
 310     $ script/myapp_create.pl view Web TT
 311
 312 This creates a F<MyApp::View::Web.pm> module in the F<lib> directory (again,
 313 replacing C<MyApp> with the name of your application) which looks
 314 something like this:
 315
 316     package FooBar::View::Web;
 317
 318     use strict;
 319     use warnings;
 320
 321     use base 'Catalyst::View::TT';
 322
 323     __PACKAGE__->config(DEBUG => 'all');
 324
 325 Now you can modify your action handlers in the main application and/or
 326 controllers to forward to your view class.  You might choose to do this
 327 in the end() method, for example, to automatically forward all actions
 328 to the TT view class.
 329
 330     # In MyApp or MyApp::Controller::SomeController
 331
 332     sub end : Private {
 333         my( $self, $c ) = @_;
 334         $c->forward( $c->view('Web') );
 335     }
 336
 337 But if you are using the standard auto-generated end action, you don't even need
 338 to do this!
 339
 340     # in MyApp::Controller::Root
 341     sub end : ActionClass('RenderView') {} # no need to change this line
 342
 343     # in MyApp.pm
 344     __PACKAGE__->config(
 345         ...
 346         default_view => 'Web',
 347     );
 348
 349 This will Just Work.  And it has the advantages that:
 350
 351 =over 4
 352
 353 =item *
 354
 355 If you want to use a different view for a given request, just set
 356 << $c->stash->{current_view} >>.  (See L<Catalyst>'s C<< $c->view >> method
 357 for details.
 358
 359 =item *
 360
 361 << $c->res->redirect >> is handled by default.  If you just forward to
 362 C<View::Web> in your C<end> routine, you could break this by sending additional
 363 content.
 364
 365 =back
 366
 367 See L<Catalyst::Action::RenderView> for more details.
 368
 369 =head2 CONFIGURATION
 370
 371 There are a three different ways to configure your view class.  The
 372 first way is to call the C<config()> method in the view subclass.  This
 373 happens when the module is first loaded.
 374
 375     package MyApp::View::Web;
 376
 377     use strict;
 378     use base 'Catalyst::View::TT';
 379
 380     __PACKAGE__->config({
 381         INCLUDE_PATH => [
 382             MyApp->path_to( 'root', 'templates', 'lib' ),
 383             MyApp->path_to( 'root', 'templates', 'src' ),
 384         ],
 385         PRE_PROCESS  => 'config/main',
 386         WRAPPER      => 'site/wrapper',
 387     });
 388
 389 You may also override the configuration provided in the view class by adding
 390 a 'View::Web' section to your application config (either in the application
 391 main class, or in your configuration file). This should be reserved for
 392 deployment-specific concerns. For example:
 393
 394     # MyApp_local.conf (Config::General format)
 395
 396     <View Web>
 397       WRAPPER "custom_wrapper"
 398       INCLUDE_PATH __path_to('root/templates/custom_site')__
 399       INCLUDE_PATH __path_to('root/templates')__
 400     </View>
 401
 402 might be used as part of a simple way to deploy different instances of the
 403 same application with different themes.
 404
 405 =head2 DYNAMIC INCLUDE_PATH
 406
 407 Sometimes it is desirable to modify INCLUDE_PATH for your templates at run time.
 408
 409 Additional paths can be added to the start of INCLUDE_PATH via the stash as
 410 follows:
 411
 412     $c->stash->{additional_template_paths} =
 413         [$c->config->{root} . '/test_include_path'];
 414
 415 If you need to add paths to the end of INCLUDE_PATH, there is also an
 416 include_path() accessor available:
 417
 418     push( @{ $c->view('Web')->include_path }, qw/path/ );
 419
 420 Note that if you use include_path() to add extra paths to INCLUDE_PATH, you
 421 MUST check for duplicate paths. Without such checking, the above code will add
 422 "path" to INCLUDE_PATH at every request, causing a memory leak.
 423
 424 A safer approach is to use include_path() to overwrite the array of paths
 425 rather than adding to it. This eliminates both the need to perform duplicate
 426 checking and the chance of a memory leak:
 427
 428     @{ $c->view('Web')->include_path } = qw/path another_path/;
 429
 430 If you are calling C<render> directly then you can specify dynamic paths by
 431 having a C<additional_template_paths> key with a value of additonal directories
 432 to search. See L<CAPTURING TEMPLATE OUTPUT> for an example showing this.
 433
 434 =head2 RENDERING VIEWS
 435
 436 The view plugin renders the template specified in the C<template>
 437 item in the stash.
 438
 439     sub message : Global {
 440         my ( $self, $c ) = @_;
 441         $c->stash->{template} = 'message.tt2';
 442         $c->forward( $c->view('Web') );
 443     }
 444
 445 If a stash item isn't defined, then it instead uses the
 446 stringification of the action dispatched to (as defined by $c->action)
 447 in the above example, this would be C<message>, but because the default
 448 is to append '.tt', it would load C<root/message.tt>.
 449
 450 The items defined in the stash are passed to the Template Toolkit for
 451 use as template variables.
 452
 453     sub default : Private {
 454         my ( $self, $c ) = @_;
 455         $c->stash->{template} = 'message.tt2';
 456         $c->stash->{message}  = 'Hello World!';
 457         $c->forward( $c->view('Web') );
 458     }
 459
 460 A number of other template variables are also added:
 461
 462     c      A reference to the context object, $c
 463     base   The URL base, from $c->req->base()
 464     name   The application name, from $c->config->{ name }
 465
 466 These can be accessed from the template in the usual way:
 467
 468 <message.tt2>:
 469
 470     The message is: [% message %]
 471     The base is [% base %]
 472     The name is [% name %]
 473
 474
 475 The output generated by the template is stored in C<< $c->response->body >>.
 476
 477 =head2 CAPTURING TEMPLATE OUTPUT
 478
 479 If you wish to use the output of a template for some other purpose than
 480 displaying in the response, e.g. for sending an email, this is possible using
 481 L<Catalyst::Plugin::Email> and the L<render> method:
 482
 483   sub send_email : Local {
 484     my ($self, $c) = @_;
 485
 486     $c->email(
 487       header => [
 488         To      => 'me@localhost',
 489         Subject => 'A TT Email',
 490       ],
 491       body => $c->view('Web')->render($c, 'email.tt', {
 492         additional_template_paths => [ $c->config->{root} . '/email_templates'],
 493         email_tmpl_param1 => 'foo'
 494         }
 495       ),
 496     );
 497   # Redirect or display a message
 498   }
 499
 500 =head2 TEMPLATE PROFILING
 501
 502 See L<C<TIMER>> property of the L<config> method.
 503
 504 =head2 METHODS
 505
 506 =head2 new
 507
 508 The constructor for the TT view. Sets up the template provider,
 509 and reads the application config.
 510
 511 =head2 process($c)
 512
 513 Renders the template specified in C<< $c->stash->{template} >> or
 514 C<< $c->action >> (the private name of the matched action).  Calls L<render> to
 515 perform actual rendering. Output is stored in C<< $c->response->body >>.
 516
 517 It is possible to forward to the process method of a TT view from inside
 518 Catalyst like this:
 519
 520     $c->forward('View::Web');
 521
 522 N.B. This is usually done automatically by L<Catalyst::Action::RenderView>.
 523
 524 =head2 render($c, $template, \%args)
 525
 526 Renders the given template and returns output. Throws a L<Template::Exception>
 527 object upon error.
 528
 529 The template variables are set to C<%$args> if C<$args> is a hashref, or
 530 C<< $c->stash >> otherwise. In either case the variables are augmented with
 531 C<base> set to C<< $c->req->base >>, C<c> to C<$c>, and C<name> to
 532 C<< $c->config->{name} >>. Alternately, the C<CATALYST_VAR> configuration item
 533 can be defined to specify the name of a template variable through which the
 534 context reference (C<$c>) can be accessed. In this case, the C<c>, C<base>, and
 535 C<name> variables are omitted.
 536
 537 C<$template> can be anything that Template::process understands how to
 538 process, including the name of a template file or a reference to a test string.
 539 See L<Template::process|Template/process> for a full list of supported formats.
 540
 541 To use the render method outside of your Catalyst app, just pass a undef context.
 542 This can be useful for tests, for instance.
 543
 544 It is possible to forward to the render method of a TT view from inside Catalyst
 545 to render page fragments like this:
 546
 547     my $fragment = $c->forward("View::Web", "render", $template_name, $c->stash->{fragment_data});
 548
 549 =head3 Backwards compatibility note
 550
 551 The render method used to just return the Template::Exception object, rather
 552 than just throwing it. This is now deprecated and instead the render method
 553 will throw an exception for new applications.
 554
 555 This behaviour can be activated (and is activated in the default skeleton
 556 configuration) by using C<< render_die => 1 >>. If you rely on the legacy
 557 behaviour then a warning will be issued.
 558
 559 To silence this warning, set C<< render_die => 0 >>, but it is recommended
 560 you adjust your code so that it works with C<< render_die => 1 >>.
 561
 562 In a future release, C<< render_die => 1 >> will become the default if
 563 unspecified.
 564
 565 =head2 template_vars
 566
 567 Returns a list of keys/values to be used as the catalyst variables in the
 568 template.
 569
 570 =head2 config
 571
 572 This method allows your view subclass to pass additional settings to
 573 the TT configuration hash, or to set the options as below:
 574
 575 =head2 paths
 576
 577 The list of paths TT will look for templates in.
 578
 579 =head2 expose_methods
 580
 581 The list of methods in your View class which should be made available to the templates.
 582
 583 For example:
 584
 585   expose_methods => [qw/uri_for_static/],
 586
 587   ...
 588
 589   sub uri_for_css {
 590     my ($self, $c, $filename) = @_;
 591
 592     # additional complexity like checking file exists here
 593
 594     return $c->uri_for('/static/css/' . $filename);
 595   }
 596
 597 Then in the template:
 598
 599   [% uri_for_css('home.css') %]
 600
 601 =head2 C<CATALYST_VAR>
 602
 603 Allows you to change the name of the Catalyst context object. If set, it will also
 604 remove the base and name aliases, so you will have access them through <context>.
 605
 606 For example, if CATALYST_VAR has been set to "Catalyst", a template might
 607 contain:
 608
 609     The base is [% Catalyst.req.base %]
 610     The name is [% Catalyst.config.name %]
 611
 612 =head2 C<TIMER>
 613
 614 If you have configured Catalyst for debug output, and turned on the TIMER setting,
 615 C<Catalyst::View::TT> will enable profiling of template processing
 616 (using L<Template::Timer>). This will embed HTML comments in the
 617 output from your templates, such as:
 618
 619     <!-- TIMER START: process mainmenu/mainmenu.ttml -->
 620     <!-- TIMER START: include mainmenu/cssindex.tt -->
 621     <!-- TIMER START: process mainmenu/cssindex.tt -->
 622     <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
 623     <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
 624
 625     ....
 626
 627     <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
 628
 629
 630 =head2 C<TEMPLATE_EXTENSION>
 631
 632 a sufix to add when looking for templates bases on the C<match> method in L<Catalyst::Request>.
 633
 634 For example:
 635
 636   package MyApp::Controller::Test;
 637   sub test : Local { .. }
 638
 639 Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for
 640 <root>/test/test.tt.
 641
 642 =head2 C<PROVIDERS>
 643
 644 Allows you to specify the template providers that TT will use.
 645
 646     MyApp->config({
 647         name     => 'MyApp',
 648         root     => MyApp->path_to('root'),
 649         'View::Web' => {
 650             PROVIDERS => [
 651                 {
 652                     name    => 'DBI',
 653                     args    => {
 654                         DBI_DSN => 'dbi:DB2:books',
 655                         DBI_USER=> 'foo'
 656                     }
 657                 }, {
 658                     name    => '_file_',
 659                     args    => {}
 660                 }
 661             ]
 662         },
 663     });
 664
 665 The 'name' key should correspond to the class name of the provider you
 666 want to use.  The _file_ name is a special case that represents the default
 667 TT file-based provider.  By default the name is will be prefixed with
 668 'Template::Provider::'.  You can fully qualify the name by using a unary
 669 plus:
 670
 671     name => '+MyApp::Provider::Foo'
 672
 673 You can also specify the 'copy_config' key as an arrayref, to copy those keys
 674 from the general config, into the config for the provider:
 675
 676     DEFAULT_ENCODING    => 'utf-8',
 677     PROVIDERS => [
 678         {
 679             name    => 'Encoding',
 680             copy_config => [qw(DEFAULT_ENCODING INCLUDE_PATH)]
 681         }
 682     ]
 683
 684 This can prove useful when you want to use the additional_template_paths hack
 685 in your own provider, or if you need to use Template::Provider::Encoding
 686
 687 =head2 HELPERS
 688
 689 The L<Catalyst::Helper::View::TT> and
 690 L<Catalyst::Helper::View::TTSite> helper modules are provided to create
 691 your view module.  There are invoked by the F<myapp_create.pl> script:
 692
 693     $ script/myapp_create.pl view Web TT
 694
 695     $ script/myapp_create.pl view Web TTSite
 696
 697 The L<Catalyst::Helper::View::TT> module creates a basic TT view
 698 module.  The L<Catalyst::Helper::View::TTSite> module goes a little
 699 further.  It also creates a default set of templates to get you
 700 started.  It also configures the view module to locate the templates
 701 automatically.
 702
 703 =head1 NOTES
 704
 705 If you are using the L<CGI> module inside your templates, you will
 706 experience that the Catalyst server appears to hang while rendering
 707 the web page. This is due to the debug mode of L<CGI> (which is
 708 waiting for input in the terminal window). Turning off the
 709 debug mode using the "-no_debug" option solves the
 710 problem, eg.:
 711
 712     [% USE CGI('-no_debug') %]
 713
 714 =head1 SEE ALSO
 715
 716 L<Catalyst>, L<Catalyst::Helper::View::TT>,
 717 L<Catalyst::Helper::View::TTSite>, L<Template::Manual>
 718
 719 =head1 AUTHORS
 720
 721 Sebastian Riedel, C<sri@cpan.org>
 722
 723 Marcus Ramberg, C<mramberg@cpan.org>
 724
 725 Jesse Sheidlower, C<jester@panix.com>
 726
 727 Andy Wardley, C<abw@cpan.org>
 728
 729 =head1 COPYRIGHT
 730
 731 This program is free software. You can redistribute it and/or modify it
 732 under the same terms as Perl itself.
 733
 734 =cut