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

FreeBSD Manual Pages

  
 
  

home | help
HACKING(3)	      User Contributed Perl Documentation	    HACKING(3)

NAME
       HACKING.pod - contributing to TAP::Harness

ABOUT
       This is the guide for TAP::Harness internals contributors (developers,
       testers,	documenters.)

       If you are looking for more information on how to use TAP::Harness, you
       probably	want
       <http://testanything.org/testing-with-tap/perl/tap::parser-cookbook.html>
       instead.

Getting	Started
       See the resources section in META.yml or	Build.PL for links to the
       project mailing list, bug tracker, svn repository, etc.

       For ease	of reference, at the time of writing the SVN repository	was
       at:

	 http://svn.hexten.net/tapx

       To get the latest version of trunk:

	 git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git

       For best	results, read the rest of this file, check RT for bugs which
       scratch your itch, join the mailing list, etc.

Formatting
   perltidy
       The project comes with a	".perltidyrc", which perltidy will
       automatically use if the	project	root is	your working directory.	 This
       is setup	by default to read and write the perl code on a	pipe.  To
       configure your editor:

       o   vim

	   In ".vimrc",	you can	add the	following lines:

	    nnoremap <Leader>pt	:%!perltidy -q<cr> " only work in 'normal' mode
	    vnoremap <Leader>pt	:!perltidy -q<cr>  " only work in 'visual' mode

	   In other words, if your "Leader" is a backslash, you	can type "\pt"
	   to reformat the file	using the ".perltidyrc".  If you are in	visual
	   mode	(selecting lines with shift-v),	then only the code you have
	   currently have selected will	be reformatted.

       o   emacs

	   For emacs, you can use this snippet from Sam	Tregar
	   (<http://use.perl.org/~samtregar/journal/30185>):

	    (defun perltidy-region ()
	       "Run perltidy on	the current region."
	       (interactive)
	       (save-excursion
		 (shell-command-on-region (point) (mark) "perltidy -q" nil t)
		 (cperl-mode)))

	    (defun perltidy-all	()
	       "Run perltidy on	the current region."
	       (interactive)
	       (let ((p	(point)))
		 (save-excursion
		   (shell-command-on-region (point-min)	(point-max) "perltidy -q" nil t)
		   )
		 (goto-char p)
		 (cperl-mode)))

	    (global-set-key "\M-t" `perltidy-region)
	    (global-set-key "\M-T" `perltidy-all)

Tests and Coverage
       ...

Writing	for Compatibility
       ...

Use TAP::Object
       TAP::Object is the common base class to all TAP::* modules, and should
       be for any that you write.

Exception Handling
       Exceptions should be raised with	Carp:

	 require Carp;
	 Carp::croak("Unsupported syntax version: $version");

	 require Carp;
	 Carp::confess("Unsupported syntax version: $version");

Deprecation cycle
       Any documented sub that needs to	be changed or removed (and would
       therefore cause a backwards-compat issue) must go through a deprecation
       cycle to	give developers	a chance to adjust:

	 1. Document the deprecation
	 2. Carp a suitable message
	 3. Release
	 4. Change the code
	 5. Release

Documentation
       The end-user and	API documentation is all in the	'lib/' directory.  In
       .pm files, the pod is "inline" to the code.  See	perlpod	for more about
       pod.

   Pod Commands
       For compatibility's sake, we do not use the =head3 and =head4 commands.

       "=head1 SECTION"
	   Sections begin with an "=head1" command and are all-caps.

	     NAME
	     VERSION
	     SYNOPSIS
	     CONSTRUCTOR
	     METHODS
	     CLASS METHODS
	     SOME OTHER	SORT OF	METHODS
	     SEE ALSO

       "=head2 method"
	   The "=head2"	command	documents a method.  The name of the method
	   should have no adornment (e.g. don't	C<method> or C<method($list,
	   $of,	$params)>.)

	   These sections should begin with a short description	of what	the
	   method does,	followed by one	or more	examples of usage.  If needed,
	   elaborate on	the subtleties of the parameters and context after
	   (and/or between) the	example(s).

	     =head2 this_method

	     This method does some blah	blah blah.

	       my @answer = $thing->this_method(@arguments);

	     =head2 that_thing

	     Returns true if the thing is true.

	       if($thing->that_thing) {
		 ...
	       }

       "=item parameter"
	   Use "=item" commands	for method arguments and parameters (and etc.)
	   In most html	pod formatters,	these do not get added to the table-
	   of-contents at the top of the page.

   Pod Formatting Codes
       L<Some::Module>
	   Be careful of the wording of	"L<Some::Module>".  Older pod
	   formatters would render this	as "the	Some::Module manpage", so it
	   is best to either word your links as	""(see <Some::Module> for
	   details.)"" or use the "explicit rendering" form of
	   ""<Some::Module|Some::Module>"".

   VERSION
       The version numbers are updated by Perl::Version.

   DEVELOPER DOCS/NOTES
       The following "formats" are used	with "=begin"/"=end" and "=for"
       commands	for pod	which is not part of the public	end-user/API
       documentation.

       note
	   Use this if you are uncertain about a change	to some	pod or think
	   it needs work.

	     =head2 some_method

	       ...

	     =for note
	       This is either falsely documented or a bug -- see ...

       developer
	     =begin developer

	     Long-winded explanation of	why some code is the way it is or various
	     other subtleties which might incite head-scratching and WTF'ing.

	     =end developer

       deprecated
	     =for deprecated
	       removed in 0.09,	kill by	~0.25

Committing to Subversion
       If you have commit access, please bear this in mind.

       Development is done either on trunk or a	branch,	as appropriate:

       If it's something that might be controversial, break the	build or take
       a long time (more than a	couple of weeks) to complete then it'd
       probably	be appropriate to branch. Otherwise it can go in trunk.

       If in doubt discuss it on the mailing list before you commit.

perl v5.24.1			  2015-04-17			    HACKING(3)

NAME | ABOUT | Getting Started | Formatting | Tests and Coverage | Writing for Compatibility | Use TAP::Object | Exception Handling | Deprecation cycle | Documentation | Committing to Subversion

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

home | help