Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 411 lines (262 sloc) 12.171 kb
8ee1ad7 @allisonrandal [cage] Updating copyright in whole repository to Parrot Foundation.
allisonrandal authored
1 # Copyright (C) 2001-2008, Parrot Foundation.
ef9e57c tidy up pdds
Michael Scott authored
2 # $Id$
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
3
740e774 @allisonrandal [cage] Cleaning up the PDD titles for better display and
allisonrandal authored
4 =head1 PDD 3: Calling Conventions
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
5
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
6 =head2 Abstract
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
7
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
8 Parrot's inter-routine calling conventions.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
9
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
10 =head2 Version
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
11
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
12 $Revision$
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
13
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
14 =head2 Synopsis
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3/Ti...
jkeenan authored
15
16 Not applicable.
17
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
18 =head2 Description
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
19
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
20 This document describes how to pass arguments from registers to subroutines,
21 and how subroutines can extract their parameters into registers for use.
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored
22
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
23 Since Parrot's calling conventions are continuation-based, there is arguably
24 very little difference between a call and a return. Because of this, the
25 conversion rules are the same regardless of whether code is invoking a
26 subroutine or a return continuation.
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
27
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
28 =head3 Common Features of Argument/Return Opcodes
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
29
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
30 There are four opcodes involved in parameter and return value propagation:
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
31
32 =over 4
33
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
34 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
35
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
36 C<set_args>, for passing arguments;
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
37
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
38 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
39
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
40 C<set_returns>, for returning values;
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
41
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
42 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
43
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
44 C<get_params>, for accepting parameters; and
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
45
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
46 =item *
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored
47
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
48 C<get_results>, for accepting return values.
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored
49
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
50 =back
8f37cf5 tweak calling conventions
Dan Sugalski authored
51
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
52 FAQ: Given Parrot's internal use of continuation-passing style ["CPS"], it
53 would be possible to use one pair of opcodes for both call and return, since
54 under CPS returns I<are> calls. And perhaps someday we will have only two
2be4a28 * docs/pdds/draft/pdd06_pasm.pod:
Bob Rogers authored
55 opcodes. But for now, certain efficiency hacks are easier with four opcodes.
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
56
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
57 The common syntax of these opcodes is:
8f37cf5 tweak calling conventions
Dan Sugalski authored
58
3b2acaf @paultcochrane [pdd] Removed deprecated opcode syntax as recommended by Allison Randal....
paultcochrane authored
59 <set_opcode> "flags0, flags1, ..., flagsN", VAL0, VAL1, ... VALN
60 <get_opcode> "flags0, flags1, ..., flagsN", REG0, REG1, ... REGN
61 <get_opcode> "..., 0x200, flags0, ...", ..., "name", REG0, ...
8155c8a MMD 16 - builtin infix multis
Leopold Toetsch authored
62
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
63 The flags string is a literal quoted string denoting a list of zero or more
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
64 comma-separated integers. Integers may be specified either in decimal, or if
65 prefixed with "0b"/"0x", in binary/hexadecimal. There must be exactly one
66 integer for each value or register given.
67
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
68 For documentation purposes we'll number the bits 0 (low) through 30 (high).
69 Bit 31 (and higher, where available) will not be used.
70
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
71 Some values and registers do not correspond directly to values passed or
72 received. (See the descriptions of the OPT_FLAG and NAMED bits, below.)
73
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
74 =head4 Flag Words; Common Flag Word Bits
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
75
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
76 Each integer in the flag string controls the processing of the corresponding
77 value or register.
7dccda2 Changes to the calling conventions
Dan Sugalski authored
78
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
79 These bits of each flag word have common meanings for all argument/
80 return-value opcodes:
7dccda2 Changes to the calling conventions
Dan Sugalski authored
81
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
82 0-3 TYPE
83 0b0000 = I
84 0b0001 = S
85 0b0010 = P
86 0b0011 = N
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
87
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
88 Don't set these bits yourself; the assembler will do it.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
89
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
90 =head3 Passing Arguments, Returning Values
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
91
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
92 Just before calling a subroutine with C<invokecc> or calling a method with
85e077d @paultcochrane [pdds] Minor formatting and textual corrections.
paultcochrane authored
93 C<call_methodcc>, use the C<set_args> opcode to tell Parrot where the
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
94 subroutine's or method's arguments will come from and how they should be
95 expanded by the target.
7ed080d Fixed the PMC parameter passing docs
Dan Sugalski authored
96
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3/Ti...
jkeenan authored
97 Similarly, just before returning from such a subroutine or method, use
98 the C<set_returns> opcode to tell Parrot where the return values will
99 come from and how to expand them for the caller's use.
7ed080d Fixed the PMC parameter passing docs
Dan Sugalski authored
100
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
101 =head4 Flag Word Bits For 'Setting'
37a10ea Some precursor changes
Dan Sugalski authored
102
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
103 These bits of each flag word have these meanings specific to C<set_args> and
104 C<set_returns>:
37a10ea Some precursor changes
Dan Sugalski authored
105
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
106 =over 4
107
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored
108 =item 4 C<CONSTANT>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
109
110 The value is a literal constant, not a register. (Don't set this bit
111 yourself; the assembler will do it.)
112
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
113 =item 5 C<FLAT> (P only)
114
115 If this bit is set on a PMC value, then the PMC must be an aggregate. The
116 contents of the aggregate, rather than the aggregate itself, will be passed.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
117
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
118 If the C<NAMED> bit is also set, the aggregate will be used as a hash; its
119 contents, as key/value pairs, will be passed as named parameters. The PMC
d5b380d @paultcochrane [pdd] Converted TODO items to RT tickets.
paultcochrane authored
120 must implement the full hash interface. {{ RT#45367: Limit the required
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
121 interface. }}
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
122
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
123 If the C<NAMED> bit is not set, the aggregate will be used as an array; its
124 contents will be passed as positional parameters.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
125
126 The meaning of this bit is undefined when applied to integer, number, and
127 string values.
128
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
129 =item 6 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
130
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
131 =item 7 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
132
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
133 =item 8 (unused)
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored
134
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
135 =item 9 C<NAMED> (C<FLAT> or string constant only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
136
137 When the FLAT bit is also set, behavior is as described above in the "FLAT"
138 section. Otherwise, this bit may only be set on a unique string constant
139 specifying the name of the next argument (or returned value).
140
141 =back
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
142
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
143 =head3 Accepting Parameters, Accepting Return Values
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
144
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3/Ti...
jkeenan authored
145 As the I<first opcode> in a subroutine that will be called with
146 C<invokecc> or a method that will be called with C<call_methodcc>, use
147 the C<get_params> opcode to tell Parrot where the subroutine's or
148 method's arguments should be stored and how they should be expanded.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
149
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3/Ti...
jkeenan authored
150 Similarly, just I<before> (yes, I<before>) calling such a subroutine or
151 method, use the C<get_results> opcode to tell Parrot where the return
152 values should be stored and how to expand them for your use.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
153
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
154 NOTE: It should be obvious, but in case it's not: You must name only registers
155 as targets of these opcodes, not constants. (You can't store anything into a
156 constant. That would make it a variable.)
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
157
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
158 =head4 Flag Word Bits For 'Getting'
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
159
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
160 These bits of each flag word have these meanings specific to C<get_params> and
161 C<get_results>:
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
162
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
163 =over 4
164
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
165 =item 4 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
166
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
167 =item 5 C<SLURPY> (P only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
168
169 If this bit is set on a P register, then it will be populated with an
170 aggregate that will contain all of the remaining values that have not already
171 been stored in other registers.
172
173 All such values will be converted to PMCs according to the detailed rules
174 below, and those PMCs will be stored into the new aggregate.
175
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
176 If the C<NAMED> bit is also set, the aggregate will be the HLL-specific hash
177 type and the contents will be all unassigned _named_ parameters.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
178
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
179 If the C<NAMED> bit is not set, the aggregate will be the HLL-specific array
180 type and the contents will be all unassigned positional parameters.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
181
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
182 =item 6 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
183
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored
184 =item 7 C<OPTIONAL>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
185
186 If this bit is set on a register for which no value has been passed, no
187 exception will be raised; rather, the register will be set to a default value:
188 a Null PMC for P, an empty string for S, or zero for N or I.
189
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
190 =item 8 C<OPT_FLAG> (I only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
191
192 An I register with this bit set is set to one if the immediately preceding
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
193 B<OPTIONAL> register received a value; otherwise, it is set to zero. If the
194 preceding register was not marked B<OPTIONAL>, the behavior is undefined; but
195 we promise you won't like it.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
196
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
197 =item 8 C<READONLY> (P only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
198
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
199 I<XXX - PROPOSED ONLY - XXX>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
200
201 If this bit is set on a P register that receives a value, Parrot will ensure
202 that the final value in the P register is read-only (i.e. will not permit
203 modification). If the received value was a mutable PMC, then Parrot will
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
204 create and set the register to a {not yet invented} read-only PMC wrapper
205 around the original PMC.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
206
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
207 Future Notes: Parrot's algorithm for deciding what is writable may be
208 simplistic. In initial implementations, it may assume that any PMC not of a
209 known read-only-wrapper type is mutable. Later it may allow the HLL to
210 provide the test. But we must beware overdesigning this; any HLL with a truly
211 complex notion of read-only probably needs to do this kind of wrapping itself.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
212
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
213 =item 8 (unused for S and N)
214
215 =item 9 C<NAMED> (C<SLURPY> or string constant only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored
216
217 When the SLURPY bit is also set, behavior is as described above in the
218 "SLURPY" section. Otherwise, this bit may only be set on a unique string
219 constant specifying the name of the next argument (or returned value).
220
221 =back
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
222
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
223 =head4 Overflow and underflow
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
224
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored
225 If too many or too few values are provided for the given target registers,
226 Parrot by default will throw an exception for C<get_params>, but not for
227 C<get_results>. This error behavior can be controlled via the C<errorson> and
228 C<errorsoff> opcodes using C<PARROT_ERRORS_PARAM_COUNT_FLAG> for C<get_params>
229 and C<PARROT_ERRORS_RESULT_COUNT_FLAG> for C<get_results>. (It is not
230 possible to control underflow behavior separately from overflow.)
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
231
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored
232 Note that if the final target is a P register with FLAT set, then overflow can
233 never occur. Similarly, if all target registers are marked B<OPTIONAL>, then
234 underflow is impossible.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
235
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored
236 Note also that when these errors are off, any excess destination registers in
237 the case of underflow are left untouched, rather than being reset to zero or
238 null. Excess registers explicitly marked B<OPTIONAL> are always reset,
239 regardless of the error flag settings.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
240
5d75ebc @rurban [pdd] make all pdds pass t/codingstd/perlcritic.t and pdd_format.t: trai...
rurban authored
241 RT#45357 - which exception? We really could use an exception subsystem.
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored
242 Oh, wait, that's my job. Never mind. --Chip
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored
243
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
244 =head4 Ordering of named values (outgoing)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
245
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
246 Named values (arguments, or values to return) must be listed textually after
247 all the positional values. C<FLAT> and non-C<FLAT> values may be mixed in any
248 order.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
249
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
250 =head4 Ordering of named targets (incoming)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
251
252 Named targets (parameters, or returned values) must appear I<after> all the
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
253 positional targets. A C<SLURPY> positional target, if present, must be the
254 last positional target; a C<SLURPY> named target, if present, must be the last
255 named target.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
256
257 So the acceptable ordering of targets is:
258
259 =over 4
260
261 =item *
262
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
263 positional non-SLURPY (any number)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
264
265 =item *
266
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
267 positional SLURPY array (optional)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
268
269 =item *
270
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
271 NAMED non-SLURPY (any number)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
272
273 =item *
274
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
275 NAMED SLURPY hash (optional)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
276
277 =back
278
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
279 =head4 Mixing named and positional values
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
280
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
281 Positional targets can only be filled with positional values.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
282
85e077d @paultcochrane [pdds] Minor formatting and textual corrections.
paultcochrane authored
283 Named targets can be filled with either positional or named values.
284 However, if a named target was already filled by a positional value, and
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
285 then a named value is also given, this is an overflow error.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
286
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
287 =head4 Type Conversions
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
288
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
289 Unlike the C<set_*> opcodes, the C<get_*> opcodes must perform conversion from
290 one register type to another. Here are the conversion rules:
898b4d2 Final release version of pdd03
Dan Sugalski authored
291
292 =over 4
293
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
294 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored
295
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
296 When the target is an I, N, or S register, storage will behave like an
297 C<assign> (standard conversion).
898b4d2 Final release version of pdd03
Dan Sugalski authored
298
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
299 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored
300
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
301 When the target and source are both P registers, storage will behave like a
302 C<set> (pass by reference).
898b4d2 Final release version of pdd03
Dan Sugalski authored
303
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
304 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored
305
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
306 When the target is a P register and the source is an integer, the P will be
757c937 @chromatic [OO] Changed more PMC creation from constant syntax to string style.
chromatic authored
307 set to a new Integer[1] which has been C<assign>ed the given integer.
898b4d2 Final release version of pdd03
Dan Sugalski authored
308
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
309 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored
310
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
311 When the target is a P register and the source is a number, the P will be set
757c937 @chromatic [OO] Changed more PMC creation from constant syntax to string style.
chromatic authored
312 to a new Float[1] which has been C<assign>ed the given number.
898b4d2 Final release version of pdd03
Dan Sugalski authored
313
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
314 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored
315
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored
316 When the target is a P register and the source is a string, the P will be set
757c937 @chromatic [OO] Changed more PMC creation from constant syntax to string style.
chromatic authored
317 to a new String[1] which has been C<assign>ed the given string.
898b4d2 Final release version of pdd03
Dan Sugalski authored
318
319 =back
320
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
321 [1] or some other type specified by the current HLL type map, which may
322 substitute an alternative type for each default low-level Parrot type (array,
323 hash, string, number, etc.).
5b3d0e6 update pdd03 to better reflect current state
Leopold Toetsch authored
324
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
325 =head2 Implementation
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3/Ti...
jkeenan authored
326
327 Not applicable.
328
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
329 =head2 Bugs
898b4d2 Final release version of pdd03
Dan Sugalski authored
330
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
331 Required features are missing:
898b4d2 Final release version of pdd03
Dan Sugalski authored
332
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
333 =over 4
6ef5471 Added null ops to core.ops
Dan Sugalski authored
334
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
335 =item *
6ef5471 Added null ops to core.ops
Dan Sugalski authored
336
6d3f9cf @chipdude It's all new. All of it.
chipdude authored
337 Specific exceptions to throw for specific errors.
338
339 =back
340
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
341 =head2 PIR Syntax Examples
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
342
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
343 =head3 Function Calls
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
344
6124f6e @cotto [pmcc] bring branch up-to-date with trunk
cotto authored
345 =begin PIR_FRAGMENT_INVALID
346
347 .local pmc foo, i, ar, y, p, value, kw, a, b, c, z
348 # ...
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
349 foo(1, i) # 2 positional arguments
350 foo(x, ar :flat, y) # flattening array
d5305a0 @particle [PDD03[: clarify examples for :named syntax
particle authored
351 foo(p, 'key' => value) # named argument
352 foo(p, value :named('key')) # the same
33fc8c5 pdd03 typo
Leopold Toetsch authored
353 foo(kw :named :flat) # a flattening hash
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
354
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
355 # all together now: three positional (one flat) with two named (one flat)
356 foo(a, b, c :flat, 'x' => 3, 'y' => 4, z :flat :named('z'))
357
6124f6e @cotto [pmcc] bring branch up-to-date with trunk
cotto authored
358 =end PIR_FRAGMENT_INVALID
359
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
360 =head3 Parameters
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
361
6124f6e @cotto [pmcc] bring branch up-to-date with trunk
cotto authored
362 =begin PIR
363
364 .sub foo
365 .param int i # positional parameter
366 .param pmc argv :slurpy # slurpy array
367 .param pmc value :named('key') # named parameter
368 .param int x :optional # optional parameter
369 .param int has_x :opt_flag # flag 0/1 x was passed
370 .param pmc kw :slurpy :named # slurpy hash
371 # ...
372 .end
373
374 =end PIR
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
375
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
376 =head3 Return Values
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
377
6124f6e @cotto [pmcc] bring branch up-to-date with trunk
cotto authored
378 =begin PIR_INVALID
379
380 .sub foo
381 .local pmc i, ar, value
382 .return (i, ar: flat, value :named('key') )
383 .end
384
385 =end PIR_INVALID
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
386
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
387 =head3 Call Results
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
388
6124f6e @cotto [pmcc] bring branch up-to-date with trunk
cotto authored
389 =begin PIR_FRAGMENT
390
391 .local pmc x, foo, i, j, ar, value
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored
392 x = foo() # single result
d5305a0 @particle [PDD03[: clarify examples for :named syntax
particle authored
393 (i, j :optional, ar :slurpy, value :named('key') ) = foo()
6ef5471 Added null ops to core.ops
Dan Sugalski authored
394
6124f6e @cotto [pmcc] bring branch up-to-date with trunk
cotto authored
395 =end PIR_FRAGMENT
396
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
397 =head2 Attachments
ef9e57c tidy up pdds
Michael Scott authored
398
399 None.
400
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored
401 =head2 References
ef9e57c tidy up pdds
Michael Scott authored
402
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored
403 L<pdd23_exceptions.pod>
ef9e57c tidy up pdds
Michael Scott authored
404
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
405 =cut
f140bda @chipdude Formatting: standardize word wrap at column 78.
chipdude authored
406
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored
407 __END__
408 Local Variables:
409 fill-column:78
410 End:
Something went wrong with that request. Please try again.