Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::Typemaps::OutputMap.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 "ExtUtils::Typemaps::OutputMap 3perl"
58 .TH ExtUtils::Typemaps::OutputMap 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 ExtUtils::Typemaps::OutputMap \- Entry in the OUTPUT section of a typemap
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 5
68 \& use ExtUtils::Typemaps;
69 \& ...
70 \& my $output = $typemap\->get_output_map(\*(AqT_NV\*(Aq);
71 \& my $code = $output\->code();
72 \& $output\->code("...");
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 Refer to ExtUtils::Typemaps for details.
77 .SH METHODS
78 .IX Header "METHODS"
79 .SS new
80 .IX Subsection "new"
81 Requires \f(CW\*(C`xstype\*(C'\fR and \f(CW\*(C`code\*(C'\fR parameters.
82 .SS code
83 .IX Subsection "code"
84 Returns or sets the OUTPUT mapping code for this entry.
85 .SS xstype
86 .IX Subsection "xstype"
87 Returns the name of the XS type of the OUTPUT map.
88 .SS cleaned_code
89 .IX Subsection "cleaned_code"
90 Returns a cleaned-up copy of the code to which certain transformations
91 have been applied to make it more ANSI compliant.
92 .SS targetable
93 .IX Subsection "targetable"
94 This is an obscure but effective optimization that used to
95 live in \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR directly. Not implementing it
96 should never result in incorrect use of typemaps, just less
97 efficient code.
98 .PP
99 In a nutshell, this will check whether the output code
100 involves calling \f(CW\*(C`sv_setiv\*(C'\fR, \f(CW\*(C`sv_setuv\*(C'\fR, \f(CW\*(C`sv_setnv\*(C'\fR, \f(CW\*(C`sv_setpv\*(C'\fR or
101 \&\f(CW\*(C`sv_setpvn\*(C'\fR to set the special \f(CW$arg\fR placeholder to a new value
102 \&\fBAT THE END OF THE OUTPUT CODE\fR. If that is the case, the code is
103 eligible for using the \f(CW\*(C`TARG\*(C'\fR\-related macros to optimize this.
104 Thus the name of the method: \f(CW\*(C`targetable\*(C'\fR.
105 .PP
106 If this optimization is applicable, \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR will
107 emit a \f(CW\*(C`dXSTARG;\*(C'\fR definition at the start of the generated XSUB code,
108 and type (see below) dependent code to set \f(CW\*(C`TARG\*(C'\fR and push it on
109 the stack at the end of the generated XSUB code.
110 .PP
111 If the optimization can not be applied, this returns undef.
112 If it can be applied, this method returns a hash reference containing
113 the following information:
114 .PP
115 .Vb 5
116 \& type: Any of the characters i, u, n, p
117 \& with_size: Bool indicating whether this is the sv_setpvn variant
118 \& what: The code that actually evaluates to the output scalar
119 \& what_size: If "with_size", this has the string length (as code,
120 \& not constant, including leading comma)
121 .Ve
122 .SH "SEE ALSO"
123 .IX Header "SEE ALSO"
124 ExtUtils::Typemaps
125 .SH AUTHOR
126 .IX Header "AUTHOR"
127 Steffen Mueller \f(CW\*(C`<[email protected]\*(C'\fR>
128 .SH "COPYRIGHT & LICENSE"
129 .IX Header "COPYRIGHT & LICENSE"
130 Copyright 2009, 2010, 2011, 2012 Steffen Mueller
131 .PP
132 This program is free software; you can redistribute it and/or
133 modify it under the same terms as Perl itself.