1 2 3# = HISTORY SECTION ===================================================================== 4 5# --------------------------------------------------------------------------------------- 6# version | date | author | changes 7# --------------------------------------------------------------------------------------- 8# 0.19 |07.03.2006| JSTENZEL | added DUMMY_TOKEN; 9# 0.18 |15.12.2005| JSTENZEL | internal helper routine name now begins with underscore; 10# 0.17 |15.06.2003| JSTENZEL | added DIRECTIVE_EVERY constant; 11# |10.09.2003| JSTENZEL | added DIRECTIVE_DPOINT_TEXT constant; 12# |08.07.2004| JSTENZEL | added TEMPLATE_ACTION_... constants; 13# 0.16 |< 02.03.02| JSTENZEL | added DIRECTIVE_DSTREAM_ENTRYPOINT constant; 14# |02.03.2002| JSTENZEL | added DSTREAM_... constants; 15# |29.09.2002| JSTENZEL | added STREAM_DOCSTREAMS; 16# |02.01.2003| JSTENZEL | added TRACE_TMPFILES; 17# 0.15 |10.08.2001| JSTENZEL | added STREAM_... constants; 18# | | JSTENZEL | reorganized POD slightly; 19# |14.08.2001| JSTENZEL | added missed doc of TAG_... constants; 20# |29.09.2001| JSTENZEL | removed STREAM_CONTROL; 21# |13.11.2001| JSTENZEL | added PARSING_IGNORE and PARSING_ERASE; 22# |14.11.2001| JSTENZEL | added STREAM_DIR_ index constants; 23# 0.14 |28.05.2001| JSTENZEL | added DIRECTIVE_VARRESET; 24# |12.06.2001| JSTENZEL | added PARSING_... constants; 25# 0.13 |18.03.2001| JSTENZEL | added tag constants; 26# 0.12 |14.03.2001| JSTENZEL | added mailing list hint to POD; 27# 0.11 |20.01.2001| JSTENZEL | added new constant DIRECTIVE_VARSET; 28# 0.10 |07.12.2000| JSTENZEL | new namespace PerlPoint; 29# 0.09 |18.11.2000| JSTENZEL | added new CACHE constants; 30# 0.08 |28.10.2000| JSTENZEL | added new constant TRACE_ACTIVE; 31# 0.07 |07.10.2000| JSTENZEL | added new constant DIRECTIVE_NEW_LINE; 32# | | JSTENZEL | sligthly improved POD; 33# 0.06 |27.05.2000| JSTENZEL | updated POD; 34# 0.05 |11.04.2000| JSTENZEL | added new paragraph constants: xxx_DPOINT; 35# 0.04 |07.04.2000| JSTENZEL | added new paragraph constants: xxx_UPOINT, xxx_OPOINT; 36# |08.04.2000| JSTENZEL | added new paragraph constants: xxx_xSHIFT; 37# |09.04.2000| JSTENZEL | START/STOP constants are now in the same range as 38# | | | directives to avoid comparison trouble in tests; 39# |14.04.2000| JSTENZEL | new directives: list envelopes; 40# 0.03 |13.10.1999| JSTENZEL | updated POD; 41# 0.02 |11.10.1999| JSTENZEL | renamed into PP::Constants; 42# | | JSTENZEL | adapted POD to pod2text (needs more blank lines); 43# | | JSTENZEL | added backend constants; 44# 0.01 |09.10.1999| JSTENZEL | derived from the PP::Parser draft. 45# --------------------------------------------------------------------------------------- 46 47# = POD SECTION ========================================================================= 48 49=head1 NAME 50 51B<PerlPoint::Constants> - public PerlPoint module constants 52 53=head1 VERSION 54 55This manual describes version B<0.19>. 56 57=head1 DESCRIPTION 58 59The module declares a number of constants shared between other 60B<PerlPoint::...> modules. 61 62=head1 SYNOPSIS 63 64The I<usage> of the provided constants is described in the manuals 65of the using modules B<PerlPoint::Parser> and B<PerlPoint::Backend>. 66 67=head1 CONSTANTS 68 69=cut 70 71# declare package 72package PerlPoint::Constants; 73 74# declare version 75$VERSION=$VERSION=0.19; 76 77# startup actions 78BEGIN 79 { 80 # declare startup helper function 81 sub _startupGenerateConstants 82 { 83 # init counter 84 my $c=0; 85 86 # and generate constants 87 foreach my $constant (@_) 88 {eval "use constant $constant => $c"; $c++;} 89 } 90 91=pod 92 93=head2 Stream directive constants 94 95These constants are built into I<directives> which the parser produces 96in its output (that is, the representation format it translates an ASCII 97text in to be subsequently processed by a backend). 98 99=over 4 100 101=item DIRECTIVE_BLOCK 102 103flags a block paragraph; 104 105=item DIRECTIVE_COMMENT 106 107flags a comment; 108 109=item DIRECTIVE_COMPLETE 110 111a format entity is completed; 112 113=item DIRECTIVE_DOCUMENT 114 115flags a complete document (made from one ASCII file); 116 117=item DIRECTIVE_DLIST 118 119flags a "definition list"; 120 121=item DIRECTIVE_DPOINT 122 123flags a "definition point" paragraph; 124 125=item DIRECTIVE_DPOINT_ITEM 126 127flags a "definition point" item (the stuff to be defined); 128 129=item DIRECTIVE_DPOINT_TEXT 130 131flags a "definition point" text (the definition part); 132 133=item DIRECTIVE_DSTREAM_ENTRYPOINT 134 135flags the switch into another document stream; 136 137=item DIRECTIVE_HEADLINE 138 139flags a headline; 140 141=item DIRECTIVE_LIST_LSHIFT 142 143control directive, shift a list left; 144 145=item DIRECTIVE_LIST_RSHIFT 146 147control directive, shift a list right; 148 149=item DIRECTIVE_NEW_LINE 150 151a backend hint to inform about a new source line; 152 153=item DIRECTIVE_OLIST 154 155flags an "ordered list"; 156 157=item DIRECTIVE_OPOINT 158 159flags an "ordered point" paragraph; 160 161=item DIRECTIVE_SIMLPE 162 163a pseudo directive, used to flag simple strings in backends; 164 165=item DIRECTIVE_START 166 167a format entity starts; 168 169=item DIRECTIVE_TAG 170 171flags a tag; 172 173=item DIRECTIVE_TEXT 174 175flags a text paragraph; 176 177=item DIRECTIVE_ULIST 178 179flags an "unordered list"; 180 181=item DIRECTIVE_UPOINT 182 183flags an "unordered point" paragraph; 184 185=item DIRECTIVE_VARRESET 186 187a backend hint flagging that I<all> variables are deleted; 188 189=item DIRECTIVE_VARSET 190 191a backend hint propagating a variable setting; 192 193=item DIRECTIVE_VERBATIM 194 195flags a verbatim block paragraph; 196 197=back 198 199=cut 200 201 # directive constants 202 _startupGenerateConstants( 203 'DIRECTIVE_EVERY', # pseudo_directive used in backend; 204 205 'DIRECTIVE_START', # entity start; 206 'DIRECTIVE_COMPLETE', # entity complete; 207 208 'DIRECTIVE_BLOCK', # block; 209 'DIRECTIVE_COMMENT', # comment; 210 'DIRECTIVE_DLIST', # definition list; 211 'DIRECTIVE_DOCUMENT', # document; 212 'DIRECTIVE_DPOINT', # definition list point; 213 'DIRECTIVE_DPOINT_ITEM', # defined item; 214 'DIRECTIVE_DPOINT_TEXT', # definition text; 215 'DIRECTIVE_HEADLINE', # headline; 216 'DIRECTIVE_LIST_LSHIFT', # shift list left; 217 'DIRECTIVE_LIST_RSHIFT', # shift list right; 218 'DIRECTIVE_NEW_LINE', # backend line hint; 219 'DIRECTIVE_OLIST', # ordered list; 220 'DIRECTIVE_OPOINT', # ordered list point; 221 'DIRECTIVE_TAG', # tag; 222 'DIRECTIVE_TEXT', # text; 223 'DIRECTIVE_ULIST', # unordered list; 224 'DIRECTIVE_UPOINT', # unordered list point; 225 'DIRECTIVE_VARSET', # backend hint: variable setting; 226 'DIRECTIVE_VARRESET', # backend hint: reset *all* variables; 227 'DIRECTIVE_VERBATIM', # verbatim; 228 'DIRECTIVE_DSTREAM_ENTRYPOINT', # document stream entry point; 229 230 'DIRECTIVE_SIMPLE', # a pseudo directive (never used directly - MUST be the last here!); 231 ); 232 233=pod 234 235=head2 Parser constants 236 237control how the parser continues processing, usually used by tag hooks. 238 239=over 4 240 241=item PARSING_COMPLETED 242 243We read all we need. Stop parsing successfully. 244 245=item PARSING_ERASE 246 247Ignore the tag I<and all its contents> (which means its body). 248 249=item PARSING_ERROR 250 251A semantic error occurred. Parsing will usually be continued 252to possibly detect even more errors. 253 254=item PARSING_FAILED 255 256A syntactic error occured. Parsing will be stopped immediately. 257 258=item PARSING_IGNORE 259 260Ignore the tag as if it was not written. 261 262=item PARSING_OK 263 264Input ok, parsing can be continued. 265 266=back 267 268=cut 269 270 # parser constants 271 _startupGenerateConstants( 272 'PARSING_OK', # all right, proceed; 273 'PARSING_COMPLETED', # we know without further parsing that the input was perfect; 274 'PARSING_ERROR', # a semantic error occured; 275 'PARSING_FAILED', # a syntactical error occured; 276 'PARSING_IGNORE', # ignore the tag; 277 'PARSING_ERASE', # ignore the tag *and all its content*; 278 ); 279 280 281=pod 282 283=head2 Tag definition constants 284 285flagging mode of tag components. 286 287=over 4 288 289=item TAGS_OPTIONAL 290 291the item can be used but is not required. 292 293=item TAGS_MANDATORY 294 295the item is an essential tag part. 296 297=item TAGS_DISABLED 298 299the item must not be used. 300 301=back 302 303=cut 304 305 306 # tag constants 307 _startupGenerateConstants( 308 'TAGS_OPTIONAL', # something is optional; 309 'TAGS_MANDATORY', # something is mandatory; 310 'TAGS_DISABLED', # something is disabled (not necessary); 311 ); 312 313 314 315=pod 316 317=head2 Stream data structure part constants 318 319index constants to access parts of the intermediate data structure produced 320by the parser and processed by backends. Intended to be used by C<PerlPoint::Parser> 321and C<PerlPoint::Backend>. 322 323=over 4 324 325=item STREAM_IDENT 326 327stream data identifier - a string identifying the data structure as a PerlPoint stream. 328 329=item STREAM_DOCSTREAMS 330 331a list of all detected document stream identifiers. 332 333=item STREAM_TOKENS 334 335token stream. 336 337=item STREAM_HEADLINES 338 339headline stream. 340 341=back 342 343=cut 344 345 346 # stream data structure part constants 347 _startupGenerateConstants( 348 'STREAM_IDENT', # stream data identifier; 349 'STREAM_DOCSTREAMS', # list of document streams (hash); 350 'STREAM_TOKENS', # token stream; 351 'STREAM_HEADLINES', # headline stream; 352 ); 353 354 355=pod 356 357=head2 Stream directive data structure index constants 358 359index constants to access parts of a stream directive. 360 361=over 4 362 363=item STREAM_DIR_HINTS 364 365a hash filled by the parser to control backend behaviour. 366 367=item STREAM_DIR_TYPE 368 369directive type constant (C<DIRECTIVE_HEADLINE>, C<DIRECTIVE_TAG> etc.) 370 371=item STREAM_DIR_STATE 372 373start/completion flag (C<DIRECTIVE_START>, C<DIRECTIVE_COMPLETE>). 374 375=item STREAM_DIR_DATA 376 377beginning of the data part, depends on directive type. 378 379 380=back 381 382=cut 383 384 385 # stream directive data structure index constants 386 _startupGenerateConstants( 387 'STREAM_DIR_HINTS', # backend hints stored by the parser; 388 'STREAM_DIR_TYPE', # directive type; 389 'STREAM_DIR_STATE', # directive state (starting, complete); 390 'STREAM_DIR_DATA', # data part (index of first element); 391 ); 392 393 394=pod 395 396=head2 Document stream handling constants 397 398declare how document streams should be handled by the parser. 399 400=over 4 401 402=item DSTREAM_DEFAULT 403 404Document stream entry points are streamed directly - so the backend 405can handle them. 406 407=item DSTREAM_IGNORE 408 409Document streams (except of the main stream) are completely ignored. 410 411=item DSTREAM_HEADLINES 412 413Document stream entry points are streamed as headlines. 414 415=back 416 417=cut 418 419 # declare display constants 420 _startupGenerateConstants( 421 'DSTREAM_DEFAULT', # just stream them; 422 'DSTREAM_IGNORE', # ignore all streams except of "main"; 423 'DSTREAM_HEADLINES', # stream entry points as headlines; 424 ); 425 } 426 427 428 429 430=pod 431 432=head2 Trace constants 433 434They activate trace code. 435 436=over 4 437 438=item TRACE_ACTIVE 439 440activates the traces of active contents evaluation. 441 442=item TRACE_BACKEND 443 444activates backend traces; 445 446=item TRACE_LEXER 447 448activates the traces of the lexical analysis. 449 450=item TRACE_NOTHING 451 452deactivates all trace codes. (In fact, it I<does not activate> any trace. 453If you decide to combine it with other trace constants, it will cause nothing.) 454 455=item TRACE_PARAGRAPHS 456 457activates traces which show the paragraphs recognized when they are entered 458or completed. 459 460=item TRACE_PARSER 461 462activates the traces of the syntactical analysis. 463 464=item TRACE_SEMANTIC 465 466activates the traces of the semantic analysis. 467 468=item TRACE_TMPFILES 469 470deactivates the removal of temporary files. 471 472=back 473 474=cut 475 476 # declare trace constants (take care of correct values) 477 use constant 'TRACE_NOTHING' => 0; # MUST be 0! 478 use constant 'TRACE_PARAGRAPHS' => 1; 479 use constant 'TRACE_LEXER' => 2; 480 use constant 'TRACE_PARSER' => 4; 481 use constant 'TRACE_SEMANTIC' => 8; 482 use constant 'TRACE_ACTIVE' => 16; 483 use constant 'TRACE_BACKEND' => 32; 484 use constant 'TRACE_TMPFILES' => 64; 485 486=pod 487 488=head2 Display constants 489 490determine if information messages should be suppressed. 491 492=over 4 493 494=item DISPLAY_ALL 495 496all messages are displayed. (More correctly, no message is suppressed. 497If you combine this constant with other display constants, it will take 498no effect.) 499 500=item DISPLAY_NOINFO 501 502suppresses information messages; 503 504=item DISPLAY_NOWARN 505 506suppresses warnings; 507 508=back 509 510=cut 511 512 # declare display constants 513 use constant 'DISPLAY_ALL' => 0; # MUST be 0! 514 use constant 'DISPLAY_NOINFO' => 1; # suppress informations; 515 use constant 'DISPLAY_NOWARN' => 2; # suppress warnings; 516 517 518=pod 519 520=head2 Cache constants 521 522specify how presentation files shall be cached. 523 524=over 4 525 526=item CACHE_OFF 527 528Files are reparsed completely regardless of cache data. Existing cache data 529remain untouched. 530 531=item CACHE_ON 532 533While reading the presentation descriptions, cached and unchanged paragraphs 534are reloaded from the cache if possible. New or modified paragraphs are stored 535to accelerate repeated reading. 536 537Please note that this will not overwrite or remove previously stored cache data for modified 538or deleted paragraphs. Old cache data remains in the cache, while new data is added - the 539cache size continously grows. 540 541=item CACHE_CLEANUP 542 543Cleans up an existing cache before the parser starts (and possibly rebuilds it). 544 545=back 546 547=cut 548 549 # declare cache constants 550 use constant 'CACHE_OFF' => 0; # MUST be 0! Deactivates the cache. 551 use constant 'CACHE_ON' => 1; # activates the cache; 552 use constant 'CACHE_CLEANUP' => 2; # cache cleanup; 553 554 555=pod 556 557=head2 Template action constants 558 559flag which way a template engine should perform an action. 560 561=over 4 562 563=item TEMPLATE_ACTION_DOC 564 565Produce files which are needed I<once> (per document). 566 567=item TEMPLATE_ACTION_INDEX 568 569Processes the index page. 570 571=item TEMPLATE_ACTION_PAGE 572 573Produce a page. 574 575=item TEMPLATE_ACTION_PAGE_SUPPLEMENTS 576 577Produce additional files belonging to a page. 578 579=item TEMPLATE_ACTION_TOC 580 581Processes the table of contents page. 582 583=back 584 585=cut 586 587 # template action constants 588 _startupGenerateConstants( 589 'TEMPLATE_ACTION_DOC', # process doc data; 590 'TEMPLATE_ACTION_INDEX', # process index; 591 'TEMPLATE_ACTION_PAGE', # process page data; 592 'TEMPLATE_ACTION_PAGE_SUPPLEMENTS', # process page supplement files; 593 'TEMPLATE_ACTION_TOC', # process TOC template; 594 ); 595 596 597=pod 598 599=head2 String constants 600 601used for various purposes. 602 603=over 4 604 605=item DUMMY_TOKEN 606 607a pseudo token added for reasons of parsing, which the backend can delete from the stream. 608 609=back 610 611=cut 612 613 use constant DUMMY_TOKEN => '__DUMMY__TOKEN__'; 614 615# release memory 616undef &_startupGenerateConstants; 617 618 619# modules 620use Exporter; 621@ISA=qw(Exporter); 622 623# declare exports 624@EXPORT=qw( 625 DIRECTIVE_START 626 DIRECTIVE_COMPLETE 627 628 DIRECTIVE_BLOCK 629 DIRECTIVE_COMMENT 630 DIRECTIVE_DLIST 631 DIRECTIVE_DOCUMENT 632 DIRECTIVE_DPOINT 633 DIRECTIVE_DPOINT_ITEM 634 DIRECTIVE_DPOINT_TEXT 635 DIRECTIVE_DSTREAM_ENTRYPOINT 636 DIRECTIVE_HEADLINE 637 DIRECTIVE_LIST_LSHIFT 638 DIRECTIVE_LIST_RSHIFT 639 DIRECTIVE_NEW_LINE 640 DIRECTIVE_OLIST 641 DIRECTIVE_OPOINT 642 DIRECTIVE_VARRESET 643 DIRECTIVE_TAG 644 DIRECTIVE_TEXT 645 DIRECTIVE_ULIST 646 DIRECTIVE_UPOINT 647 DIRECTIVE_VARSET 648 DIRECTIVE_VERBATIM 649 650 DIRECTIVE_SIMPLE 651 652 DIRECTIVE_EVERY 653 654 TRACE_ACTIVE 655 TRACE_BACKEND 656 TRACE_LEXER 657 TRACE_NOTHING 658 TRACE_PARAGRAPHS 659 TRACE_PARSER 660 TRACE_SEMANTIC 661 TRACE_TMPFILES 662 663 DISPLAY_ALL 664 DISPLAY_NOINFO 665 DISPLAY_NOWARN 666 667 CACHE_OFF 668 CACHE_ON 669 CACHE_CLEANUP 670 671 DSTREAM_DEFAULT 672 DSTREAM_IGNORE 673 DSTREAM_HEADLINES 674 675 DUMMY_TOKEN 676 ); 677 678%EXPORT_TAGS=( 679 parsing => [qw(PARSING_OK PARSING_COMPLETED PARSING_ERROR PARSING_FAILED PARSING_IGNORE PARSING_ERASE)], 680 stream => [qw( 681 STREAM_IDENT STREAM_DOCSTREAMS STREAM_TOKENS STREAM_HEADLINES 682 STREAM_DIR_HINTS STREAM_DIR_TYPE STREAM_DIR_STATE STREAM_DIR_DATA 683 )], 684 tags => [qw(TAGS_OPTIONAL TAGS_MANDATORY TAGS_DISABLED)], 685 templates => [qw( 686 TEMPLATE_ACTION_DOC 687 TEMPLATE_ACTION_INDEX 688 TEMPLATE_ACTION_PAGE 689 TEMPLATE_ACTION_PAGE_SUPPLEMENTS 690 TEMPLATE_ACTION_TOC 691 )], 692 ); 693 694Exporter::export_ok_tags( 695 qw( 696 parsing 697 stream 698 tags 699 templates 700 ) 701 ); 702 7031; 704 705 706# = POD TRAILER SECTION ================================================================= 707 708=pod 709 710=head1 SEE ALSO 711 712=over 4 713 714=item B<PerlPoint::Parser> 715 716A parser for Perl Point ASCII texts. 717 718=item B<PerlPoint::Backend> 719 720A frame class to write Perl Point backends. 721 722=back 723 724 725=head1 SUPPORT 726 727A PerlPoint mailing list is set up to discuss usage, ideas, 728bugs, suggestions and translator development. To subscribe, 729please send an empty message to perlpoint-subscribe@perl.org. 730 731If you prefer, you can contact me via perl@jochen-stenzel.de 732as well. 733 734 735=head1 AUTHOR 736 737Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 1999-2004. 738All rights reserved. 739 740This module is free software, you can redistribute it and/or modify it 741under the terms of the Artistic License distributed with Perl version 7425.003 or (at your option) any later version. Please refer to the 743Artistic License that came with your Perl distribution for more 744details. 745 746The Artistic License should have been included in your distribution of 747Perl. It resides in the file named "Artistic" at the top-level of the 748Perl source tree (where Perl was downloaded/unpacked - ask your 749system administrator if you dont know where this is). Alternatively, 750the current version of the Artistic License distributed with Perl can 751be viewed on-line on the World-Wide Web (WWW) from the following URL: 752http://www.perl.com/perl/misc/Artistic.html 753 754 755=head1 DISCLAIMER 756 757This software is distributed in the hope that it will be useful, but 758is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or 759implied, INCLUDING, without limitation, the implied warranties of 760MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE. 761 762The ENTIRE RISK as to the quality and performance of the software 763IS WITH YOU (the holder of the software). Should the software prove 764defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR 765CORRECTION. 766 767IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, 768MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO 769ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even 770if they arise from known or unknown flaws in the software). 771 772Please refer to the Artistic License that came with your Perl 773distribution for more details. 774 775=cut 776