NAME

PerlPoint::Anchors - simple anchor collection class

VERSION

This manual describes version 0.03.

SYNOPSIS

  # make a new object
  my $anchors=new PerlPoint::Anchors;

  # register an anchor
  $anchors->add('page number', '500');

  # check an anchor for being known
  ... if $anchors->query('page number');

  # get a list of all registered anchors
  my %regAnchors=%{$anchors->query};

DESCRIPTION

Anchors are no part of the PerlPoint language definition, but used by various tags which either define or reference them. To support those tags, this simple collection class was implemented. It provides a consistent and general interface for dealing with anchors.

By using the module, one can register an anchor together with a value and query these data later, to check if a certain anchor was already registered or to access the anchor related value. A value can be any valid Perl data. Additionally, the complete collection can be requested.

METHODS

new()

The constructor builds and prepares a new collection object. You may have more than one object at a certain time, they work independently.

Parameters:

class: The class name.
class: An optional prefix for generic anchor names. Defaults to "__GANCHOR__".

Returns: the new object.

Example:

  my $anchors=new PerlPoint::Anchors;

add()

Registers a new anchor together with a related value. The value is optional and might be whatever data Perl allows to store via a scalar.

Parameters:

object: An object made by "new".
name: The anchors name. This is a string. It is not checked if the name was already registered before, an existing entry will be overwritten quietly.
value: Data related to the anchor. This is an scalar. The object does nothing with it then storing and providing it on request, so it is up to the user what kind of data is collected here.
page: The absolute number of the page the anchor is located in. This counting starts with 1 for the first chapter and continues with 2, 3 etc. regardless of chapter levels.

Returns: the object.

Example:

  $anchors->add('new anchor', [{new=>'anchor'}], 17);

query()

Requests anchors from the collection. This can be either the complete collection or just one entry. The method can be used both to check if an anchor was registered and to get its value.

Parameters:

object: An object made by "new()".
name: The name of the anchor of interest.
This parameter is optional.

Returns:

If no "name" was passed, the complete collection is provided as a reference to a hash containing name-value/page-pairs. The referenced hash is the objects own hash used internally, so modifications will affect the object.

If an anchor name was passed and this name was registered, a hash reference is provided as well (for reasons of consistency). The referenced hash is a copy and contains the appropriate pair of anchor name and a reference to an array of its value and page.

If an anchor name was passed and this name was not registered, the method returns an undefined value.

Examples:

  # check an anchor for being known
  ... if $anchors->query('new anchor');

  # get the value of an anchor
  if ($anchors->query('new anchor'))
   {$value=$anchors->query('new anchor')->{'new anchor'};}

  # get the collection
  my %anchorHash=%{$anchors->query};

checkpoint()

Activates or deactivates logging of all anchors added after this call. By default, logging is switched off.

The list of new anchors can be requested by a call of reportNew().

Previous logs are reset by a new call of "checkpoint()".

Parameters:

object: An object made by "new".
logging mode: Logging is activated by a true value, disabled otherwise.

Returns: the object.

Example:

  $anchors->checkpoint;

reportNew()

Reports anchors added after the last recent call of "checkpoint()". If the "checkpoint()" invokation disabled anchor logging, the result will by empty even if anchors were added.

Requesting the log does not reset the logging data. To reset it, checkpoint() needs to be called again.

Parameters:

object: An object made by "new".

Returns: A reference to a hash containing names and values of newly added anchors. The supplied hash can be modified without effect to the object.

Example:

  my $newAnchorHash=$anchors->reportNew;

generic()

Supplies a generic anchor name build according to the pattern /^<generic prefix>\d+$/ (with the <generic prefix> set up in the call of new()) - so it is recommended not to use those names explicitly.

Parameters:

object: An object made by "new".

Returns: The new anchor name.

Example:

  $anchors->add($anchors->generic, $data);

NOTES

SUPPORT

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

If you prefer, you can contact me via perl@jochen-stenzel.de as well.

AUTHOR

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: http://www.perl.com/perl/misc/Artistic.html

DISCLAIMER

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.

IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even if they arise from known or unknown flaws in the software).

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