This file is indexed.

/usr/share/perl5/Petal.pm is in libpetal-perl 2.23-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
# ------------------------------------------------------------------
# Petal - Perl Template Attribute Language
# ------------------------------------------------------------------
# Author: Jean-Michel Hiver
# Description: Front-end for all Petal templating functionality
# ------------------------------------------------------------------
package Petal;
use Petal::Hash;
use Petal::Cache::Disk;
use Petal::Cache::Memory;
use Petal::Parser;
use Petal::Canonicalizer::XML;
use Petal::Canonicalizer::XHTML;
use Petal::Functions;
use Petal::Entities;
use File::Spec;
use Carp;
use Data::Dumper;
use Scalar::Util;
use strict;
use warnings;
use MKDoc::XML::Decode;
use Petal::I18N;


BEGIN
{
    ($] > 5.007) and do {
        require Encode;
    };
    $@ and warn $@;
}



# these are used as local variables when the XML::Parser
# is crunching templates...
use vars qw /@tokens @nodeStack/;


# HTML errors?
our $HTML_ERRORS = undef;


# Encode / Decode info...
our $DECODE_CHARSET = 'utf8';
our $ENCODE_CHARSET = 'utf8'; # deprecated


# Prints as much info as possible when this is enabled.
our $DEBUG_DUMP = 1;


# Warn about uninitialised values in the template?
our $WARN_UNINIT = 0;


# What do we use to parse input?
our $INPUT  = 'XML';
our $INPUTS = {
    'XML'     => 'Petal::Parser',
    'HTML'    => 'Petal::Parser',
    'XHTML'   => 'Petal::Parser',
};


# What do we use to format output?
our $OUTPUT  = 'XML';
our $OUTPUTS = {
    'XML'   => 'Petal::Canonicalizer::XML',
    'HTML'  => 'Petal::Canonicalizer::XHTML',
    'XHTML' => 'Petal::Canonicalizer::XHTML',
};


# makes taint mode happy if set to 1
our $TAINT = undef;


# don't confess() errors if we access an undefined template variable
our $ERROR_ON_UNDEF_VAR = 1;


# where are our templates supposed to be?
our @BASE_DIR = ('.');
our $BASE_DIR = undef; # for backwards compatibility...


# vroom!
our $DISK_CACHE = 1;


# vroom vroom!
our $MEMORY_CACHE = 1;


# cache only mode
our $CACHE_ONLY = 0;


# prevents infinites includes...
our $MAX_INCLUDES = 30;
our $CURRENT_INCLUDES = 0;


# this is for CPAN
our $VERSION = '2.23';


# The CodeGenerator class backend to use.
# Change this only if you know what you're doing.
our $CodeGenerator = 'Petal::CodeGenerator';
our $CodeGeneratorLoaded = 0;

# Default language for multi-language mode.
# Change if you feel that English isn't a fair default.
our $LANGUAGE = 'en';


# this is for XML namespace support. Can't touch this :-)
our $NS = 'petal';
our $NS_URI = 'http://purl.org/petal/1.0/';

our $XI_NS = 'xi';
our $XI_NS_URI = 'http://www.w3.org/2001/XInclude';

our $MT_NS       = 'metal';
our $MT_NS_URI   = 'http://xml.zope.org/namespaces/metal';
our $MT_NAME_CUR = 'main';

# translation service, optional
our $TranslationService = undef;


# Displays the canonical template for template.xml.
# You can set $INPUT using by setting the PETAL_INPUT environment variable.
# You can set $OUTPUT using by setting the PETAL_OUTPUT environment variable.
sub main::canonical
{
    my $file = shift (@ARGV);
    local $Petal::DISK_CACHE = 0;
    local $Petal::MEMORY_CACHE = 0;
    local $Petal::CACHE_ONLY = 0;
    local $Petal::INPUT  = $ENV{PETAL_INPUT}  || 'XML';
    local $Petal::OUTPUT = $ENV{PETAL_OUTPUT} || 'XHTML';
    print ${Petal->new ($file)->_canonicalize()};
}


# Displays the perl code for template.xml.
# You can set $INPUT using by setting the PETAL_INPUT environment variable.
# You can set $OUTPUT using by setting the PETAL_OUTPUT environment variable.
sub main::code
{
    my $file = shift (@ARGV);
    local $Petal::DISK_CACHE = 0;
    local $Petal::MEMORY_CACHE = 0;
    local $Petal::CACHE_ONLY = 0;
    print Petal->new ($file)->_code_disk_cached;
}


# Displays the perl code for template.xml, with line numbers.
# You can set $INPUT using by setting the PETAL_INPUT environment variable.
# You can set $OUTPUT using by setting the PETAL_OUTPUT environment variable.
sub main::lcode
{
    my $file = shift (@ARGV);
    local $Petal::DISK_CACHE = 0;
    local $Petal::MEMORY_CACHE = 0;
    local $Petal::CACHE_ONLY = 0;
    print Petal->new ($file)->_code_with_line_numbers;
}


sub load_code_generator
{
    if (not $CodeGeneratorLoaded)
    {
	eval "require $CodeGenerator";
	confess "Failed to load $CodeGenerator, $@" if $@;
	$CodeGeneratorLoaded = 1;
    }
}


# Instanciates a new Petal object.
sub new
{
    my $class = shift;
    $class = ref $class || $class;
    unshift (@_, 'file') if (@_ == 1);
    my $self = bless { @_ }, $class;
    $self->_initialize();
    
    return $self;
}


# (multi language mode)
# if the language has been specified, let's try to
# find which template we can use.
sub _initialize
{
    my $self  = shift;
    my $file  = $self->{file};
    if ($file =~ /#/)
    {
	my ($file, $macro) = split /#/, $file, 2;
	$self->{file}  = $file;
	$self->_initialize_lang();
	$self->{file} .= "#$macro";
    }
    else
    {
	$self->_initialize_lang();
    }
}


sub _initialize_lang
{
    my $self = shift;
    my $lang = $self->language() || return;
    my @dirs = $self->base_dir();
    @dirs    = map { File::Spec->canonpath ("$_/$self->{file}") } @dirs;
    
    $self->{file}  =~ s/\/$//;
    my $filename   = Petal::Functions::find_filename ($lang, @dirs);
    $self->{file} .= "/$filename" if ($filename);
}


# (multi language mode)
# returns the current preferred language.
sub language
{
    my $self = shift;
    return $self->{language} || $self->{lang};
}


sub default_language   { exists $_[0]->{default_language}   ? $_[0]->{default_language}   : $LANGUAGE           }
sub input              { exists $_[0]->{input}              ? $_[0]->{input}              : $INPUT              }
sub output             { exists $_[0]->{output}             ? $_[0]->{output}             : $OUTPUT             }
sub taint              { exists $_[0]->{taint}              ? $_[0]->{taint}              : $TAINT              }
sub error_on_undef_var { exists $_[0]->{error_on_undef_var} ? $_[0]->{error_on_undef_var} : $ERROR_ON_UNDEF_VAR }
sub disk_cache         { exists $_[0]->{disk_cache}         ? $_[0]->{disk_cache}         : $DISK_CACHE         }
sub memory_cache       { exists $_[0]->{memory_cache}       ? $_[0]->{memory_cache}       : $MEMORY_CACHE       }
sub cache_only         { exists $_[0]->{cache_only}         ? $_[0]->{cache_only}         : $CACHE_ONLY         }
sub max_includes       { exists $_[0]->{max_includes}       ? $_[0]->{max_includes}       : $MAX_INCLUDES       }


sub base_dir
{
    my $self = shift;
    return map { defined $_ ? $_ : () } $self->_base_dir();
}


sub _base_dir
{
    my $self = shift;
    if (exists $self->{base_dir})
    {
	my $base_dir = $self->{base_dir};
	if (ref $base_dir) { return @{$base_dir} }
	else
	{
	    die '\$self->{base_dir} is not defined' unless (defined $base_dir);
	    return $base_dir;
	}
    }
    else
    {
	if (defined $BASE_DIR) { return ( $BASE_DIR, @BASE_DIR ) }
	else                   { return @BASE_DIR                }
    }
}


# _include_compute_path ($path);
# ------------------------------
# Computes the new absolute path from the current
# path and $path
sub _include_compute_path
{
    my $self  = shift;
    my $file  = shift;
    
    # this is for metal self-includes
    if ($file =~ /^#/)
    {
	$file = $self->{file} . $file;
    }
    
    return $file unless ($file =~ /^\./);
    
    my $path = $self->{file};
    ($path)  = $path =~ /(.*)\/.*/;
    $path  ||= '.';
    $path .= '/';
    $path .= $file;
    
    my @path = split /\//, $path;
    my @new_path = ();
    while (scalar @path)
    {
	my $next = shift (@path);
	next if $next eq '.';
	
	if ($next eq '..')
	{
	    die "Cannot go above base directory: $file" if (scalar @new_path == 0);
	    pop (@new_path);
	    next;
	}
	
	push @new_path, $next;
    }
    
    return join '/', @new_path;
}


# Processes the current template object with the information contained in
# %hash. This information can be scalars, hash references, array
# references or objects.
#
# Example:
#
#   my $data_out = $template->process (
#     user   => $user,
#     page   => $page,
#     basket => $shopping_basket,    
#   );
#
# print "Content-Type: text/html\n\n";
# print $data_out;
sub process
{
    my $self = shift;
    $self->_process_absolutize_pathes();
    
    # ok, from there on we need to override any global variable with stuff
    # that might have been specified when constructing the object
    local $TAINT              = defined $self->{taint}               ? $self->{taint}               : $TAINT;
    local $ERROR_ON_UNDEF_VAR = defined $self->{error_on_undef_var}  ? $self->{error_on_undef_var}  : $ERROR_ON_UNDEF_VAR;
    local $DISK_CACHE         = defined $self->{disk_cache}          ? $self->{disk_cache}          : $DISK_CACHE;
    local $MEMORY_CACHE       = defined $self->{memory_cache}        ? $self->{memory_cache}        : $MEMORY_CACHE;
    local $CACHE_ONLY         = defined $self->{cache_only}          ? $self->{cache_only}          : $CACHE_ONLY;
    local $MAX_INCLUDES       = defined $self->{max_includes}        ? $self->{max_includes}        : $MAX_INCLUDES;
    local $INPUT              = defined $self->{input}               ? $self->{input}               : $INPUT;
    local $OUTPUT             = defined $self->{output}              ? $self->{output}              : $OUTPUT;
    local $BASE_DIR           = defined $self->{base_dir} ? do { ref $self->{base_dir} ? undef : $self->{base_dir} } : $BASE_DIR;
    local @BASE_DIR           = defined $self->{base_dir} ? do { ref $self->{base_dir} ? @{$self->{base_dir}} : () } : @BASE_DIR;
    local $LANGUAGE           = defined $self->{default_language}    ? $self->{default_language}    : $LANGUAGE;
    local $DEBUG_DUMP         = defined $self->{debug_dump}          ? $self->{debug_dump}          : $DEBUG_DUMP;
    local $DECODE_CHARSET     = defined $self->{decode_charset}      ? $self->{decode_charset}      : $DECODE_CHARSET;
    local $TranslationService = defined $self->{translation_service} ? $self->{translation_service} : $TranslationService;
    # local $ENCODE_CHARSET     = defined $self->{encode_charset}     ? $self->{encode_charset}     : $ENCODE_CHARSET;

    # prevent infinite includes from happening...
    my $current_includes = $CURRENT_INCLUDES;
    return "ERROR: MAX_INCLUDES : $CURRENT_INCLUDES" if ($CURRENT_INCLUDES > $MAX_INCLUDES);
    local $CURRENT_INCLUDES = $current_includes + 1;
    
    my $res = undef;
    eval {
	my $hash = undef;
	if (ref $_[0] eq 'Petal::Hash') { $hash = shift }
	elsif (ref $_[0] eq 'HASH')     { $hash = new Petal::Hash (%{shift()}) }
	else                            { $hash = new Petal::Hash (@_)         }
	
	my $coderef = $self->_code_memory_cached;
	die "\$coderef is undefined\n\n" unless $coderef;
	die "\$hash is undefined\n\n" unless $hash;
	$res = $coderef->($hash);
    };
    
    if ( $CACHE_ONLY == 1 ){ return 1; }
   
    if (defined $@ and $@) { $res = $self->_handle_error ($@) }
    elsif (defined $TranslationService && $CURRENT_INCLUDES == 1) { $res = Petal::I18N->process ($res) } 

    return $res;
}


# File::Spec->rel2abs() is pretty slow since it uses Cwd which does a
# super-ugly backtick. Hence this method absolutizes base directories
# only once. It is necessary to work with absolute base directories to
# avoid cache conflicts.
sub _process_absolutize_pathes
{
    my $self = shift;
    
    if (defined $BASE_DIR)
    {
	$BASE_DIR = File::Spec->rel2abs ($BASE_DIR) unless (
	    File::Spec->file_name_is_absolute ($BASE_DIR)
	     );
    }
    
    @BASE_DIR = ( map { File::Spec->file_name_is_absolute ($_) ? $_ : File::Spec->rel2abs ($_) }
		  map { defined $_ ? $_ : () } @BASE_DIR );
    
    if (defined $self->{base_dir})
    {
	if (ref $self->{base_dir})
	{
	    $self->{base_dir} = [
		map { File::Spec->file_name_is_absolute ($_) ? $_ : File::Spec->rel2abs ($_) }
		map { defined $_ ? $_ : () } @{$self->{base_dir}}
	       ] if (defined $self->{base_dir});
	}
	else
	{
	    $self->{base_dir} = File::Spec->rel2abs ($self->{base_dir}) unless (
		File::Spec->file_name_is_absolute ($self->{base_dir})
		 );
	}
    }
}


sub _handle_error
{
    my $self = shift;
    my $error = shift;

    $Petal::HTML_ERRORS and do {
        my $res  = '<pre>';
        $res    .= "Error: $error\n";
        $res    .= "=============\n";
        $res    .= "\n\n";
        $res    .= "Petal object dump:\n";
        $res    .= "==================\n";
	$res    .= Dumper ($self);
        $res    .= "\n\n";
	$res    .= "Stack trace:\n";
	$res    .= "============\n";
	$res    .= Carp::longmess();
	$res    .= "\n\n";
        $res    .= "Template perl code dump:\n";
        $res    .= "========================\n";

        my $dump = eval { $self->_code_with_line_numbers() };
        $res    .= ($dump) ? $dump : "(no dump available)";
        
        $res .= '</pre>';
        return $res;
    };
    
    $Petal::DEBUG_DUMP and do {
	my $tmpdir  = File::Spec->tmpdir();
	my $tmpfile = $$ . '.' . time() . '.' . ( join '', map { chr (ord ('a') + int (rand (26))) } 1..10 );
	my $debug   = "$tmpdir/petal_debug.$tmpfile";
	
	open ERROR, ">$debug" || die "Cannot write-open \">$debug\"";
	
	print ERROR "Error: $error\n";
	ref $error and do {
	    print ERROR "=============\n";
	};
	print ERROR "\n";
	
	print ERROR "Petal object dump:\n";
	print ERROR "==================\n";
	print ERROR Dumper ($self);
	print ERROR "\n\n";
	
	print ERROR "Stack trace:\n";
	print ERROR "============\n";
	print ERROR Carp::longmess();
	print ERROR "\n\n";
	
	print ERROR "Template perl code dump:\n";
	print ERROR "========================\n";
	my $dump = eval { $self->_code_with_line_numbers() };
	($dump) ? print ERROR $dump : print ERROR "(no dump available)";
	
	die "[PETAL ERROR] $error. Debug info written in $debug";
    };
    
    ! $Petal::DEBUG_DUMP and do {
	die "[PETAL ERROR] $error. No debug info written.";
    };
}


# $self->code_with_line_numbers;
# ------------------------------
#   utility method to return the Perl code, each line being prefixed with
#   its number... handy for debugging templates. The nifty line number padding
#   patch was provided by Lucas Saud <lucas.marinho@uol.com.br>.
sub _code_with_line_numbers
{
    my $self = shift;
    my $code = $self->_code_disk_cached;

    # get lines of code
    my @lines = split(/\n/, $code);

    # add line numbers
    my $count = 0;
    @lines = map {
	my $cur_line = $_;
	$count++;
	
	# space padding so the line numbers nicely line up with each other
	my $line_num = sprintf ("%" . length(scalar(@lines)) . "d", $count);
	
	# put line number and line back together
	"${line_num}. ${cur_line}";
    } @lines;
    
    return join("\n", @lines);
}


# $self->_file;
# -------------
#   setter / getter for the 'file' attribute
sub _file
{
    my $self = shift;
    $self->{file} = shift if (@_);
    $self->{file} =~ s/^\///;
    return $self->{file};
}


sub _macro
{
    my $self = shift;
    my $file = $self->_file;
    $file =~ s/^.*#// || return;
    return $file;
}


sub _file_path_with_macro
{
    my $self  = shift;
    my $file  = $self->_file_path;
    my $macro = $self->_macro;
    my $res   = $macro ? "$file#$macro" : $file;
    return $res;
}


# $self->_file_path;
# ------------------
#   computes the file of the absolute path where the template
#   file should be fetched
sub _file_path
{
    my $self = shift;
    my $file = $self->_file;
    $file =~ s/#.*$//;
    my @dirs = $self->base_dir;
    
    foreach my $dir (@dirs)
    {
	# my $base_dir  = File::Spec->canonpath ($dir);
	# $base_dir     = File::Spec->rel2abs ($base_dir) unless ($base_dir =~ /^\//);
	my $base_dir  = $dir;
	$base_dir     =~ s/\/$//;
	my $file_path = File::Spec->canonpath ($base_dir . '/' . $file);
	return $file_path if (-e $file_path and -r $file_path);
    }
    
    Carp::confess ("Cannot find $file in @dirs. (typo? permission problem?)");
}


# $self->_file_data_ref;
# ----------------------
# slurps the template data into a variable and returns a
# reference to that variable
sub _file_data_ref
{
    my $self      = shift;
    my $file_path = $self->_file_path;
    $file_path =~ s/#.*$//;
    
    if ($] > 5.007)
    {
	my $encoding = Encode::resolve_alias ($DECODE_CHARSET) || 'utf8';
	open FP, "<:encoding($encoding)", "$file_path" or die "Cannot read-open $file_path";
    }
    else
    {
	open FP, "<$file_path" || die 'Cannot read-open $file_path';
    }
    
    my $res = join '', <FP>;
    close FP;
    
    # kill template comments
    $res =~ s/\<!--\?.*?\-->//gsm;
    
    my $decode = ($OUTPUT =~ /HTML$/i or $INPUT =~ /HTML$/i) ?
        new MKDoc::XML::Decode ('numeric', 'xhtml') :
	new MKDoc::XML::Decode ('numeric');
    
    $res = $decode->process ($res);    
    return \$res;
}


# $self->_code_disk_cached;
# -------------------------
# Returns the Perl code data, using the disk cache if possible
sub _code_disk_cached
{
    my $self = shift;
    my $code = (defined $DISK_CACHE and $DISK_CACHE) ? Petal::Cache::Disk->get ($self->_file_path_with_macro, $self->language) : undef;
    unless (defined $code)
    {
	my $macro = $self->_macro() || $MT_NAME_CUR;
	
	local ($MT_NAME_CUR);
	$MT_NAME_CUR = $macro;
	
	my $data_ref = $self->_canonicalize;
	load_code_generator();
	$code = $CodeGenerator->process ($data_ref, $self);
	Petal::Cache::Disk->set ($self->_file_path_with_macro, $code, $self->language) if (defined $DISK_CACHE and $DISK_CACHE);
    }
    
    return $code;
}


# $self->_code_memory_cached;
# ---------------------------
# Returns the Perl code data, using the disk cache if possible
sub _code_memory_cached
{
    my $self = shift;
    my $code = (defined $MEMORY_CACHE and $MEMORY_CACHE) ? Petal::Cache::Memory->get ($self->_file_path_with_macro, $self->language) : undef;
    unless (defined $code)
    {
	my $code_perl = $self->_code_disk_cached;
	my $VAR1 = undef;
	
	eval "$code_perl";
	confess ($@ . "\n" . $self->_code_with_line_numbers) if $@;
	$code = $VAR1;
	
	Petal::Cache::Memory->set ($self->_file_path_with_macro, $code, $self->language) if (defined $MEMORY_CACHE and $MEMORY_CACHE);	
    }
    
    return $code;
}


# $self->_code_cache;
# -------------------
#   Returns TRUE if this object uses the code cache, FALSE otherwise
sub _memory_cache
{
    my $self = shift;
    return $self->{memory_cache} if (defined $self->{memory_cache});
    return $MEMORY_CACHE;
}


# $self->_canonicalize;
# ---------------------
#   Returns the canonical data which will be sent to the
#   Petal::CodeGenerator module
sub _canonicalize
{
    my $self = shift;
    my $parser_type        = $INPUTS->{$INPUT}   || confess "unknown \$Petal::INPUT = $INPUT";
    my $canonicalizer_type = $OUTPUTS->{$OUTPUT} || confess "unknown \$Petal::OUTPUT = $OUTPUT";
    
    my $data_ref = $self->_file_data_ref;
    my $parser = $parser_type->new;
    return $canonicalizer_type->process ($parser, $data_ref);
}


1;


=head1 NAME

Petal - Perl Template Attribute Language - TAL for Perl!


=head1 SYNOPSIS

in your Perl code:

  use Petal;
  my $template = new Petal ('foo.xhtml');
  print $template->process (bar => 'BAZ');


in foo.xhtml

  <html xmlns:tal="http://purl.org/petal/1.0/">
    <body tal:content="bar">Dummy Content</body>
  </html>


and you get something like:

  <html>
    <body>BAZ</body>
  </html>


=head1 SUMMARY

Petal is a XML based templating engine that is able to process any
kind of XML, XHTML and HTML.

Petal borrows a lot of good ideas from the Zope Page Templates TAL
specification, it is very well suited for the creation of WYSIWYG XHTML
editable templates.

The idea is to further enforce the separation of logic from presentation. With
Petal, graphic designers can use their favorite WYSIWYG editor to easily edit
templates without having to worry about the loops and ifs which happen behind
the scene.


=head1 NAMESPACE

Although this is not mandatory, Petal templates should include use the namespace
L<http://purl.org/petal/1.0/>. Example:

    <html xml:lang="en"
          lang="en"
          xmlns="http://www.w3.org/1999/xhtml"
          xmlns:tal="http://purl.org/petal/1.0/">

      Blah blah blah...
      Content of the file
      More blah blah...
    </html>

If you do not specify the namespace, Petal will by default try to use the
C<petal:> prefix. However, in all the examples of this POD we'll use the
C<tal:> prefix to avoid too much typing.


=head1 KICKSTART

Let's say you have the following Perl code:

    use Petal;
    local $Petal::OUTPUT = 'XHTML';

    my $template = new Petal ('foo.xhtml');
    $template->process ( my_var => some_object() );

some_object() is a subroutine that returns some kind of object, may it be a scalar,
object, array referebce or hash reference. Let's see what we can do...


=head2 Version 1: WYSIWYG friendly prototype.

Using TAL you can do:

    This is the variable 'my_var' :
    <span tal:replace="my_var/hello_world">Hola, Mundo!</span>

Now you can open your template in any WYSIWYG tool (mozilla composer,
frontpage, dreamweaver, adobe golive...) and work with less risk of damaging
your petal commands.


=head2 Version 2: Object-oriented version

Let's now say that C<my_var> is actually an object with a method hello_world()
that returns I<Hello World>. To output the same result, your line, which was:

    <span tal:replace="my_var/hello_world">Hola, Mundo!</span>

Would need to be... EXACTLY the same. Petal lets you access hashes and objects
in an entirely transparent way and tries to automagically do The Right Thing
for you.

This high level of polymorphism means that in most cases you can maintain your
code, swap hashes for objects, and not change a single line of your template
code.


=head2 Version 3: Personalizable

Now let's say that your method hello_world() can take an optional
argument so that C<$some_object-E<gt>hello_world ('Jack')> returns I<Hello Jack>.

You would write:

    <span tal:replace="my_var/hello_world 'Jack'">Hola, Mundo!</span>


Optionally, you can get rid of the quotes by using two dashes, a la GNU
command-line option:

    <span tal:replace="my_var/hello_world --Jack">Hola, Mundo!</span>


So you can pass parameters to methods using double dashes or quotes.
Now let us say that your C<my_var> object also has a method current_user()
that returns the current user real name. You can do:

    <span tal:replace="my_var/hello_world my_var/current_user">Hola, Mundo!</span>


TRAP:

You cannot write nested expressions such as:

    ${my_var/hello_world ${my_var/current_user}}

This will NOT work. At least, not yet.


=head2 Version 4: Internationalized

Let's say that you have a directory called C<hello_world> with the following
files:

    hello_world/en.xhtml
    hello_world/fr.xhtml
    hello_world/es.xhtml

You can use Petal as follows in your Perl code:

    use Petal;
    local $Petal::OUTPUT = 'XHTML';

    my $template = new Petal ( file => 'hello_world', lang => 'fr-CA' );
    print $template->process ( my_var => some_object() );

What will happen is that the C<$template> object will look in the
C<hello_world> directory and try to find a file named C<fr-CA.xhtml>, then
C<fr.xhtml>, then will default to C<en.xhtml>. It works fine for includes, too!

These internationalized templates can have whatever file-extension you like,
Petal searches on the first part of the filename.  So you can call them
C<fr.html>, C<fr.xml>, C<fr.xhtml> or use whatever convention suits you.

NOTE: There is now support for ZPT-like i18n attributes, which should
provide a much nicer framework. See L<Petal::I18N> for details.


TIP:

If you feel that 'en' should not be the default language, you can specify a
different default:

    my $template = new Petal (
        file             => 'hello_world',
        language         => 'zh',
        default_language => 'fr' # vive la France!
    );


TRAP:

If you do specify the C<lang> option, you MUST use a path to a template
directory, not a file directory.

Conversely, if you do not specify a C<lang> option, you MUST use a path to a
template file, not a directory.


=head1 OPTIONS

When you create a Petal template object you can specify various options using
name => value pairs as arguments to the constructor.  For example:

  my $template = Petal->new(
    file     => 'gerbils.html',
    base_dir => '/var/www/petshop',
    input    => 'HTML',
    output   => 'HTML',
  );

The recognized options are:


=head2 file => I<filename>

The template filename.  This option is mandatory and has no default.

Note: If you also use 'language' this option should point to a directory.


=head2 base_dir => I<pathname> | [ I<pathname list> ] (default: '.')

The directories listed in this option will be searched in turn to locate the
template file.  A single directory can be specified as a scalar.  For a
directory list use an arrayref.


=head2 input => 'HTML' | 'XHTML' | 'XML' (default: 'XML')

Defines the format of the template files.  Recognised values are:

  'HTML'  - Alias for 'XHTML'
  'XHTML' - Petal will use Petal::Parser to parse the template
  'XML'   - Petal will use Petal::Parser to parse the template


=head2 output => 'HTML' | 'XHTML' | 'XML' (default: 'XML')

Defines the format of the data generated as a result of processing the template
files.  Recognised values are:

  'HTML'  - Petal will output XHTML, self-closing certain tags
  'XHTML' - Alias for 'HTML'
  'XML'   - Petal will output generic XML 


=head2 language => I<language code>

For internationalized applications, you can use the 'file' option to point to a
I<directory> and select a language-specific template within that directory
using the 'language' option.  Languages are selected using a two letter code
(eg: 'fr') optionally followed by a hyphen and a two letter country code (eg:
'fr-CA').


=head2 default_language => I<language code> (default: 'en')

This language code will be used if no template matches the selected
language-country or language.


=head2 taint => I<true> | I<false> (default: I<false>)

If set to C<true>, makes perl taint mode happy.


=head2 error_on_undef_var => I<true> | I<false> (default: I<true>)

If set to C<true>, Petal will confess() errors when trying to access undefined
template variables, otherwise an empty string will be returned.


=head2 disk_cache => I<true> | I<false> (default: I<true>)

If set to C<false>, Petal will not use the C<Petal::Cache::Disk> module.


=head2 memory_cache => I<true> | I<false> (default: I<true>)

If set to C<false>, Petal will not use the C<Petal::Cache::Memory> module.


=head2 cache_only => I<true> | I<false> (default: I<false>)

If set to C<true>, Petal will return true after having compiled a template into
perl code and a subroutine , and optionally using disk_cache or memory_cache if
either is set.


=head2 max_includes => I<number> (default: 30)

The maximum number of recursive includes before Petal stops processing.  This
is to guard against accidental infinite recursions.


=head2 debug_dump => I<true> | I<false> (default: I<true>)

If this option is true, when Petal cannot process a template it will
output lots of debugging information in a temporary file which you can
inspect.  The location for this file is wherever File::Spec->tmpdir()
specifies as a temp directory (usually /tmp on a unix system).


=head2 encode_charset => I<charset> (default: undef)

This option is _DEPRECATED_ as of Petal 2.01.
Petal will now always return results in Perl's internal form.

It doesn't guarantee that the result will be in UTF-8 or in your
local encoding, but at least the UTF-8 flag should be set properly.

If you want to encode the results for a specific charset, you
should look at the module L<Encode>.


=head2 decode_charset => I<charset> (default: undef)

This option will work only if you use Perl 5.8 or greater.

If specified, Petal will assume that the template to be processed (and its
sub-templates) are in the character set I<charset>.

I<charset> can be any character set that can be used with the module L<Encode>. 


=head1 TAL SYNTAX

This functionality is directly and shamelessly stolen from the excellent TAL
specification: L<http://wiki.zope.org/ZPT/TAL>.


=head2 define

Abstract

  <tag tal:define="variable_name EXPRESSION">

Evaluates C<EXPRESSION> and assigns the returned value to C<variable_name>.

Example

  <!--? sets document/title to 'title' -->
  <span tal:define="title document/title">

Why?

This can be useful if you have a C<very/very/long/expression>.  You can set it
to let's say C<vvle> and then use C<vvle> instead of using
C<very/very/long/expression>.


=head2 condition (ifs)

Abstract

  <tag tal:condition="true:EXPRESSION">
     blah blah blah
  </tag>

Example

  <span tal:condition="true:user/is_authenticated">
    Yo, authenticated!
  </span>

Why?

Conditions can be used to display something if an expression
is true. They can also be used to check that a list exists
before attempting to loop through it.


=head2 repeat (loops)

Abstract

  <tag tal:repeat="element_name EXPRESSION">
     blah blah blah
  </tag>

Why?

Repeat statements are used to loop through a list of values,
typically to display the resulting records of a database query.

Example:

  <li tal:repeat="user system/user_list">$user/real_name</li>

A select list with one item selected:

  <select>
    <option
      selected="selected"
      tal:attributes="value self/selected_lang/value"
      tal:content="self/selected_lang/label"
    >English</option>
    <option
      value="i-klingon"
      tal:repeat="lang self/unselected_langs;"
      tal:attributes="value lang/value"
      tal:content="lang/label"
    >Klingon</option>
  </select>

A table with rows of alternating colours set via CSS:

  <table>
    <div
      tal:omit-tag=""
      tal:repeat="audience self/audiences"
    >
      <tr 
        class="odd"
        tal:condition="repeat/odd"
      >
        <td>
          This a odd row, it comes before the even row.
        </td>
      </tr>
      <tr 
        class="even"
        tal:condition="repeat/even"
      >
        <td> 
          This a even row.
        </td>
      </tr>
    </div>
  </table>

I<repeat> is a local temporary object that only exists within a
petal:repeat loop.  It has a bunch of methods useful for selecting
different positions in the loop:

=head3 repeat/index

I<index> returns the numeric position of this item within the loop, starts with
one not zero.

=head3 repeat/number

I<number> is an alias for I<index>.

=head3 repeat/even

I<even> is true if the position is even (0, 2, 4 ...)

=head3 repeat/odd

I<odd> is true is the position is odd (1, 3, 5 ...)

=head3 repeat/start

I<start> is true if this is the first item.

=head3 repeat/end

I<end> is true if this is the last item.

=head3 repeat/inner

I<inner> is true if this is not the I<start> or I<end>.

=head2 attributes

Abstract

  <tag tal:attributes="attr1 EXPRESSION_1; attr2 EXPRESSION_2"; ...">
     blah blah blah
  </tag>

Example

  <a href="http://www.gianthard.com"
     lang="en-gb"
     tal:attributes="href document/href_relative; lang document/lang">

Why?

Attributes statements can be used to template a tag's attributes.


=head2 content

Abstract

  <tag tal:content="EXPRESSION">Dummy Data To Replace With EXPRESSION</tag>

By default, the characters greater than, lesser than, double quote and
ampersand are encoded to the entities I<&lt;>, I<&gt;>, I<&quot;> and I<&amp;>
respectively.  If you don't want them to (because the result of your expression
is already encoded) you have to use the C<structure> keyword.

Example

  <span tal:content="title">Dummy Title</span>

  <span tal:content="structure some/variable">
     blah blah blah
  </span>

Why?

It lets you replace the contents of a tag with whatever value the evaluation of
EXPRESSION returned. This is handy because you can fill your templates with
dummy content which will make them usable in a WYSIWYG tool.


=head2 replace

Abstract

  <tag tal:replace="EXPRESSION">
    This time the entire tag is replaced
    rather than just the content!
  </tag>

Example

  <span tal:replace="title">Dummy Title</span>

Why?

Similar reasons to C<content>. Note however that C<tal:content> and
C<tal:replace> are *NOT* aliases. The former will replace the contents of the
tag, while the latter will replace the whole tag.

Indeed you cannot use C<tal:content> and C<tal:replace> in the same tag.


=head2 omit-tag

Abstract

  <tag tal:omit-tag="EXPRESSION">Some contents</tag>

Example

  <b tal:omit-tag="not:bold">I may not be bold.</b>

If C<not:bold> is evaluated as I<TRUE>, then the <b> tag will be omited.
If C<not:bold> is evaluated as I<FALSE>, then the <b> tag will stay in place.

Why?

omit-tag statements can be used to leave the contents of a tag in place while
omitting the surrounding start and end tags if the expression which is
evaluated is TRUE.

TIP:

If you want to ALWAYS remove a tag, you can use C<omit-tag="string:1">


=head2 on-error

Warning: this is currently only partially implemented.  C<on-error> may be used
in Petal templates, but the expression isn't evaluated - Petal simply prints
the expression as a string.

Abstract

  <tag on-error="EXPRESSION">...</tag>

Example

  <p on-error="string:Cannot access object/method!!">
    $object/method
  </p>

Why?

When Petal encounters an error, it usually dies with some obscure error
message. The C<on-error> statement lets you trap the error and replace it
with a proper error message.


=head2 using multiple statements

You can do things like:

  <p tal:define="children document/children"
     tal:condition="children"
     tal:repeat="child children"
     tal:attributes="lang child/lang; xml:lang child/lang"
     tal:content="child/data"
     tal:on-error="string:Ouch!">Some Dummy Content</p>

Given the fact that XML attributes are not ordered, withing the same tag
statements will be executed in the following order:

    define
    condition
    repeat
        attributes
        content
    OR
        replace
    OR
        omit-tag
        content


TRAP:

Don't forget that the default prefix is C<petal:> NOT C<tal:>, until
you set the petal namespace in your HTML or XML document as follows:

    <html xmlns:tal="http://purl.org/petal/1.0/">


=head1 METAL MACROS

Petal supports an implementation of the METAL specification, which is a very
WYSIWYG compatible way of doing template includes.


=head2 define-macro

In order to define a macro inside a file (i.e. a fragment to be included), you
use the metal:define-macro directive. For example:

  File foo.xml
  ============

  <html xmlns:metal="http://xml.zope.org/namespaces/metal">
    <body>
      <p metal:define-macro="footer">
        (c) Me (r)(tm) (pouet pouet)
      </p>
    </body>
  </html>


=head2 use-macro

In order to use a previously defined macro, you use the metal:use-macro directive.
For example:

  File bar.xml
  ============

  <html xmlns:metal="http://xml.zope.org/namespaces/metal">
    <body>
      ... plenty of content ...

      <p metal:use-macro="foo.xml#footer">
        Page Footer.
      </p>
    </body>
  </html>


=head2 define-slot

In any given macro you can define slots, which are bits of macros that can be
overridden by something else using the fill-macro directive. To re-use the
example above, imagine that we want to be able to optionally override the
(pouet pouet) bit with something else:


  File foo.xml
  ============

  <html xmlns:metal="http://xml.zope.org/namespaces/metal">
    <body>
      <p metal:define-macro="footer">
        (c) Me (r)(tm) <span metal:define-slot="pouet">(pouet pouet)</span>
      </p>
    </body>
  </html>


=head2 fill-slot

Your including file can override any slot using the fill-slot instruction, i.e.

  File bar.xml
  ============

  <html xmlns:metal="http://xml.zope.org/namespaces/metal">
    <body>
      ... plenty of content ...

      <p metal:use-macro="foo.xml#footer">
        Page Footer. <span metal:fill-slot="pouet" petal:omit-tag="">(bar baz)</span>
      </p>
    </body>
  </html>

This would result in the macro 'foo.xml#footer' to produce:

  <html>
    <body>
      <p>
        (c) Me (r)(tm) (bar baz)
      </p>
    </body>
  </html>


=head2 self includes

In Zope, METAL macros are expanded first, and then the TAL instructions are processed.
However with Petal, METAL macros are expanded at run-time just like regular includes,
which allows for recursive macros.

This example templates a sitemap, which on a hierarchically organized site would
be recursive by nature:

  <html xmlns:metal="http://xml.zope.org/namespaces/metal"
        xmlns:petal="http://purl.org/petal/1.0/">
    <body>
      <p>Sitemap:</p>

      <li metal:define-macro="recurse">
        <a href="#"
           petal:attributes="href child/Full_Path" 
           petal:content="child/Title"
        >Child Document Title</a>
        <ul 
          petal:define="children child/Children"
          petal:condition="children"
          petal:repeat="child children"
        >
          <li metal:use-macro="#recurse">Dummy Child 1</li>
          <li petal:replace="nothing">Dummy Child 2</li>
          <li petal:replace="nothing">Dummy Child 3</li>
        </ul>
      </li>
    </body>
  </html>


=head1 EXPRESSIONS AND MODIFIERS

Petal has the ability to bind template variables to the following Perl
datatypes: scalars, lists, hash, arrays and objects. The article describes
the syntax which is used to access these from Petal templates.

In the following examples, we'll assume that the template is used as follows:

  my $hashref = some_complex_data_structure();
  my $template = new Petal ('foo.xml');
  print $template->process ( $hashref );

Then we will show how the Petal Expression Syntax maps to the Perl way of
accessing these values.  


=head2 accessing scalar values

Perl expression

  $hashref->{'some_value'};

Petal expression

  some_value

Example

  <!--? Replaces Hello, World with the contents of
        $hashref->{'some_value'}
  -->
  <span tal:replace="some_value">Hello, World</span>


=head2 accessing hashes & arrays

Perl expression

  $hashref->{'some_hash'}->{'a_key'};

Petal expression

  some_hash/a_key

Example

  <!--? Replaces Hello, World with the contents
        of $hashref->{'some_hash'}->{'a_key'}
  -->
  <span tal:replace="some_hash/a_key">Hello, World</span>


Perl expression

  $hashref->{'some_array'}->[12]

Petal expression

  some_array/12

Example

  <!--? Replaces Hello, World with the contents
       of $hashref->{'some_array'}->[12]
  -->
  <span tal:replace="some_array/12">Hello, World</span>

Note: You're more likely to want to loop through arrays:

  <!--? Loops trough the array and displays each values -->
  <ul tal:condition="some_array">
    <li tal:repeat="value some_array"
        tal:content="value">Hello, World</li>
  </ul>


=head2 accessing object methods

Perl expressions

  1. $hashref->{'some_object'}->some_method();
  2. $hashref->{'some_object'}->some_method ('foo', 'bar');
  3. $hashref->{'some_object'}->some_method ($hashref->{'some_variable'})  

Petal expressions

  1. some_object/some_method
  2a. some_object/some_method 'foo' 'bar'
  2b. some_object/some_method "foo" "bar"
  2c. some_object/some_method --foo --bar
  3. some_object/some_method some_variable

Note that the syntax as described in 2c works only if you use strings
which do not contain spaces.

Example

  <p>
    <span tal:replace="value1">2</span> times
    <span tal:replace="value2">2</span> equals
    <span tal:replace="math_object/multiply value1 value2">4</span>
  </p>
    

=head2 composing

Petal lets you traverse any data structure, i.e.

Perl expression

  $hashref->{'some_object'}
          ->some_method()
          ->{'key2'}
          ->some_other_method ( 'foo', $hash->{bar} );

Petal expression

  some_object/some_method/key2/some_other_method --foo bar


=head2 true:EXPRESSION

  If EXPRESSION returns an array reference
    If this array reference has at least one element
      Returns TRUE
    Else
      Returns FALSE

  Else
    If EXPRESSION returns a TRUE value (according to Perl 'trueness')
      Returns TRUE
    Else
      Returns FALSE

the C<true:> modifiers should always be used when doing Petal conditions.


=head2 false:EXPRESSION

I'm pretty sure you can work this one out by yourself :-)


=head2 set:variable_name EXPRESSION

Sets the value returned by the evaluation of EXPRESSION in
C<$hash-E<gt>{variable_name}>. For instance:

Perl expression:

  $hash->{variable_name} = $hash->{object}->method();

Petal expression:

  set:variable_name object/method


=head2 string:STRING_EXPRESSION

The C<string:> modifier lets you interpolate petal expressions within a string
and returns the value.

  string:Welcome $user/real_name, it is $date!

Alternatively, you could write:

  string:Welcome ${user/real_name}, it is ${date}!
  
The advantage of using curly brackets is that it lets you interpolate
expressions which invoke methods with parameters, i.e.

  string:The current CGI 'action' param is: ${cgi/param --action}


=head1 ADVANCED PETAL


=head2 writing your own modifiers

Petal lets you write your own modifiers, either using coderefs
or modules.


=head3 Coderefs

Let's say that you want to write an uppercase: modifier, which
would uppercase the result of an expression evaluation, as in:

  uppercase:string:Hello, World

Would return

  HELLO, WORLD

Here is what you can do:

  # don't forget the trailing colon in C<uppercase:> !!
  $Petal::Hash::MODIFIERS->{'uppercase:'} = sub {
      my $hash = shift;
      my $args = shift;

      my $result = $hash->fetch ($args);
      return uc ($result);
  };


=head3 Modules.

You might want to use a module rather than a coderef. Here is the example above
reimplemented as a module:

    package Petal::Hash::UpperCase;
    use strict;
    use warnings;
  
    sub process {
      my $class = shift;
      my $hash  = shift;
      my $args  = shift;

      my $result = $hash->fetch ($args);
      return uc ($result);
    }

    1;

As long as your module is in the namespace Petal::Hash::<YourModifierName>,
Petal will automatically pick it up and assign it to its lowercased
name, i.e. in our example C<uppercase:>.

If your modifier is OUTSIDE Petal::Hash::<YourModifierName>, you need to
make Petal aware of its existence as follows:

  use MyPetalModifier::UpperCase;
  $Petal::Hash::MODIFIERS->{'uppercase:'} = 'MyPetalModifier::UpperCase';


=head1 Expression keywords


=head3 XML encoding / structure keyword

By default Petal will encode C<&>, C<<>, C<>> and C<"> to C<&amp;>, C<&lt;>,
C<&gt> and C<&quot;> respectively. However sometimes you might want to display
an expression which is already encoded, in which case you can use the
C<structure> keyword.

  structure my/encoded/variable

Note that this is a language I<keyword>, not a modifier. It does not use a
trailing colon.


=head3 Petal::Hash caching and fresh keyword 

Petal caches the expressions which it resolves, i.e. if you write the
expression:

  string:$foo/bar, ${baz/buz/blah}

Petal::Hash will compute it once, and then for subsequent accesses to that
expression always return the same value. This is almost never a problem, even
for loops because a new Petal::Hash object is used for each iteration in order
to support proper scoping.

However, in some rare cases you might not want to have that behavior, in which
case you need to prefix your expression with the C<fresh> keyword, i.e. 

  fresh string:$foo/bar, ${baz/buz/blah}

You can use C<fresh> with C<structure> if you need to:

  fresh structure string:$foo/bar, ${baz/buz/blah}

However the reverse does not work:

  <!--? VERY BAD, WON'T WORK !!! -->
  structure fresh string:$foo/bar, ${baz/buz/blah}


=head2 TOY FUNCTIONS (For debugging or if you're curious)


=head3 perl -MPetal -e canonical template.xml

Displays the canonical template for template.xml.
You can set C<$Petal::INPUT> using by setting the PETAL_INPUT environment variable.
You can set C<$Petal::OUTPUT> using by setting the PETAL_OUTPUT environment variable.


=head3 perl -MPetal -e code template.xml

Displays the perl code for template.xml.
You can set C<$Petal::INPUT> using by setting the PETAL_INPUT environment variable.
You can set C<$Petal::OUTPUT> using by setting the PETAL_OUTPUT environment variable.


=head3 perl -MPetal -e lcode template.xml

Displays the perl code for template.xml, with line numbers.
You can set C<$Petal::INPUT> using by setting the PETAL_INPUT environment variable.
You can set C<$Petal::OUTPUT> using by setting the PETAL_OUTPUT environment variable.


=head2 What does Petal do internally?

The cycle of a Petal template is the following:

    1. Read the source XML template
    2. $INPUT (XML or HTML) throws XML events from the source file
    3. $OUTPUT (XML or HTML) uses these XML events to canonicalize the template
    4. Petal::CodeGenerator turns the canonical template into Perl code
    5. Petal::Cache::Disk caches the Perl code on disk
    6. Petal turns the perl code into a subroutine
    7. Petal::Cache::Memory caches the subroutine in memory
    8. Petal executes the subroutine
    9. (optional) Petal internationalizes the resulting output.

If you are under a persistent environment a la mod_perl, subsequent calls to
the same template will be reduced to step 8 until the source template changes.

Otherwise, subsequent calls will resume at step 6, until the source template
changes.

If you are using the mod_perl prefork MPM, you can precompile Petal templates
into Apache's shared memory at startup by using the cache_only option.  This
will allow you to run through steps 1-7 without passing any data to Petal.


=head1 DECRYPTING WARNINGS AND ERRORS


=head2 "Cannot import module $module. Reason: $@" (nonfatal)

Petal was not able to import one of the modules. This error warning will be
issued when Petal is unable to load a plugin because it has been badly install
or is just broken.


=head2 "Petal modifier encode: is deprecated" (nonfatal)

You don't need to use encode:EXPRESSION to XML-encode expression anymore,
Petal does it for you. encode: has been turned into a no-op.


=head2 Cannot find value for ... (FATAL)

You tried to invoke an/expression/like/this/one but Petal could not resolve
it. This could be because an/expression/like evaluated to undef and hence the
remaining this/one could not be resolved.

Usually Petal gives you a line number and a dump of your template as Perl
code. You can look at the perl code to try to determine the faulty bit in
your template.


=head2 not well-formed (invalid token) at ... (FATAL)

Petal was trying to parse a file that is not well-formed XML or that has strange
entities in it. Try to run xmllint on your file to see if it's well formed or
try to use the $Petal::INPUT = 'XHTML' option.


=head2 other errors

Either I've forgot to document it, or it's a bug. Send an email to the Petal
mailing list.


=head1 EXPORTS

None.


=head1 AUTHOR

Copyright 2003 - MKDoc Ltd.

Authors: Jean-Michel Hiver, 
         Fergal Daly <fergal@esatclear.ie>,
	 and others.

This module free software and is distributed under the same license as Perl
itself. Use it at your own risk.

Thanks to everybody on the list who contributed to Petal in the form of
patches, bug reports and suggestions. See README for a list of contributors.


=head1 SEE ALSO

Join the Petal mailing list:

  http://lists.webarch.co.uk/mailman/listinfo/petal

Mailing list archives:

  http://lists.webarch.co.uk/pipermail/petal


Have a peek at the TAL / TALES / METAL specs:

  http://wiki.zope.org/ZPT/TAL
  http://wiki.zope.org/ZPT/TALES
  http://wiki.zope.org/ZPT/METAL