GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TEST::HACKING (3)

.ds Aq ’

NAME

HACKING.pod - contributing to TAP::Harness

CONTENTS

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 WTFing.

  =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.

Search for    or go to Top of page |  Section 3 |  Main Index


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

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.