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

FreeBSD Manual Pages

  
 
  

home | help
Pod::POM::Node(3)     User Contributed Perl Documentation    Pod::POM::Node(3)

NAME
       Pod::POM::Node -	base class for a POM node

SYNOPSIS
	   package Pod::POM::Node::Over;
	   use parent qw( Pod::POM::Node );
	   use vars qw(	@ATTRIBS @ACCEPT $EXPECT $ERROR	);

	   @ATTRIBS =	( indent => 4 );
	   @ACCEPT  = qw( over item begin for text verbatim );
	   $EXPECT  =  q( back );

	   package main;
	   my $list = Pod::POM::Node::Over->new(8);
	   $list->add('item', 'First Item');
	   $list->add('item', 'Second Item');
	   ...

DESCRIPTION
       This documentation describes the	inner workings of the Pod::POM::Node
       module and gives	a brief	overview of the	relationship between it	and
       its derived classes.  It	is intended more as a guide to the internals
       for interested hackers than as general user documentation.  See
       Pod::POM	for information	on using the modules.

       This module implements a	base class node	which is subclassed to
       represent different elements within a Pod Object	Model.

	   package Pod::POM::Node::Over;
	   use parent qw( Pod::POM::Node );

       The base	class implements the new() constructor method to instantiate
       new node	objects.

	   my $list = Pod::POM::Node::Over->new();

       The characteristics of a	node can be specified by defining certain
       variables in the	derived	class package.	The @ATTRIBS list can be used
       to denote attributes that the node should accept.  In the case of an
       "=over" node, for example, an "indent" attribute	can be specified which
       otherwise defaults to 4.

	   package Pod::POM::Node::Over;
	   use parent qw( Pod::POM::Node );
	   use vars qw(	@ATTRIBS $ERROR	);

	   @ATTRIBS = (	indent => 4 );

       The new() method	will now expect	an argument to set the indent value,
       or will use 4 as	the default if no argument is provided.

	   my $list = Pod::POM::Node::Over->new(8);    # indent: 8
	   my $list = Pod::POM::Node::Over->new( );    # indent: 4

       If the default value is undefined then the argument is mandatory.

	   package Pod::POM::Node::Head1;
	   use parent qw( Pod::POM::Node );
	   use vars qw(	@ATTRIBS $ERROR	);

	   @ATTRIBS = (	title => undef );

	   package main;
	   my $head = Pod::POM::Node::Head1->new('My Title');

       If a mandatory argument isn't provided then the constructor will	return
       undef to	indicate failure.  The $ERROR variable in the derived class
       package is set to contain a string of the form "$type expected a
       $attribute".

	   # dies with error: "head1 expected a	title"
	   my $head = Pod::POM::Node::Head1->new()
	       || die $Pod::POM::Node::Head1::ERROR;

       For convenience,	the error() subroutine can be called as	a class	method
       to retrieve this	value.

	   my $type = 'Pod::POM::Node::Head1';
	   my $head = $type->new()
	       || die $type->error();

       The @ACCEPT package variable can	be used	to indicate the	node types
       that are	permitted as children of a node.

	   package Pod::POM::Node::Head1;
	   use parent qw( Pod::POM::Node );
	   use vars qw(	@ATTRIBS @ACCEPT $ERROR	);

	   @ATTRIBS =	( title	=> undef );
	   @ACCEPT  = qw( head2	over begin for text verbatim );

       The add() method	can then be called against a node to add a new child
       node as part of its content.

	   $head->add('over', 8);

       The first argument indicates the	node type.  The	@ACCEPT	list is
       examined	to ensure that the child node type is acceptable for the
       parent node.  If	valid, the constructor for the relevant	child node
       class is	called passing any remaining arguments as attributes.  The new
       node is then returned.

	   my $list = $head->add('over', 8);

       The error() method can be called	against	the parent node	to retrieve
       any constructor error generated by the child node.

	   my $list = $head->add('over', 8);
	   die $head->error() unless defined $list;

       If the child node is not	acceptable to the parent then the add()	method
       returns one of the constants IGNORE, REDUCE or REJECT, as defined in
       Pod::POM::Constants.  These return values are used by the Pod::POM
       parser module to	implement a simple shift/reduce	parser.

       In the most common case,	IGNORE is returned to indicate that the	parent
       node doesn't know anything about	the new	child node.  The parser	uses
       this as an indication that it should back up through the	parse stack
       until it	finds a	node which will	accept this child node.	 Through this
       mechanism, the parser is	able to	implicitly terminate certain POD
       blocks.	For example, a list item initiated by a	"=item"	tag will not
       accept another "=item" tag, but will instead return IGNORE.  The	parser
       will back out until it finds the	enclosing "=over" node which will
       accept it.  Thus, a new "=item" implicitly terminates any previous
       "=item".

       The $EXPECT package variable can	be used	to indicate a node type	which
       a parent	expects	to terminate itself.  An "=over" node, for example,
       should always be	terminated by a	matching "=back".  When	such a match
       is made,	the add() method returns REDUCE	to indicate successful
       termination.

	   package Pod::POM::Node::Over;
	   use parent qw( Pod::POM::Node );
	   use vars qw(	@ATTRIBS @ACCEPT $EXPECT $ERROR	);

	   @ATTRIBS =	( indent => 4 );
	   @ACCEPT  = qw( over item begin for text verbatim );
	   $EXPECT  =  q( back );

	   package main;
	   my $list = Pod::POM::Node::Over->new();
	   my $item = $list->add('item');
	   $list->add('back');		       # returns REDUCE

       If a child node isn't specified in the @ACCEPT list or doesn't match
       any $EXPECT specified then REJECT is returned.  The parent node sets an
       internal	error of the form "$type expected a terminating	$expect".  The
       parser uses this	to detect missing POD tags.  In	nearly all cases the
       parser is smart enough to fix the incorrect structure and downgrades
       any errors to warnings.

	   # dies with error 'over expected terminating	back'
	   ref $list->add('head1', 'My Title')	   # returns REJECT
	       || die $list->error();

       Each node contains a 'type' field which contains	a simple string
       indicating the node type, e.g. 'head1', 'over', etc.  The $NODES	and
       $NAMES package variables	(in the	base class) reference hash arrays
       which map these names to	and from package names (e.g. head1 <=>
       Pod::POM::Node::Head1).

	   print $list->{ type };      # 'over'

       An AUTOLOAD method is provided to access	to such	internal items for
       those who don't like violating an object's encapsulation.

	   print $list->type();

       Nodes also contain a 'content' list, blessed into the
       Pod::POM::Node::Content class, which contains the content (child
       elements) for the node.	The AUTOLOAD method returns this as a list
       reference or as a list of items depending on the	context	in which it is
       called.

	   my $items = $list->content();
	   my @items = $list->content();

       Each node also contains a content list for each individual child	node
       type that it may	accept.

	   my @items = $list->item();
	   my @text  = $list->text();
	   my @vtext = $list->verbatim();

       The present() method is used to present a node through a	particular
       view.  This simply maps the node	type to	a method which is then called
       against the view	object.	 This is known as 'double dispatch'.

	   my $view = 'Pod::POM::View::HTML';
	   print $list->present($view);

       The method name is constructed from the node type prefixed by 'view_'.
       Thus the	following are roughly equivalent.

	   $list->present($view);

	   $view->view_list($list);

       The benefit of the former over the latter is, of	course,	that the
       caller doesn't need to know or determine	the type of the	node.  The
       node itself is in the best position to determine	what type it is.

AUTHOR
       Andy Wardley <abw@kfs.org>

COPYRIGHT
       Copyright (C) 2000, 2001	Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

SEE ALSO
       Consult Pod::POM	for a general overview and examples of use.

perl v5.32.0			  2015-11-07		     Pod::POM::Node(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help