Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  PERLPOINT::TAGS (3)

.ds Aq ’


PerlPoint::Tags - processes PerlPoint tag declarations



This manual describes version <B>0.05B>.


  # declare a tag declaration package
  package PerlPoint::Tags::New;

  # declare base "class"
  use base qw(PerlPoint::Tags);


PerlPoint is built a modularized way. The base packages provide parsing and stream processing for all translators into target formats and are therefore intended to be as general as possible. That’s why they not even define tags, because every translator author may wish to provide own tags special to the addressed target projector (or format, respectively). On the other hand, the parser needs to know about tags to recognize them correctly. That is where this module comes in. It serves as a base of tag declaration modules by providing a general import() method to be inherited by them. This method scans the invoking module for certain data structures containing tag declarations and imports these data into a structure in its own namespace. The parser knows about this <B>PerlPoint::TagsB> collection and makes it the base of its tag handling.

It is recommended to have a top level tag declaration module for each PerlPoint translator, so there could be a PerlPoint::Tags::HTML, a PerlPoint::Tags::Latex, PerlPoint::Tags::SDF, a PerlPoint::Tags::XML and so on. (These modules of course may simply invoke lower level declarations.)

Note: We are speaking in terms of classes here but of course we are actually only using the mechanism of import() together with inheritance to provide an intuitive and easy to use way of declaration.

As an additional feature, the module provides a method <B>B>addTagSets()<B>B> to allow translator users to declare tags additionally. See below for details.

    Tag declaration by subclasses

So to declare tags, just write a module in the <B>PerlPoint::TagsB> namespace and make it a subclass of <B>PerlPoint::TagsB>:

  # declare a tag declaration package
  package PerlPoint::Tags::New;

  # declare base "class"
  use base qw(PerlPoint::Tags);

Now the tags can be declared. Tag declarations are expected in a global hash named <B>B>%tags<B>B>. Each key is the name of a tag, while descriptions are nested structures stored as values.

  # pragmata
  use strict;
  use vars qw(%tags %sets);

  # tag declarations
         EMPHASIZE => {
                       # options
                       options => TAGS_OPTIONAL,

                       # dont miss the body!
                       body    => TAGS_MANDATORY,

         COLORIZE => {...},

         FONTIFY  => {...},


This looks complicated but is easy to understand. Each option is decribed by a hash. The body slot just expresses if the body is obsolete, optional or mandatory. This is done by using constants provided by <B>PerlPoint::ConstantsB>. Obsolete bodies will not be recognized by the parser.

The body slot may be omitted. This means the body is optional.

There are the same choices for options in general: they may be obsolete, optional or mandatory. If the slot is omitted this means that the tag does not need any options. The parser will not accept a tag option part in this case.

To sum it up, options and body of a tag can be declared as mandatory by TAGS_MANDATORY, optional by TAGS_OPTIONAL, or obsolete by TAGS_DISABLED.

If you need further checks you can hook into the parser by using the "hook" key:

         EMPHASIZE => {
                       # options
                       options => TAGS_OPTIONAL,

                       # perform special checks
                       hook => sub {
                                    # get parameters
                                    my ($tagname, $options, $body, $anchor)=@_;

                                    # checks

                                    reply results

         COLORIZE => {...},

         FONTIFY  => {...},


An option hook function receives the tag name, a reference to a hash of option name / value pairs to check, a body array reference and an anchor object. Using the option hash reference, the hook can modify the options. The passed body array is a copy of the body part of the stream. The hook therefore cannot modify the body part on parsers side. The anchor object can be used to store new anchors or query anchors already known, see \PerlPoint::Anchors for details of this objects interface.

The following return codes are defined:
PARSING_COMPLETED Parsing will be stopped successfully.
PARSING_ERASE The parser will throw away the tag and all its content.
PARSING_ERROR A semantic error occurred. This error will be counted, but parsing will be continued to possibly detect even more errors.
PARSING_FAILED A syntactic error occured. Parsing will be stopped immediately.
PARSING_IGNORE The parser will ignore the tag, but stream the body. The result is similar to a source omitting the tag.
PARSING_OK The checked object is declared to be OK, parsing will be continued.
Hooks are an interesting way to extend document parsing, but please take into consideration that tag hooks might be called quite often. So, if checks have to be performed, users will be glad if they are performed quickly.

And there is another hook interface. It might happen that several operations need parsing to be completed before they can start, like checking an referenced anchor which might be defined after the referencing tag. To handle such situations, a subroutine can be declared as value of key finish. The parser will invoke this code when parsing is done and the tag was parsed successfully. (So if a hook function returned an error code, the finish hook will be ignored.)

Here is an example (from an implementation of the basic tag \REF):

  # afterburner
  finish =>  sub
               # declare and init variable
               my $ok=PARSING_OK;

               # take parameters
               my ($options, $anchors)=@_;

               # check link for being valid
               unless (my $anchor=$anchors->query($options->{name}))
                  warn qq(\n\n[Error] Unknown link address "$options->{name}."\n);
                  # link ok, get value (there is only one key/value pair
                  # in the received hash)
                  ($options->{__value__})=(values %$anchor);

               # supply status

Because several informations are no longer available after parsing, finish hooks have a different interface. They receive options and anchors like parsing hooks, but no line number and no body information.

Options can be modified as well as in parsing hooks. Return codes are the same, but are evaluated slightly different according to the invokation time:
PARSING_COMPLETED All right. This code is accepted for reasons of convenience, it is recommended to use PARSING_OK instead.
PARSING_ERASE The backend will ignore the tag and all its contents (which means its body).
PARSING_ERROR A semantic error occurred. This error will be counted.
PARSING_FAILED An error occured. Because parsing is already finished, this will be counted as an sematic error.

This code is accepted for reasons of convenience, it is recommended to use PARSING_ERROR instead.

PARSING_IGNORE The backend will ignore the tag, but process its body. This simply means that the tag takes no effect.
PARSING_OK All right.
The order of finish hook invokation can differ from the order of tag usage. Do not depend on it.

A finish hook is not invoked unless the tag was processed and streamed successfully at parsing time. This simply means if the parsing hook returned PARSING_OK, or if there was no parsing hook at all.

    Marking tags that can act standalone

A tag can be part of various paragraphs. A single tag in a paragraph with no prefix produces a text paragraph containing just this tag. This can be intended, but there are other cases when the tag should stand for its own.

The standalone attribute instructs the parser to strip off the wrapping paragraph from a handle that is used as its only content. If there is more content in the paragraph the paragraph wrapper will not be removed.

The flag should be set to a true value to activate the occasional paragraph stripping.


  standalone => 1,

    Using other tag definitions

One can invoke hooks of any other registered tag. This is powerful, but dangerous. Nevertheless, it helps to emulate other tags, for example if an old interface (tag and option names) shall be preserved but the new functionality shall be used (without being copied between tag modules). To invoke a foreign hook, call \PerlPoint::Tags::call() (fully qualified function name) with tag name, hook type and parameters, like so:

 $rc=PerlPoint::Tags::call(TAG, hook, @_);

Valid hook types are hook and finish (currently). If the tag is not registered, or has no hook of the specified type, an undefined value is supplied, otherwise the return code of the invoked function.

It is not checked if you call a hook function from a finish hook or vice versa. Take care!

This feature is made available to interchange hooks between several tag definition modules. If you want to share hook functions between tags declared by the same tag module, it is recommended to use common Perl techniques.

    Tag activation

Now, in a translator software where a parser object should be built, tag declarations can be accessed by simply loading the declaration modules, just as usual (there is no need to load <B>PerlPoint::TagsB> directly there, unless the converter should run under perl 5.005 which needs this parent module to be loaded explicitly (while perl 5.6 does is implicitly)):

  # declare all the tags to recognize
  use PerlPoint::Tags::New;

This updates a structure in the <B>PerlPoint::TagsB> namespace. The parser knows about this structure and will automatically evaluate it.

Several declaration modules can be loaded subsequently. Each new tag is added to the internal structure, while predeclared tags are overwritten by new declarations.

  # declare all the tags to recognize
  use PerlPoint::Tags::Basic;
  use PerlPoint::Tags::HTML;
  use PerlPoint::Tags::SDF;
  use PerlPoint::Tags::New;

    Activating certain tags

Certain translators might only want to support subsets of tags declared in a <B>PerlPoint::ParserB> submodule. This is possible as well, similar to the usual importing mechanism:

  # declare all the tags to recognize
  use PerlPoint::Tags::New qw(COLORIZE);

This does only declare the COLORIZE tag, but ignores EMPHASIZE and FONTIFY.

    Tag sets

To simplify activation of certain but numerous tags a declaration module can group them by setting up a global hash named %sets.

         pointto => [qw(EMPHASIZE COLORIZE)],

This allows a translator autor to activate EMPHASIZE and COLORIZE at once:

  # declare all the tags to recognize
  use PerlPoint::Tags::New qw(:pointto);

The syntax is borrowed from the usual import mechanism.

Tag sets can overlap:

         pointto => [qw(EMPHASIZE COLORIZE)],
         set2    => [qw(COLORIZE FONTIFY)],

And of course they can be nested:

         pointto => [qw(EMPHASIZE COLORIZE)],
         all     => [(:pointto, qw(FONTIFY))],

    Allowing translator users to import foreign tag declarations

As PerlPoint provides a flexible way to write translators, PerlPoint documents might be written with tags for a certain translator and later then be processed by another translator which does not support all the original tags. Of course, the second translator does not need to handle these tags, but the parser needs to know they should be recognized. On the other hand, it cannot know this from the declarations made by the second translator itself, because they of course do not contain the tags of the first translator.

The problem could be solved if there would be a way to inform the parser about the tags initially used. That’s why this module provides <B>B>addTagSets()<B>B>, a method that imports foreign declarations at run time. Suppose a translator provides an option -tagset to let a user specify which tag sets the document was initially written for. Then the following code makes them known to the parser, addtionally to the declarations the translator itself already made as usual (see above):

  # load module to access the function
  use PerlPoint::Tags;

  # get options

  # import foreign tags
    if exists $options{tagset};

(Note: this example is based on the <B>Getopt::LongB> option access interface. Other interfaces might need adaptations.)

Tags imported via addTagSets() do not overwrite original definitions.

A tag set, in this context, is the set of tag declarations a certain translator makes. So, the attributes to <B>B>addTagSets()<B>B> are expected to be target languages corresponding to the translators name, making usage easy for the user. So, pp2sdf is expected to provide a tag set declaration module PerlPoint::Tags::<B>SDFB>, pp2html PerlPoint::Tags::<B>HTMLB>, pp2xml PerlPoint::Tags::<B>XMLB> and so on.

If all translators provide this same interface, usage should be easy. A user who wrote a document with pp2html in mind, passing it to pp2sdf which provides significantly less tags, only has to add the option "-tagset HTML" to the pp2sdf call to make his document pass the PerlPoint parser.



Imports tagsets. See Allowing translator users to import foreign tag declarations for details.


Calls a hook function of a registered tag. See Using other tag definitions for details.


The form of tag declaration provided by this module is designed to make tag activation intuitive to write and read. Ideally, declarations are written by one author, but used by several others.

Each tag declaration module should provide a tag description in PerlPoint. This allows translator authors to easily integrate tag descriptions into their own documentations.

Tag declarations have nothing to do with the way backends (translators) handle recognized tags. They only enable tag detection and a few simple semantic checks by the parser. A translator has still to implement its tag handling itself.

There are no tag namespaces. Although Perl modules are used to declare the tags, tags declared by various PerlPoint::Tags::Xyz share the same one global scope. This means that different tags should be named different. <B>PerlPoint::TagsB> displays a warning if a tag is overwritten by another one.


<B>PerlPoint::ParserB> The parser module working on base of the declarations.
<B>PerlPoint::Tags::xyzB> Various declaration modules.


A PerlPoint mailing list is set up to discuss usage, ideas, bugs, suggestions and translator development. To subscribe, please send an empty message to

If you prefer, you can contact me via as well.


Copyright (c) Jochen Stenzel (, 1999-2001. All rights reserved.

This module is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.

The Artistic License should have been included in your distribution of Perl. It resides in the file named Artistic at the top-level of the Perl source tree (where Perl was downloaded/unpacked - ask your system administrator if you dont know where this is). Alternatively, the current version of the Artistic License distributed with Perl can be viewed on-line on the World-Wide Web (WWW) from the following URL:


This software is distributed in the hope that it will be useful, but is provided AS IS WITHOUT WARRANTY OF ANY KIND, either expressed or implied, INCLUDING, without limitation, the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.

The ENTIRE RISK as to the quality and performance of the software IS WITH YOU (the holder of the software). Should the software prove defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.


Please refer to the Artistic License that came with your Perl distribution for more details.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 PERLPOINT::TAGS (3) 2006-03-12

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.