HACKING(3pm)

📦
version 3.52 · 11 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay bestie, this is HACKING.pod — the whole vibe is contributing to TAP::Harness. That's it, that's the name, slay. ✨

🦋 ABOUT 🦋

So like, this page? It's the guide for TAP::Harness internals contributors — that means developers, testers, and documenters. All three. The whole squad. 💅

If you're actually here looking for info on how to use TAP::Harness (not hack on it, just use it, which is also valid), you probably want this instead:

http://testanything.org/testing-with-tap/perl/tap-parser-cookbook.html

no cap, go there, it's the right one for you. 🫶

🌸 Getting Started 🌸

Lowkey first move: check the resources section in META.yml or Build.PL — that's where the links live for the project mailing list, the bug tracker, the svn repository, etc. etc. ✨

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

http://svn.hexten.net/tapx

And to get the latest version of trunk:

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

For best results (and honestly this is the main character move): read the rest of this file, check RT for bugs which scratch your itch, join the mailing list, etc. Do the whole loop. It's giving community. 🌈

🎀 Formatting 🎀

perltidy

The project comes with a .perltidyrc, and perltidy will automatically use it if the project root is your working directory. It's set up by default to read and write the perl code on a pipe. To configure your editor:

  • 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. And if you're in visual mode (selecting lines with shift-v), then only the code you currently have selected will be reformatted. iconic. 💅

(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 bestie, it should be the base class for any that you write. no exceptions, periodt. 💜

🔥 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, so developers get a chance to adjust. You can't just yank it, that's not the vibe:

  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 they're 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. lowkey underrated. 🙈

🎀 Pod Formatting Codes 🎀

  • L<Some::Module> — be careful with the wording of L<Some::Module>, bestie. Older pod formatters would render this as the Some::Module manpage, so it's 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. iykyk. ✨

  • note — use this if you're 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 — for the long lore:
=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.

And if in doubt? Discuss it on the mailing list before you commit. Don't be the one who raw-dogs a commit into trunk and starts drama. 💀

okay that's the whole page, bestie, you ate it 💅✨ this was perl v5.40.1, dated 2025-08-10, from the User Contributed Perl Documentation fam — HACKING(3pm), signing off 🎀🦋

📦 where this page comes from