Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 363 lines (253 sloc) 9.497 kb
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
1 /*
48311a5 @petdance teeny consting
petdance authored
2 Copyright (C) 2007-2009, Parrot Foundation.
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
3 $Id$
4
5 =head1 NAME
6
7 src/pmc/exporter.pmc - Export globals from one namespace to another
8
abc4db2 @particle [pmc]: exporter api changes
particle authored
9 =head1 SYNOPSIS
10
11 You can use Exporter in PIR to import subs from a library. At its simplest:
12
13 .sub main :main
14 load_bytecode 'Test/More.pir'
f6d5c3e @chromatic [PMC] More minor cleanups and reformattings.
chromatic authored
15
bdc07b9 @chromatic [PMC] Add Exporter documentation into POD (Pabellon, RT #44487).
chromatic authored
16 .local pmc exporter, src_ns, dest_ns
17 src_ns = get_namespace [ 'Test'; 'More' ]
abc4db2 @particle [pmc]: exporter api changes
particle authored
18 exporter = new 'Exporter'
f6d5c3e @chromatic [PMC] More minor cleanups and reformattings.
chromatic authored
19
bdc07b9 @chromatic [PMC] Add Exporter documentation into POD (Pabellon, RT #44487).
chromatic authored
20 exporter.'import'( src_ns :named('source') 'plan ok' :named('globals') )
abc4db2 @particle [pmc]: exporter api changes
particle authored
21 plan(1)
22 ok(1, 'exporter has imported the requested functions')
23 .end
24
bdc07b9 @chromatic [PMC] Add Exporter documentation into POD (Pabellon, RT #44487).
chromatic authored
25 You can also specify the exporter attributes before making the import call,
26 for example to import into the alternate namespace 'Foo' you could use the
27 following code:
28
29 src_ns = get_namespace [ 'Test'; 'More' ]
30 dest_ns = get_namespace [ 'Foo' ]
31 exporter.'source'(src_ns)
32 exporter.'destination'(dest_ns)
33 exporter.'import'('plan ok' :named('globals'))
34
35 You can even import subroutines under different names if globals is a hash:
36
37 globals = new 'Hash'
38 globals['plan'] = 'steps'
39 globals['ok'] = 'passed'
40 exporter.'import'(globals :named('globals'))
41 steps(1)
42 passed(1)
43
abc4db2 @particle [pmc]: exporter api changes
particle authored
44
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
45 =head1 DESCRIPTION
46
b29ad29 @particle [pmc] Exporter updates
particle authored
47 Exports globals from one namespace to another. Exporter always uses
6498378 @particle [pmc]: update Exporter documentation based on draft guidelines
particle authored
48 the typed namespace interface, as outlined in
49 F<docs/pdds/pdd21_namespaces.pod>.
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
50
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
51 Exporter is not derived from any other PMC, and does not provide any
abc4db2 @particle [pmc]: exporter api changes
particle authored
52 vtable interface--its interface consists solely of non-vtable methods.
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
53
54 =head2 Structure
55
56 The Exporter PMC structure (C<Parrot_Exporter>) consists of three items:
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
57
58 =over 4
59
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
60 =item C<ns_src>
61
62 The source namespace -- a NameSpace PMC.
5b556ee @particle [pmc]: Exporter is complete
particle authored
63 A Null PMC is allocated during initialization.
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
64
65 =item C<ns_dest>
66
67 The destination namespace -- a NameSpace PMC.
4b47d4c @particle [pmc]: Exporter
particle authored
68 A PMC representing the current namespace is allocated upon initialization.
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
69
70 =item C<globals>
71
bdc07b9 @chromatic [PMC] Add Exporter documentation into POD (Pabellon, RT #44487).
chromatic authored
72 The globals to export -- a PMC that implements a hash, an array, a String
73 containing a list of space-separated subroutine names or Null.
74
b29ad29 @particle [pmc] Exporter updates
particle authored
75 A Null PMC is allocated during initialization.
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
76
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
77 =cut
78
79 */
80
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
81 /*
82
83 =back
84
85 =head2 Functions
86
87 =over 4
88
89 =cut
90
91 */
92
6b81760 @Whiteknight [pmc] we don't need need_ext anymore, so BALEETED
Whiteknight authored
93 pmclass Exporter auto_attrs {
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
94
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
95 ATTR PMC *ns_src;
96 ATTR PMC *ns_dest;
97 ATTR PMC *globals;
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
98
99 /*
100
101 =item C<void init()>
102
b54e3d5 @particle [pmc]: documentation updates
particle authored
103 Initializes an Exporter PMC.
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
104
105 =cut
106
107 */
108
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
109 VTABLE void init() {
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
110 /* Set up the object. */
ac99f44 @NotFound [cage] full use of SET/GET ATTR in exporter PMC
NotFound authored
111 SET_ATTR_ns_src(INTERP, SELF, PMCNULL);
112 SET_ATTR_ns_dest(INTERP, SELF, CONTEXT(interp)->current_namespace);
113 SET_ATTR_globals(INTERP, SELF, PMCNULL);
366638e @particle [pmc]: set pmc flags after anchoring to prevent accidental collection du...
particle authored
114
1997c49 @cotto [gc] remove/replace DOD references in core PMCs
cotto authored
115 /* Set flags for custom GC mark and destroy. */
366638e @particle [pmc]: set pmc flags after anchoring to prevent accidental collection du...
particle authored
116 PObj_custom_mark_SET(SELF);
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
117 }
118
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
119 /*
120
121 =item C<void mark()>
122
123 Mark referenced strings and PMCs in the structure as live.
124
125 =cut
126
127 */
128
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
129 VTABLE void mark() {
ac99f44 @NotFound [cage] full use of SET/GET ATTR in exporter PMC
NotFound authored
130 PMC *ns_src;
131 PMC *ns_dest;
132 PMC *globals;
e8c1290 @NotFound [cage] codingstd hard tabs, mikehh++
NotFound authored
133 GET_ATTR_ns_src(INTERP, SELF, ns_src);
134 GET_ATTR_ns_dest(INTERP, SELF, ns_dest);
135 GET_ATTR_globals(INTERP, SELF, globals);
ac99f44 @NotFound [cage] full use of SET/GET ATTR in exporter PMC
NotFound authored
136
137 if (ns_src)
138 Parrot_gc_mark_PObj_alive(interp, (PObj *)ns_src);
139 if (ns_dest)
140 Parrot_gc_mark_PObj_alive(interp, (PObj *)ns_dest);
141 if (globals)
142 Parrot_gc_mark_PObj_alive(interp, (PObj *)globals);
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
143 }
144
145
146 /*
147
148 =back
149
150 =head2 Methods
151
152 =over 4
153
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
154 =item C<METHOD
f6d5c3e @chromatic [PMC] More minor cleanups and reformattings.
chromatic authored
155 source(PMC *src :optional, int got_src :opt_flag)>
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
156
157 Accessor for the source NameSpace object (C<ns_src>.)
158 Sets the value if C<src> is passed, otherwise returns the value.
159 Throws an exception if a non-NameSpace PMC is passed.
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
160
161 =cut
162
163 */
164
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
165 METHOD source(PMC *src :optional, int got_src :opt_flag) {
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
166 if (got_src) {
2255840 @allisonrandal [pdd17pmc] Merging the pdd25cx branch into trunk for r26555 to r29949.
allisonrandal authored
167 if (src->vtable->base_type != enum_class_NameSpace)
168 Parrot_ex_throw_from_c_args(interp, NULL, 0,
ac3ceb6 @particle [pmc] finish Exporter's 'source' and 'destination' methods
particle authored
169 "source must be a NameSpace PMC");
2255840 @allisonrandal [pdd17pmc] Merging the pdd25cx branch into trunk for r26555 to r29949.
allisonrandal authored
170
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
171 SET_ATTR_ns_src(interp, SELF, src);
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
172 }
173 else {
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
174 PMC *tmp_ns_src;
175 GET_ATTR_ns_src(interp, SELF, tmp_ns_src);
176 RETURN(PMC *tmp_ns_src);
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
177 }
178 }
179
180
181 /*
182
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
183 =item C<METHOD
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
184 destination(PMC *dest :optional, int got_dest :opt_flag)>
9318910 @particle [pmc] Exporter updates
particle authored
185
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
186 Accessor for the destination NameSpace object (C<ns_dest>.)
187 Sets the value if C<dest> is passed, otherwise returns the value.
188 Throws an exception if a non-NameSpace PMC is passed.
9318910 @particle [pmc] Exporter updates
particle authored
189
190 =cut
191
192 */
193
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
194 METHOD destination(PMC *dest :optional, int got_dest :opt_flag) {
9318910 @particle [pmc] Exporter updates
particle authored
195 if (got_dest) {
2255840 @allisonrandal [pdd17pmc] Merging the pdd25cx branch into trunk for r26555 to r29949.
allisonrandal authored
196
197 if (dest->vtable->base_type != enum_class_NameSpace)
198 Parrot_ex_throw_from_c_args(interp, NULL, 0,
199 "destination must be a NameSpace PMC");
200
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
201 SET_ATTR_ns_dest(interp, SELF, dest);
9318910 @particle [pmc] Exporter updates
particle authored
202 }
203 else {
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
204 PMC *tmp_ns_dest;
205 GET_ATTR_ns_dest(interp, SELF, tmp_ns_dest);
206 RETURN(PMC *tmp_ns_dest);
9318910 @particle [pmc] Exporter updates
particle authored
207 }
208 }
209
210
211 /*
212
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
213 =item C<METHOD
b29ad29 @particle [pmc] Exporter updates
particle authored
214 globals(PMC *glb :optional, int got_glb :opt_flag)>
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
215
abc4db2 @particle [pmc]: exporter api changes
particle authored
216 Accessor for the globals to export (C<globals>.)
217 Sets the value if C<glb> is passed, otherwise returns the value.
218 If C<glb> is a String, it is split on ascii whitespace, and each array member
219 is added as a hash key.
220 If C<glb> implements the array interface, each member is added as a hash key.
221 if C<glb> implements the hash interface, it is assigned to Exporter's
222 C<globals> attribute.
223 Throws an exception if an unknown PMC type is passed.
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
224
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
225 =cut
226
227 */
228
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
229 METHOD globals(PMC *glb :optional, int got_glb :opt_flag) {
0006ce7 @chromatic [src] Fixed all CONST_STRING macros so that they don't break across line...
chromatic authored
230 STRING * const s_str = CONST_STRING(interp, "String");
231 STRING * const s_arr = CONST_STRING(interp, "array");
232 STRING * const s_hash = CONST_STRING(interp, "hash");
233 STRING * const s_space = CONST_STRING(interp, " ");
9318910 @particle [pmc] Exporter updates
particle authored
234
b29ad29 @particle [pmc] Exporter updates
particle authored
235 if (got_glb) {
abc4db2 @particle [pmc]: exporter api changes
particle authored
236 STRING * const s_empty = CONST_STRING(interp, "");
237 PMC *temp_globals = pmc_new(interp, enum_class_Hash);
238
239 if (PMC_IS_NULL(glb)) {
240 temp_globals = PMCNULL;
241 }
242 else if (VTABLE_isa(interp, glb, s_str) || (VTABLE_does(interp, glb, s_arr))) {
243 PMC *glb_array;
244 INTVAL n, i;
245
246 if (VTABLE_isa(interp, glb, s_str))
b6bc0c3 @allisonrandal [pdd28str] Merging the pdd27mmd branch into trunk for r36123 to r36318.
allisonrandal authored
247 glb_array = Parrot_str_split(interp, s_space,
0006ce7 @chromatic [src] Fixed all CONST_STRING macros so that they don't break across line...
chromatic authored
248 VTABLE_get_string(interp, glb));
abc4db2 @particle [pmc]: exporter api changes
particle authored
249 else
250 glb_array = glb;
251
252 n = VTABLE_elements(interp, glb_array);
253
254 if (n == 0)
255 temp_globals = PMCNULL;
256
6ab1a64 @paultcochrane [core] Corrected spacing of keywords wrt parentheses as per coding stand...
paultcochrane authored
257 for (i = 0; i < n; i++) {
abc4db2 @particle [pmc]: exporter api changes
particle authored
258 STRING * const item = VTABLE_get_string_keyed_int(interp, glb_array, i);
259 VTABLE_set_string_keyed_str(interp, temp_globals, item, s_empty);
260 }
261 }
262 else if (VTABLE_does(interp, glb, s_hash)) {
263 if (VTABLE_elements(interp, glb) == 0)
264 temp_globals = PMCNULL;
265 else
266 temp_globals = glb;
267 }
268 else {
2255840 @allisonrandal [pdd17pmc] Merging the pdd25cx branch into trunk for r26555 to r29949.
allisonrandal authored
269 Parrot_ex_throw_from_c_args(interp, NULL, 0,
abc4db2 @particle [pmc]: exporter api changes
particle authored
270 "Invalid type %d in globals()", glb->vtable->base_type);
271 }
272
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
273 SET_ATTR_globals(interp, SELF, temp_globals);
b29ad29 @particle [pmc] Exporter updates
particle authored
274 }
275 else {
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
276 PMC *tmp_globals;
277 GET_ATTR_globals(interp, SELF, tmp_globals);
278 if (PMC_IS_NULL(tmp_globals)) {
279 RETURN(PMC *PMCNULL);
b29ad29 @particle [pmc] Exporter updates
particle authored
280 }
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
281 else
282 RETURN(PMC *tmp_globals);
9318910 @particle [pmc] Exporter updates
particle authored
283 }
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
284 }
285
286
287 /*
288
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
289 =item C<METHOD
37922cf @chromatic [lib/PMC] Modified :named parameter syntax in METHODs to match PDD03, pe...
chromatic authored
290 import(PMC *dest :optional :named("destination"), int got_dest :opt_flag,
291 PMC *src :optional :named("source"), int got_src :opt_flag,
292 PMC *globals :optional :named("globals"), int got_globals :opt_flag)>
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
293
294 Import C<globals> from the C<src> namespace to the C<dest> namespace.
abc4db2 @particle [pmc]: exporter api changes
particle authored
295 If C<src>, C<dest>, or C<globals> are passed, they override the current value.
b29ad29 @particle [pmc] Exporter updates
particle authored
296 C<import> follows the semantics of the C<export_to> method
297 of the C<NameSpace> PMC. in particular, if a NULL value is passed
298 for C<globals>, the default set of items will be imported.
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
299 Throws an exception upon error.
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
300
301 =cut
302
303 */
304
37922cf @chromatic [lib/PMC] Modified :named parameter syntax in METHODs to match PDD03, pe...
chromatic authored
305 METHOD import(PMC *dest :optional :named("destination"),
306 int got_dest :opt_flag,
307 PMC *src :optional :named("source"),
308 int got_src :opt_flag,
309 PMC *globals :optional :named("globals"),
310 int got_globals :opt_flag) {
2f8fa82 @particle [pmc]: Exporter beginning 'import' method
particle authored
311
b29ad29 @particle [pmc] Exporter updates
particle authored
312 PMC *ns_src, *ns_dest, *ns_globals;
2f8fa82 @particle [pmc]: Exporter beginning 'import' method
particle authored
313
314 if (got_src)
315 PCCINVOKE(interp, SELF, "source", PMC *src);
f6d5c3e @chromatic [PMC] More minor cleanups and reformattings.
chromatic authored
316
2f8fa82 @particle [pmc]: Exporter beginning 'import' method
particle authored
317 if (got_dest)
318 PCCINVOKE(interp, SELF, "destination", PMC *dest);
f6d5c3e @chromatic [PMC] More minor cleanups and reformattings.
chromatic authored
319
2f8fa82 @particle [pmc]: Exporter beginning 'import' method
particle authored
320 if (got_globals)
321 PCCINVOKE(interp, SELF, "globals", PMC *globals);
9318910 @particle [pmc] Exporter updates
particle authored
322
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
323 GET_ATTR_ns_src(interp, SELF, ns_src);
324 if (PMC_IS_NULL(ns_src))
2255840 @allisonrandal [pdd17pmc] Merging the pdd25cx branch into trunk for r26555 to r29949.
allisonrandal authored
325 Parrot_ex_throw_from_c_args(interp, NULL, 0, "source namespace not set");
f6d5c3e @chromatic [PMC] More minor cleanups and reformattings.
chromatic authored
326
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
327 GET_ATTR_ns_dest(interp, SELF, ns_dest);
328 if (PMC_IS_NULL(ns_dest))
2255840 @allisonrandal [pdd17pmc] Merging the pdd25cx branch into trunk for r26555 to r29949.
allisonrandal authored
329 Parrot_ex_throw_from_c_args(interp, NULL, 0,
330 "destination namespace not set");
2f8fa82 @particle [pmc]: Exporter beginning 'import' method
particle authored
331
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
332 GET_ATTR_globals(interp, SELF, ns_globals);
b29ad29 @particle [pmc] Exporter updates
particle authored
333
334 PCCINVOKE(interp, ns_src, "export_to", PMC *ns_dest, PMC *ns_globals);
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
335 }
336
337
b29ad29 @particle [pmc] Exporter updates
particle authored
338 } /* end pmclass Exporter */
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
339
340 /*
341
342 =back
343
6498378 @particle [pmc]: update Exporter documentation based on draft guidelines
particle authored
344 =head1 STABILITY
345
346 Unstable. This PMC is under active development; major portions of the
347 interface have not yet been completed.
348
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
349 =head1 SEE ALSO
350
eae5b2f @particle [pmc]: documentation overhaul for Exporter
particle authored
351 F<docs/pdds/pdd17_basic_types.pod>, F<docs/pdds/pdd21_namespaces.pod>.
9255c82 @paultcochrane [src] Set svn:keywords and svn:eol-style properties appropriately
paultcochrane authored
352
353 =cut
354
355 */
356
357 /*
358 * Local variables:
359 * c-file-style: "parrot"
360 * End:
361 * vim: expandtab shiftwidth=4:
362 */
Something went wrong with that request. Please try again.