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

FreeBSD Manual Pages

  
 
  

home | help
Test::Synopsis(3)     User Contributed Perl Documentation    Test::Synopsis(3)

NAME
       Test::Synopsis -	Test your SYNOPSIS code

SYNOPSIS
	 # xt/synopsis.t (with Module::Install::AuthorTests)
	 use Test::Synopsis;
	 all_synopsis_ok();

	 # Or, run safe	without	Test::Synopsis
	 use Test::More;
	 eval "use Test::Synopsis";
	 plan skip_all => "Test::Synopsis required for testing"	if $@;
	 all_synopsis_ok();

DESCRIPTION
       Test::Synopsis is an (author) test module to find .pm or	.pod files
       under your lib directory	and then make sure the example snippet code in
       your SYNOPSIS section passes the	perl compile check.

       Note that this module only checks the perl syntax (by wrapping the code
       with "sub") and doesn't actually	run the	code.

       Suppose you have	the following POD in your module.

	 =head1	NAME

	 Awesome::Template - My	awesome	template

	 =head1	SYNOPSIS

	   use Awesome::Template;

	   my $template	= Awesome::Template->new;
	   $tempalte->render("template.at");

	 =head1	DESCRIPTION

       An user of your module would try	copy-paste this	synopsis code and find
       that this code doesn't compile because there's a	typo in	your variable
       name $tempalte. Test::Synopsis will catch that error before you ship
       it.

VARIABLE DECLARATIONS
       Sometimes you might want	to put some undeclared variables in your
       synopsis, like:

	 =head1	SYNOPSIS

	   use Data::Dumper::Names;
	   print Dumper($scalar, \@array, \%hash);

       This assumes these variables like $scalar are defined elsewhere in
       module user's code, but Test::Synopsis, by default, will	complain that
       these variables are not declared:

	   Global symbol "$scalar" requires explicit package name at ...

       In this case, you can add the following POD sequence elsewhere in your
       POD:

	 =for test_synopsis
	 no strict 'vars'

       Or more explicitly,

	 =for test_synopsis
	 my($scalar, @array, %hash);

       Test::Synopsis will find	these "=for" blocks and	these statements are
       prepended before	your SYNOPSIS code when	being evaluated, so those
       variable	name errors will go away, without adding unnecessary bits in
       SYNOPSIS	which might confuse users.

AUTHOR
       Tatsuhiko Miyagawa <miyagawa@bulknews.net>

       Goro Fuji blogged about the original idea at
       <http://d.hatena.ne.jp/gfx/20090224/1235449381> based on	the testing
       code taken from Test::Weaken.

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

SEE ALSO
       Test::Pod, Test::UseAllModules, Test::Inline, Test::Snippet

perl v5.32.0			  2009-07-06		     Test::Synopsis(3)

NAME | SYNOPSIS | DESCRIPTION | VARIABLE DECLARATIONS | AUTHOR | LICENSE | SEE ALSO

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

home | help