Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PerlPoint::Anchors(3) User Contributed Perl DocumentationPerlPoint::Anchors(3)

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
SEE ALSO
       PerlPoint::Parser
	   The parser module working on	base of	the declarations.

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
       Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 1999-2004.  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:
       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.

perl v5.32.0			  2006-03-12		 PerlPoint::Anchors(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | NOTES | SEE ALSO | SUPPORT | AUTHOR | DISCLAIMER

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PerlPoint::Anchors&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help