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

FreeBSD Manual Pages

  
 
  

home | help
TAP::Parser::SourceHandPerl3Programmers	ReferenceTAP::Parser::SourceHandler(3)

NAME
       TAP::Parser::SourceHandler - Base class for different TAP source
       handlers

VERSION
       Version 3.38

SYNOPSIS
	 # abstract class - don't use directly!
	 # see TAP::Parser::IteratorFactory for	general	usage

	 # must	be sub-classed for use
	 package MySourceHandler;
	 use base 'TAP::Parser::SourceHandler';
	 sub can_handle	   { return $confidence_level }
	 sub make_iterator { return $iterator }

	 # see example below for more details

DESCRIPTION
       This is an abstract base	class for TAP::Parser::Source handlers /
       handlers.

       A "TAP::Parser::SourceHandler" does whatever is necessary to produce &
       capture a stream	of TAP from the	raw source, and	package	it up in a
       TAP::Parser::Iterator for the parser to consume.

       "SourceHandlers"	must implement the source detection _ handling
       interface used by TAP::Parser::IteratorFactory.	At 2 methods, the
       interface is pretty simple: "can_handle"	and "make_source".

       Unless you're writing a new TAP::Parser::SourceHandler, a plugin, or
       subclassing TAP::Parser,	you probably won't need	to use this module
       directly.

METHODS
   Class Methods
       "can_handle"

       Abstract	method.

	 my $vote = $class->can_handle(	$source	);

       $source is a TAP::Parser::Source.

       Returns a number	between	0 & 1 reflecting how confidently the raw
       source can be handled.  For example, 0 means the	source cannot handle
       it, 0.5 means it	may be able to,	and 1 means it definitely can.	See
       "detect_source" in TAP::Parser::IteratorFactory for details on how this
       is used.

       "make_iterator"

       Abstract	method.

	 my $iterator =	$class->make_iterator( $source );

       $source is a TAP::Parser::Source.

       Returns a new TAP::Parser::Iterator object for use by the TAP::Parser.
       "croak"s	on error.

SUBCLASSING
       Please see "SUBCLASSING"	in TAP::Parser for a subclassing overview, and
       any of the subclasses that ship with this module	as an example.	What
       follows is a quick overview.

       Start by	familiarizing yourself with TAP::Parser::Source	and
       TAP::Parser::IteratorFactory.  TAP::Parser::SourceHandler::RawTAP is
       the easiest sub-class to	use as an example.

       It's important to point out that	if you want your subclass to be
       automatically used by TAP::Parser you'll	have to	and make sure it gets
       loaded somehow.	If you're using	prove you can write an App::Prove
       plugin.	If you're using	TAP::Parser or TAP::Harness directly (e.g.
       through a custom	script,	ExtUtils::MakeMaker, or	Module::Build) you can
       use the "config"	option which will cause	"load_sources" in
       TAP::Parser::IteratorFactory to load your subclass).

       Don't forget to register	your class with	"register_handler" in
       TAP::Parser::IteratorFactory.

   Example
	 package MySourceHandler;

	 use strict;

	 use MySourceHandler; #	see TAP::Parser::SourceHandler
	 use TAP::Parser::IteratorFactory;

	 use base 'TAP::Parser::SourceHandler';

	 TAP::Parser::IteratorFactory->register_handler( __PACKAGE__ );

	 sub can_handle	{
	     my	( $class, $src ) = @_;
	     my	$meta	= $src->meta;
	     my	$config	= $src->config_for( $class );

	     if	($config->{accept_all})	{
		 return	1.0;
	     } elsif (my $file = $meta->{file})	{
		 return	0.0 unless $file->{exists};
		 return	1.0 if $file->{lc_ext} eq '.tap';
		 return	0.9 if $file->{shebang}	&& $file->{shebang} =~ /^#!.+tap/;
		 return	0.5 if $file->{text};
		 return	0.1 if $file->{binary};
	     } elsif ($meta->{scalar}) {
		 return	0.8 if $$raw_source_ref	=~ /\d\.\.\d/;
		 return	0.6 if $meta->{has_newlines};
	     } elsif ($meta->{array}) {
		 return	0.8 if $meta->{size} < 5;
		 return	0.6 if $raw_source_ref->[0] =~ /foo/;
		 return	0.5;
	     } elsif ($meta->{hash}) {
		 return	0.6 if $raw_source_ref->{foo};
		 return	0.2;
	     }

	     return 0;
	 }

	 sub make_iterator {
	     my	($class, $source) = @_;
	     # this is where you manipulate the	source and
	     # capture the stream of TAP in an iterator
	     # either pick a TAP::Parser::Iterator::* or write your own...
	     my	$iterator = TAP::Parser::Iterator::Array->new([	'foo', 'bar' ]);
	     return $iterator;
	 }

	 1;

AUTHORS
       TAPx Developers.

       Source detection	stuff added by Steve Purkis

SEE ALSO
       TAP::Object, TAP::Parser, TAP::Parser::Source, TAP::Parser::Iterator,
       TAP::Parser::IteratorFactory, TAP::Parser::SourceHandler::Executable,
       TAP::Parser::SourceHandler::Perl, TAP::Parser::SourceHandler::File,
       TAP::Parser::SourceHandler::Handle, TAP::Parser::SourceHandler::RawTAP

perl v5.26.0			  2017-04-19	 TAP::Parser::SourceHandler(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | SUBCLASSING | AUTHORS | SEE ALSO

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

home | help