Debian Codegraph @

upstream/debian-unstable/man3/autodie::Util.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "autodie::Util 3perl"
58 .TH autodie::Util 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 autodie::Util \- Internal Utility subroutines for autodie and Fatal
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& # INTERNAL API for autodie and Fatal only!
69 \&
70 \& use autodie::Util qw(on_end_of_compile_scope);
71 \& on_end_of_compile_scope(sub { print "Hallo world\en"; });
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 Internal Utilities for autodie and Fatal! This module is not a part of
76 autodie's public API.
77 .PP
78 This module contains utility subroutines for abstracting away the
79 underlying magic of autodie and (ab)uses of \f(CW\*(C`%^H\*(C'\fR to call subs at the
80 end of a (compile-time) scopes.
81 .PP
82 Note that due to how \f(CW\*(C`%^H\*(C'\fR works, some of these utilities are only
83 useful during the compilation phase of a perl module and relies on the
84 internals of how perl handles references in \f(CW\*(C`%^H\*(C'\fR.
85 .SS Methods
86 .IX Subsection "Methods"
87 \fIon_end_of_compile_scope\fR
88 .IX Subsection "on_end_of_compile_scope"
89 .PP
90 .Vb 1
91 \& on_end_of_compile_scope(sub { print "Hallo world\en"; });
92 .Ve
93 .PP
94 Will invoke a sub at the end of a (compile-time) scope. The sub is
95 called once with no arguments. Can be called multiple times (even in
96 the same "compile-time" scope) to install multiple subs. Subs are
97 called in a "first\-in\-last\-out"\-order (FILO or "stack"\-order).
98 .PP
99 \fIfill_protos\fR
100 .IX Subsection "fill_protos"
101 .PP
102 .Vb 1
103 \& fill_protos(\*(Aq*$$;$@\*(Aq)
104 .Ve
105 .PP
106 Given a Perl subroutine prototype, return a list of invocation
107 specifications. Each specification is a listref, where the first
108 member is the (minimum) number of arguments for this invocation
109 specification. The remaining arguments are a string representation of
110 how to pass the arguments correctly to a sub with the given prototype,
111 when called with the given number of arguments.
112 .PP
113 The specifications are returned in increasing order of arguments
114 starting at 0 (e.g. ';$') or 1 (e.g. '$@'). Note that if the
115 prototype is "slurpy" (e.g. ends with a "@"), the number of arguments
116 for the last specification is a "minimum" number rather than an exact
117 number. This can be detected by the last member of the last
118 specification matching m/[@#]_/.
119 .PP
120 \fImake_core_trampoline\fR
121 .IX Subsection "make_core_trampoline"
122 .PP
123 .Vb 1
124 \& make_core_trampoline(\*(AqCORE::open\*(Aq, \*(Aqmain\*(Aq, prototype(\*(AqCORE::open\*(Aq))
125 .Ve
126 .PP
127 Creates a trampoline for calling a core sub. Essentially, a tiny sub
128 that figures out how we should be calling our core sub, puts in the
129 arguments in the right way, and bounces our control over to it.
130 .PP
131 If we could reliably use `goto &` on core builtins, we wouldn't need
132 this subroutine.
133 .PP
134 \fIinstall_subs\fR
135 .IX Subsection "install_subs"
136 .PP
137 .Vb 1
138 \& install_subs(\*(AqMy::Module\*(Aq, { \*(Aqread\*(Aq => sub { die("Hallo\en"), ... }})
139 .Ve
140 .PP
141 Given a package name and a hashref mapping names to a subroutine
142 reference (or \f(CW\*(C`undef\*(C'\fR), this subroutine will install said subroutines
143 on their given name in that module. If a name mapes to \f(CW\*(C`undef\*(C'\fR, any
144 subroutine with that name in the target module will be removed
145 (possibly "unshadowing" a CORE sub of same name).
146 .SH AUTHOR
147 .IX Header "AUTHOR"
148 Copyright 2013\-2014, Niels Thykier <[email protected]>
149 .SH LICENSE
150 .IX Header "LICENSE"
151 This module is free software. You may distribute it under the
152 same terms as Perl itself.