Skip to content
Newer
Older
100644 404 lines (258 sloc) 11.7 KB
fba2bc1 @coke PDD cleanup (TT #1536); Remove maintainer, changes sections.
coke authored Apr 14, 2010
1 # Copyright (C) 2001-2010, Parrot Foundation.
ef9e57c tidy up pdds
Michael Scott authored Feb 28, 2004
2 # $Id$
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
3
740e774 @allisonrandal [cage] Cleaning up the PDD titles for better display and
allisonrandal authored Mar 9, 2009
4 =head1 PDD 3: Calling Conventions
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
5
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
6 =head2 Abstract
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
7
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
8 Parrot's inter-routine calling conventions.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
9
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
10 =head2 Version
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
11
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
12 $Revision$
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
13
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
14 =head2 Synopsis
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
15
16 Not applicable.
17
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
18 =head2 Description
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
19
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 May 2, 2003
22
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 Jun 13, 2005
27
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
28 =head3 Common Features of Argument/Return Opcodes
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
29
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
30 There are four opcodes involved in parameter and return value propagation:
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
31
32 =over 4
33
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
34 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
35
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
36 C<set_args>, for passing arguments;
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
37
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
38 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
39
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
40 C<set_returns>, for returning values;
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
41
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
42 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
43
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
44 C<get_params>, for accepting parameters; and
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
45
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
46 =item *
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored May 2, 2003
47
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
48 C<get_results>, for accepting return values.
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored May 2, 2003
49
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
50 =back
8f37cf5 tweak calling conventions
Dan Sugalski authored Feb 6, 2003
51
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
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 Apr 7, 2008
55 opcodes. But for now, certain efficiency hacks are easier with four opcodes.
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
56
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
57 The common syntax of these opcodes is:
8f37cf5 tweak calling conventions
Dan Sugalski authored Feb 6, 2003
58
3b2acaf @paultcochrane [pdd] Removed deprecated opcode syntax as recommended by Allison Rand…
paultcochrane authored Sep 18, 2007
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 Apr 4, 2005
62
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 Nov 10, 2006
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 Nov 30, 2005
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 Feb 27, 2006
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 Feb 8, 2009
74 =head4 Flag Words; Common Flag Word Bits
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
75
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 Nov 17, 2003
78
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
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 Nov 17, 2003
81
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
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 Apr 27, 2002
87
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
88 Don't set these bits yourself; the assembler will do it.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
89
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
90 =head3 Passing Arguments, Returning Values
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
91
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
92 Just before calling a subroutine with C<invokecc> or calling a method with
85e077d @paultcochrane [pdds] Minor formatting and textual corrections.
paultcochrane authored Sep 11, 2007
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 Oct 5, 2005
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 Aug 8, 2002
96
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
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 Aug 8, 2002
100
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
101 =head4 Flag Word Bits For 'Setting'
37a10ea Some precursor changes
Dan Sugalski authored Sep 18, 2002
102
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 Sep 18, 2002
105
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
106 =over 4
107
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored Nov 3, 2006
108 =item 4 C<CONSTANT>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
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 Nov 10, 2006
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 Nov 2, 2006
117
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
118 If the C<NAMED> bit is also set, the aggregate will be used as a hash; its
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
119 contents, as key/value pairs, will be passed as named arguments. The PMC
bab0c32 @jkeenan Change RT reference to TT reference.
jkeenan authored Nov 21, 2009
120 must implement the full hash interface. {{ TT #1288: Limit the required
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
121 interface. }}
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
122
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
123 If the C<NAMED> bit is not set, the aggregate will be used as an array; its
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
124 contents will be passed as positional arguments.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
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 Nov 10, 2006
129 =item 6 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
130
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
131 =item 7 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
132
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
133 =item 8 (unused)
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored Nov 3, 2006
134
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
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 Nov 2, 2006
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 Apr 27, 2002
142
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
143 =head3 Accepting Parameters, Accepting Return Values
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
144
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
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 Apr 27, 2002
149
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
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 Apr 27, 2002
153
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 Apr 27, 2002
157
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
158 =head4 Flag Word Bits For 'Getting'
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
159
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
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 Apr 27, 2002
162
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
163 =over 4
164
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
165 =item 4 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
166
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
167 =item 5 C<SLURPY> (P only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
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 Nov 10, 2006
176 If the C<NAMED> bit is also set, the aggregate will be the HLL-specific hash
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
177 type and the contents will be all unassigned _named_ arguments.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
178
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
179 If the C<NAMED> bit is not set, the aggregate will be the HLL-specific array
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
180 type and the contents will be all unassigned positional arguments.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
181
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
182 =item 6 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
183
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored Nov 3, 2006
184 =item 7 C<OPTIONAL>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
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 Nov 10, 2006
190 =item 8 C<OPT_FLAG> (I only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
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 Nov 10, 2006
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 Nov 2, 2006
196
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
197 =item 8 C<READONLY> (P only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
198
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
199 I<XXX - PROPOSED ONLY - XXX>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
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 Nov 10, 2006
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 Nov 2, 2006
206
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
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 Nov 2, 2006
212
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
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 Nov 2, 2006
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
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
219 constant specifying the name of the next parameter (or returned value).
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
220
221 =back
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
222
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
223 =head4 Overflow and underflow
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
224
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored Jan 6, 2008
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 Apr 27, 2002
231
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored Jan 6, 2008
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 Apr 27, 2002
235
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored Jan 6, 2008
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 Apr 27, 2002
240
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
241 =head4 Ordering of named values (outgoing)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
242
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
243 Named values (arguments, or values to return) must be listed textually after
244 all the positional values. C<FLAT> and non-C<FLAT> values may be mixed in any
245 order.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
246
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
247 =head4 Ordering of named targets (incoming)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
248
249 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 Nov 10, 2006
250 positional targets. A C<SLURPY> positional target, if present, must be the
251 last positional target; a C<SLURPY> named target, if present, must be the last
252 named target.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
253
254 So the acceptable ordering of targets is:
255
256 =over 4
257
258 =item *
259
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
260 positional non-SLURPY (any number)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
261
262 =item *
263
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
264 positional SLURPY array (optional)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
265
266 =item *
267
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
268 NAMED non-SLURPY (any number)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
269
270 =item *
271
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
272 NAMED SLURPY hash (optional)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
273
274 =back
275
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
276 =head4 Mixing named and positional values
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
277
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
278 Positional targets can only be filled with positional values.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
279
85e077d @paultcochrane [pdds] Minor formatting and textual corrections.
paultcochrane authored Sep 11, 2007
280 Named targets can be filled with either positional or named values.
281 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 Nov 10, 2006
282 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 Feb 27, 2006
283
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
284 =head4 Type Conversions
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
285
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
286 Unlike the C<set_*> opcodes, the C<get_*> opcodes must perform conversion from
287 one register type to another. Here are the conversion rules:
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
288
289 =over 4
290
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
291 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
292
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
293 When the target is an I, N, or S register, storage will behave like an
294 C<assign> (standard conversion).
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
295
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
296 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
297
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
298 When the target and source are both P registers, storage will behave like a
299 C<set> (pass by reference).
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
300
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
301 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
302
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
303 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 Aug 30, 2007
304 set to a new Integer[1] which has been C<assign>ed the given integer.
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
305
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
306 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
307
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
308 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 Aug 30, 2007
309 to a new Float[1] which has been C<assign>ed the given number.
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
310
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
311 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
312
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
313 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 Aug 30, 2007
314 to a new String[1] which has been C<assign>ed the given string.
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
315
316 =back
317
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
318 [1] or some other type specified by the current HLL type map, which may
319 substitute an alternative type for each default low-level Parrot type (array,
320 hash, string, number, etc.).
5b3d0e6 update pdd03 to better reflect current state
Leopold Toetsch authored Dec 27, 2005
321
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
322 =head2 Implementation
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
323
324 Not applicable.
325
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
326 =head2 Bugs
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
327
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
328 Required features are missing:
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
329
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
330 =over 4
6ef5471 Added null ops to core.ops
Dan Sugalski authored Jun 21, 2003
331
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
332 =item *
6ef5471 Added null ops to core.ops
Dan Sugalski authored Jun 21, 2003
333
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
334 Specific exceptions to throw for specific errors.
335
336 =back
337
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
338 =head2 PIR Syntax Examples
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
339
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
340 =head3 Function Calls
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
341
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
342 =begin PIR_FRAGMENT_INVALID
343
344 .local pmc foo, i, ar, y, p, value, kw, a, b, c, z
345 # ...
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
346 foo(1, i) # 2 positional arguments
347 foo(x, ar :flat, y) # flattening array
d5305a0 @particle [PDD03[: clarify examples for :named syntax
particle authored Oct 13, 2006
348 foo(p, 'key' => value) # named argument
349 foo(p, value :named('key')) # the same
33fc8c5 pdd03 typo
Leopold Toetsch authored May 11, 2006
350 foo(kw :named :flat) # a flattening hash
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
351
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
352 # all together now: three positional (one flat) with two named (one flat)
353 foo(a, b, c :flat, 'x' => 3, 'y' => 4, z :flat :named('z'))
354
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
355 =end PIR_FRAGMENT_INVALID
356
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
357 =head3 Parameters
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
358
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
359 =begin PIR
360
361 .sub foo
362 .param int i # positional parameter
363 .param pmc argv :slurpy # slurpy array
364 .param pmc value :named('key') # named parameter
365 .param int x :optional # optional parameter
366 .param int has_x :opt_flag # flag 0/1 x was passed
367 .param pmc kw :slurpy :named # slurpy hash
368 # ...
369 .end
370
371 =end PIR
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
372
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
373 =head3 Return Values
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
374
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
375 =begin PIR_INVALID
376
377 .sub foo
378 .local pmc i, ar, value
379 .return (i, ar: flat, value :named('key') )
380 .end
381
382 =end PIR_INVALID
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
383
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
384 =head3 Call Results
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
385
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
386 =begin PIR_FRAGMENT
387
388 .local pmc x, foo, i, j, ar, value
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
389 x = foo() # single result
d5305a0 @particle [PDD03[: clarify examples for :named syntax
particle authored Oct 13, 2006
390 (i, j :optional, ar :slurpy, value :named('key') ) = foo()
6ef5471 Added null ops to core.ops
Dan Sugalski authored Jun 21, 2003
391
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
392 =end PIR_FRAGMENT
393
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
394 =head2 References
ef9e57c tidy up pdds
Michael Scott authored Feb 28, 2004
395
fba2bc1 @coke PDD cleanup (TT #1536); Remove maintainer, changes sections.
coke authored Apr 14, 2010
396 F<pdd23_exceptions.pod>
ef9e57c tidy up pdds
Michael Scott authored Feb 28, 2004
397
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
398 =cut
f140bda @chipdude Formatting: standardize word wrap at column 78.
chipdude authored Nov 30, 2005
399
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
400 __END__
401 Local Variables:
402 fill-column:78
403 End:
Something went wrong with that request. Please try again.