1HACKING(3) User Contributed Perl Documentation HACKING(3)
2
6 HACKING.pod - contributing to TAP::Harness
7
9 This is the guide for TAP::Harness internals contributors (developers,
10 testers, documenters.)
11 If you are looking for more information on how to use TAP::Harness, you
13 probably want
14 <http://testanything.org/testing-with-tap/perl/tap-parser-cookbook.html>
15 instead.
16
18 See the resources section in META.yml or Build.PL for links to the
19 project mailing list, bug tracker, svn repository, etc.
20 For ease of reference, at the time of writing the SVN repository was
22 at:
23 http://svn.hexten.net/tapx
25 To get the latest version of trunk:
27 git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
29 For best results, read the rest of this file, check RT for bugs which
31 scratch your itch, join the mailing list, etc.
32
34 perltidy
35 The project comes with a ".perltidyrc", which perltidy will
36 automatically use if the project root is your working directory. This
37 is setup by default to read and write the perl code on a pipe. To
38 configure your editor:
39 • vim
41 In ".vimrc", you can add the following lines:
43 nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode
45 vnoremap <Leader>pt :!perltidy -q<cr> " only work in 'visual' mode
46 In other words, if your "Leader" is a backslash, you can type "\pt"
48 to reformat the file using the ".perltidyrc". If you are in visual
49 mode (selecting lines with shift-v), then only the code you have
50 currently have selected will be reformatted.
51 • emacs
53 For emacs, you can use this snippet from Sam Tregar
55 (<http://use.perl.org/~samtregar/journal/30185>):
56 (defun perltidy-region ()
58 "Run perltidy on the current region."
59 (interactive)
60 (save-excursion
61 (shell-command-on-region (point) (mark) "perltidy -q" nil t)
62 (cperl-mode)))
63 (defun perltidy-all ()
65 "Run perltidy on the current region."
66 (interactive)
67 (let ((p (point)))
68 (save-excursion
69 (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
70 )
71 (goto-char p)
72 (cperl-mode)))
73 (global-set-key "\M-t" `perltidy-region)
75 (global-set-key "\M-T" `perltidy-all)
76
78 ...
79
81 ...
82
84 TAP::Object is the common base class to all TAP::* modules, and should
85 be for any that you write.
86
88 Exceptions should be raised with Carp:
89 require Carp;
91 Carp::croak("Unsupported syntax version: $version");
92 require Carp;
94 Carp::confess("Unsupported syntax version: $version");
95
97 Any documented sub that needs to be changed or removed (and would
98 therefore cause a backwards-compat issue) must go through a deprecation
99 cycle to give developers a chance to adjust:
100 1. Document the deprecation
102 2. Carp a suitable message
103 3. Release
104 4. Change the code
105 5. Release
106
108 The end-user and API documentation is all in the 'lib/' directory. In
109 .pm files, the pod is "inline" to the code. See perlpod for more about
110 pod.
111 Pod Commands
113 For compatibility's sake, we do not use the =head3 and =head4 commands.
114 "=head1 SECTION"
116 Sections begin with an "=head1" command and are all-caps.
117 NAME
119 VERSION
120 SYNOPSIS
121 CONSTRUCTOR
122 METHODS
123 CLASS METHODS
124 SOME OTHER SORT OF METHODS
125 SEE ALSO
126 "=head2 method"
128 The "=head2" command documents a method. The name of the method
129 should have no adornment (e.g. don't C<method> or C<method($list,
130 $of, $params)>.)
131 These sections should begin with a short description of what the
133 method does, followed by one or more examples of usage. If needed,
134 elaborate on the subtleties of the parameters and context after
135 (and/or between) the example(s).
136 =head2 this_method
138 This method does some blah blah blah.
140 my @answer = $thing->this_method(@arguments);
142 =head2 that_thing
144 Returns true if the thing is true.
146 if($thing->that_thing) {
148 ...
149 }
150 "=item parameter"
152 Use "=item" commands for method arguments and parameters (and etc.)
153 In most html pod formatters, these do not get added to the table-
154 of-contents at the top of the page.
155 Pod Formatting Codes
157 L<Some::Module>
158 Be careful of the wording of "L<Some::Module>". Older pod
159 formatters would render this as "the Some::Module manpage", so it
160 is best to either word your links as ""(see <Some::Module> for
161 details.)"" or use the "explicit rendering" form of
162 ""<Some::Module|Some::Module>"".
163 VERSION
165 The version numbers are updated by Perl::Version.
166 DEVELOPER DOCS/NOTES
168 The following "formats" are used with "=begin"/"=end" and "=for"
169 commands for pod which is not part of the public end-user/API
170 documentation.
171 note
173 Use this if you are uncertain about a change to some pod or think
174 it needs work.
175 =head2 some_method
177 ...
179 =for note
181 This is either falsely documented or a bug -- see ...
182 developer
184 =begin developer
185 Long-winded explanation of why some code is the way it is or various
187 other subtleties which might incite head-scratching and WTF'ing.
188 =end developer
190 deprecated
192 =for deprecated
193 removed in 0.09, kill by ~0.25
194
196 If you have commit access, please bear this in mind.
197 Development is done either on trunk or a branch, as appropriate:
199 If it's something that might be controversial, break the build or take
201 a long time (more than a couple of weeks) to complete then it'd
202 probably be appropriate to branch. Otherwise it can go in trunk.
203 If in doubt discuss it on the mailing list before you commit.
205perl v5.38.0 2023-10-03 HACKING(3)