Debian Codegraph @

upstream/opensuse-tumbleweed/man3/autodie::Util.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "autodie::Util 3pm"
61 .TH autodie::Util 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 autodie::Util \- Internal Utility subroutines for autodie and Fatal
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& # INTERNAL API for autodie and Fatal only!
72 \&
73 \& use autodie::Util qw(on_end_of_compile_scope);
74 \& on_end_of_compile_scope(sub { print "Hallo world\en"; });
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 Internal Utilities for autodie and Fatal! This module is not a part of
79 autodie\*(Aqs public API.
80 .PP
81 This module contains utility subroutines for abstracting away the
82 underlying magic of autodie and (ab)uses of \f(CW\*(C`%^H\*(C'\fR to call subs at the
83 end of a (compile\-time) scopes.
84 .PP
85 Note that due to how \f(CW\*(C`%^H\*(C'\fR works, some of these utilities are only
86 useful during the compilation phase of a perl module and relies on the
87 internals of how perl handles references in \f(CW\*(C`%^H\*(C'\fR.
88 .SS Methods
89 .IX Subsection "Methods"
90 \fIon_end_of_compile_scope\fR
91 .IX Subsection "on_end_of_compile_scope"
92 .PP
93 .Vb 1
94 \& on_end_of_compile_scope(sub { print "Hallo world\en"; });
95 .Ve
96 .PP
97 Will invoke a sub at the end of a (compile\-time) scope. The sub is
98 called once with no arguments. Can be called multiple times (even in
99 the same "compile\-time" scope) to install multiple subs. Subs are
100 called in a "first\-in\-last\-out"\-order (FILO or "stack"\-order).
101 .PP
102 \fIfill_protos\fR
103 .IX Subsection "fill_protos"
104 .PP
105 .Vb 1
106 \& fill_protos(\*(Aq*$$;$@\*(Aq)
107 .Ve
108 .PP
109 Given a Perl subroutine prototype, return a list of invocation
110 specifications. Each specification is a listref, where the first
111 member is the (minimum) number of arguments for this invocation
112 specification. The remaining arguments are a string representation of
113 how to pass the arguments correctly to a sub with the given prototype,
114 when called with the given number of arguments.
115 .PP
116 The specifications are returned in increasing order of arguments
117 starting at 0 (e.g. \*(Aq;$\*(Aq) or 1 (e.g. \*(Aq$@\*(Aq). Note that if the
118 prototype is "slurpy" (e.g. ends with a "@"), the number of arguments
119 for the last specification is a "minimum" number rather than an exact
120 number. This can be detected by the last member of the last
121 specification matching m/[@#]_/.
122 .PP
123 \fImake_core_trampoline\fR
124 .IX Subsection "make_core_trampoline"
125 .PP
126 .Vb 1
127 \& make_core_trampoline(\*(AqCORE::open\*(Aq, \*(Aqmain\*(Aq, prototype(\*(AqCORE::open\*(Aq))
128 .Ve
129 .PP
130 Creates a trampoline for calling a core sub. Essentially, a tiny sub
131 that figures out how we should be calling our core sub, puts in the
132 arguments in the right way, and bounces our control over to it.
133 .PP
134 If we could reliably use \`goto &\` on core builtins, we wouldn\*(Aqt need
135 this subroutine.
136 .PP
137 \fIinstall_subs\fR
138 .IX Subsection "install_subs"
139 .PP
140 .Vb 1
141 \& install_subs(\*(AqMy::Module\*(Aq, { \*(Aqread\*(Aq => sub { die("Hallo\en"), ... }})
142 .Ve
143 .PP
144 Given a package name and a hashref mapping names to a subroutine
145 reference (or \f(CW\*(C`undef\*(C'\fR), this subroutine will install said subroutines
146 on their given name in that module. If a name mapes to \f(CW\*(C`undef\*(C'\fR, any
147 subroutine with that name in the target module will be removed
148 (possibly "unshadowing" a CORE sub of same name).
149 .SH AUTHOR
150 .IX Header "AUTHOR"
151 Copyright 2013\-2014, Niels Thykier <[email protected]>
152 .SH LICENSE
153 .IX Header "LICENSE"
154 This module is free software. You may distribute it under the
155 same terms as Perl itself.