1NiceSlice(3) User Contributed Perl Documentation NiceSlice(3)
2
6 PDL::NiceSlice - toward a nicer slicing syntax for PDL
7
9 use PDL::NiceSlice;
10 $a(1:4) .= 2; # concise syntax for ranges
12 print $b((0),1:$end); # use variables in the slice expression
13 $a->xchg(0,1)->(($pos-1)) .= 0; # default method syntax
14 $idx = long 1, 7, 3, 0; # a piddle of indices
16 $a(-3:2:2,$idx) += 3; # mix explicit indexing and ranges
17 $a->clump(1,2)->(0:30); # 'default method' syntax
18 $a(myfunc(0,$var),1:4)++; # when using functions in slice expressions
19 # use parentheses around args!
20 $b = $a(*3); # Add dummy dimension of order 3
22 # modifiers are specified in a ;-separated trailing block
24 $a($a!=3;?)++; # short for $a->where($a!=3)++
25 $a(0:1114;_) .= 0; # short for $a->flat->(0:1114)
26 $b = $a(0:-1:3;⎪); # short for $a(0:-1:3)->sever
27 $n = sequence 3,1,4,1;
28 $b = $n(;-); # drop all dimensions of size 1 (AKA squeeze)
29 $b = $n(0,0;-⎪); # squeeze *and* sever
30 $c = $a(0,3,0;-); # more compact way of saying $a((0),(3),(0))
31 # Use with perldl versions < v1.31 (or include these lines in .perldlrc)
33 perldl> use PDL::NiceSlice;
34 # next one is required, see below
35 perldl> $PERLDL::PREPROCESS = \&PDL::NiceSlice::perldlpp;
36 perldl> $a(4:5) .= xvals(2);
37
39 Slicing is a basic, extremely common operation, and PDL's slice method
40 would be cumbersome to use in many cases. "PDL::NiceSlice" rectifies
41 that by incorporating new slicing syntax directly into the language via
42 a perl source filter (see the perlfilter man page). NiceSlice adds no
43 new functionality, only convenient syntax.
44 NiceSlice is loaded automatically in the perldl shell, but (to avoid
46 conflicts with other modules) must be loaded automatically in stand‐
47 alone perl/PDL scripts (see below). If you prefer not to use a pre‐
48 filter on your standalone scripts, you can use the slice method in
49 those scripts, rather than the more compact NiceSlice constructs.
50
52 The new slicing syntax can be switched on and off in scripts and perl
53 modules by using or unloading "PDL::NiceSlice".
54 Note: this will not work in the perldl shell < v1.31. Because the
56 perldl shell uses evals, and NiceSlice is a perl source filter, you
57 have to set a special variable to use it within perldl. See below how
58 to enable the new slicing syntax within older perldl.
59 But now back to scripts and modules. Everything after "use PDL::NiceS‐
61 lice" will be translated and you can use the new slicing syntax. Source
62 filtering will continue until the end of the file is encountered. You
63 can stop sourcefiltering before the end of the file by issuing a "no
64 PDL::NiceSlice" statement.
65 Here is an example:
67 use PDL::NiceSlice;
69 # this code will be translated
71 # and you can use the new slicing syntax
72 no PDL::NiceSlice;
74 # this code won't
76 # and the new slicing syntax will raise errors!
77 See also Filter::Simple and example in this distribution for further
79 examples.
80 NOTE: Unlike "normal" modules you need to include a "use PDL::NiceS‐
82 lice" call in each and every file that contains code that uses the new
83 slicing syntax. Imagine the following situation: a file test0.pl
84 # start test0.pl
86 use PDL;
87 use PDL::NiceSlice;
88 $a = sequence 10;
90 print $a(0:4),"\n";
91 require 'test1.pl';
93 # end test0.pl
94 that "require"s a second file test1.pl
96 # begin test1.pl
98 $aa = sequence 11;
99 print $aa(0:7),"\n";
100 1;
101 # end test1.pl
102 Following conventional perl wisdom everything should be alright since
104 we "use"d "PDL" and "PDL::NiceSlice" already from within test0.pl and
105 by the time test1.pl is "require"d things should be defined and
106 imported, etc. A quick test run will, however, produce something like
107 the following:
108 perl test0.pl
110 [0 1 2 3 4]
111 syntax error at test1.pl line 3, near "0:"
112 Compilation failed in require at test0.pl line 7.
113 This can be fixed by adding the line
115 use PDL::NiceSlice;
117 "before" the code in test1.pl that uses the new slicing syntax (to play
119 safe just include the line near the top of the file), e.g.
120 # begin corrected test1.pl
122 use PDL::NiceSlice;
123 $aa = sequence 11;
124 print $aa(0:7),"\n";
125 1;
126 # end test1.pl
127 Now things proceed more smoothly
129 perl test0.pl
131 [0 1 2 3 4]
132 [0 1 2 3 4 5 6 7]
133 Note that we don't need to issue "use PDL" again. "PDL::NiceSlice" is
135 a somewhat funny module in that respect. It is a consequence of the way
136 source filtering works in Perl (see also the IMPLEMENTATION section
137 below).
138 Usage with perldl
140 NOTE: This information only applies to versions of perldl earlier than
142 1.31 . From v1.31 onwards niceslicing is enabled by default, i.e. it
143 should just work. See perldl for details.
144 For pre v1.31 "perldl"s you need to add the following two lines to your
146 .perldlrc file:
147 use PDL::NiceSlice;
149 $PERLDL::PREPROCESS = \&PDL::NiceSlice::perldlpp;
150 A more complete tool box of commands for experimentation is in the file
152 local.perldlrc in the "PDL::NiceSlice" source directory. Just include
153 the code in that file in your usual ~/.perldlrc and you can switch
154 source filtering with PDL::NiceSlice on and off by typing "trans" and
155 "notrans", respectively. To see what and how your commands are trans‐
156 lated switch reporting on:
157 perldl> report 1;
159 Similarly, switch reporting off as needed
161 perldl> report 0;
163 Note that these commands will only work if you included the contents of
165 local.perldlrc in your perldl startup file. In "perldl" v1.31 and
166 later these commands are available by default.
167 evals and "PDL::NiceSlice"
169 Due to "PDL::NiceSlice" being a source filter it won't work in the
171 usual way within evals. The following will not do what you want:
172 $a = sequence 10;
174 eval << 'EOE';
175 use PDL::NiceSlice;
177 $b = $a(0:5);
178 EOE
180 print $b;
181 Instead say:
183 use PDL::NiceSlice;
185 $a = sequence 10;
186 eval << 'EOE';
187 $b = $a(0:5);
189 EOE
191 print $b;
192 Source filters must be executed at compile time to be effective. And
194 "PDL::NiceFilter" is just a source filter (although it is not necessar‐
195 ily obvious for the casual user).
196
198 Using "PDL::NiceSlice" slicing piddles becomes so much easier since,
199 first of all, you don't need to make explicit method calls. No
200 $pdl->slice(....);
202 calls, etc. Instead, "PDL::NiceSlice" introduces two ways in which to
204 slice piddles without too much typing:
205 · using parentheses directly following a scalar variable name, for
207 example
208 $c = $b(0:-3:4,(0));
210 · using the so called default method invocation in which the piddle
212 object is treated as if it were a reference to a subroutine (see also
213 perlref). Take this example that slices a piddle that is part of a
214 perl list @b:
215 $c = $b[0]->(0:-3:4,(0));
217 The format of the argument list is the same for both types of invoca‐
219 tion and will be explained in more detail below.
220 Parentheses following a scalar variable name
222 An arglist in parentheses following directly after a scalar variable
224 name that is not preceded by "&" will be resolved as a slicing command,
225 e.g.
226 $a(1:4) .= 2; # only use this syntax on piddles
228 $sum += $a(,(1));
229 However, if the variable name is immediately preceded by a "&", for
231 example
232 &$a(4,5);
234 it will not be interpreted as a slicing expression. Rather, to avoid
236 interfering with the current subref syntax, it will be treated as an
237 invocation of the code reference $a with argumentlist "(4,5)".
238 The $a(ARGS) syntax collides in a minor way with the perl syntax. In
240 particular, ``foreach $avar(LIST)'' appears like a PDL slicing call.
241 NiceSlice avoids translating the ``for $avar(LIST)'' and ``foreach
242 $avar(LIST)'' constructs for this reason. Since you can't use just any
243 old lvalue expression in the 'foreach' 'for' constructs -- only a real
244 perl scalar will do -- there's no functionality lost. If later ver‐
245 sions of perl accept ``foreach <lvalue-expr> (LIST)'', then you can use
246 the code ref syntax, below, to get what you want.
247 The default method syntax
249 The second syntax that will be recognized is what I called the default
251 method syntax. It is the method arrow "->" directly followed by an open
252 parenthesis, e.g.
253 $a->xchg(0,1)->(($pos)) .= 0;
255 Note that this conflicts with the use of normal code references, since
257 you can write in plain Perl
258 $sub = sub { print join ',', @_ };
260 $sub->(1,'a');
261 NOTE: Once "use PDL::NiceSlice" is in effect (you can always switch it
263 off with a line "no PDL::NiceSlice;" anywhere in the script) the source
264 filter will incorrectly replace the above call to $sub with an invoca‐
265 tion of the slicing method. This is one of the pitfalls of using a
266 source filter that doesn't know anything about the runtime type of a
267 variable (cf. the Implementation section).
268 This shouldn't be a major problem in practice; a simple workaround is
270 to use the "&"-way of calling subrefs, e.g.:
271 $sub = sub { print join ',', @_ };
273 &$sub(1,'a');
274 When to use which syntax?
276 Why are there two different ways to invoke slicing? The first syntax
278 "$a(args)" doesn't work with chained method calls. E.g.
279 $a->xchg(0,1)(0);
281 won't work. It can only be used directly following a valid perl vari‐
283 able name. Instead, use the default method syntax in such cases:
284 $a->xchg(0,1)->(0);
286 Similarly, if you have a list of piddles @pdls:
288 $b = $pdls[5]->(0:-1);
290 The argument list
292 The argument list is a comma separated list. Each argument specifies
294 how the corresponding dimension in the piddle is sliced. In contrast to
295 usage of the slice method the arguments should not be quoted. Rather
296 freely mix literals (1,3,etc), perl variables and function invocations,
297 e.g.
298 $a($pos-1:$end,myfunc(1,3)) .= 5;
300 There can even be other slicing commands in the arglist:
302 $a(0:-1:$pdl($step)) *= 2;
304 NOTE: If you use function calls in the arglist make sure that you use
306 parentheses around their argument lists. Otherwise the source filter
307 will get confused since it splits the argument list on commas that are
308 not protected by parentheses. Take the following example:
309 sub myfunc { return 5*$_[0]+$_[1] }
311 $a = sequence 10;
312 $sl = $a(0:myfunc 1, 2);
313 print $sl;
314 PDL barfed: Error in slice:Too many dims in slice
315 Caught at file /usr/local/bin/perldl, line 232, pkg main
316 The simple fix is
318 $sl = $a(0:myfunc(1, 2));
320 print $sl;
321 [0 1 2 3 4 5 6 7]
322 Note that using prototypes in the definition of myfunc does not help.
324 At this stage the source filter is simply not intelligent enough to
325 make use of this information. So beware of this subtlety.
326 Another pitfall to be aware of: currently, you can't use the condi‐
328 tional operator in slice expressions (i.e., "?:", since the parser con‐
329 fuses them with ranges). For example, the following will cause an
330 error:
331 $a = sequence 10;
333 $b = rand > 0.5 ? 0 : 1; # this one is ok
334 print $a($b ? 1 : 2); # error !
335 syntax error at (eval 59) line 3, near "1,
336 For the moment, just try to stay clear of the conditional operator in
338 slice expressions (or provide us with a patch to the parser to resolve
339 this issue ;).
340 Modifiers
342 Following a suggestion originally put forward by Karl Glazebrook the
344 latest versions of "PDL::NiceSlice" implement modifiers in slice
345 expressions. Modifiers are convenient shorthands for common variations
346 on PDL slicing. The general syntax is
347 $pdl(<slice>;<modifier>)
349 Four modifiers are currently implemented:
351 · "_" : flatten the piddle before applying the slice expression. Here
353 is an example
354 $b = sequence 3, 3;
356 print $b(0:-2;_); # same as $b->flat->(0:-2)
357 [0 1 2 3 4 5 6 7]
358 which is quite different from the same slice expression without the
360 modifier
361 print $b(0:-2);
363 [
364 [0 1]
365 [3 4]
366 [6 7]
367 ]
368 · "⎪" : sever the link to the piddle, e.g.
370 $a = sequence 10;
372 $b = $a(0:2;⎪)++; # same as $a(0:2)->sever++
373 print $b;
374 [1 2 3]
375 print $a; # check if $a has been modified
376 [0 1 2 3 4 5 6 7 8 9]
377 · "?" : short hand to indicate that this is really a where expression
379 As expressions like
381 $a->where($a>5)
383 are used very often you can write that shorter as
385 $a($a>5;?)
387 With the "?"-modifier the expression preceding the modifier is not
389 really a slice expression (e.g. ranges are not allowed) but rather
390 an expression as required by the where method. For example, the
391 following code will raise an error:
392 $a = sequence 10;
394 print $a(0:3;?);
395 syntax error at (eval 70) line 3, near "0:"
396 That's about all there is to know about this one.
398 · "-" : squeeze out any singleton dimensions. In less technical
400 terms: reduce the number of dimensions (potentially) by deleting
401 all dims of size 1. It is equivalent to doing a reshape(-1). That
402 can be very handy if you want to simplify the results of slicing
403 operations:
404 $a = ones 3, 4, 5;
406 $b = $a(1,0;-); # easier to type than $a((1),(0))
407 print $b->info;
408 PDL: Double D [5]
409 It also provides a unique opportunity to have smileys in your code!
411 Yes, PDL gives new meaning to smileys.
412 Combining modifiers
414 Several modifiers can be used in the same expression, e.g.
416 $c = $a(0;-⎪); # squeeze and sever
418 Other combinations are just as useful, e.g. ";_⎪" to flatten and sever.
420 The sequence in which modifiers are specified is not important.
421 A notable exception is the "where" modifier ("?") which must not be
423 combined with other flags (let me know if you see a good reason to
424 relax this rule).
425 Repeating any modifier will raise an error:
427 $c = $a(-1:1;⎪-⎪); # will cause error
429 NiceSlice error: modifier ⎪ used twice or more
430 Modifiers are still a new and experimental feature of "PDL::NiceSlice".
432 I am not sure how many of you are actively using them. Please do so and
433 experiment with the syntax. I think modifiers are very useful and make
434 life a lot easier. Feedback is welcome as usual. The modifier syntax
435 will likely be further tuned in the future but we will attempt to
436 ensure backwards compatibility whenever possible.
437 Argument formats
439 In slice expressions you can use ranges and secondly, piddles as 1D
441 index lists (although compare the description of the "?"-modifier above
442 for an exception).
443 * ranges
445 You can access ranges using the usual ":" separated format:
446 $a($start:$stop:$step) *= 4;
448 Note that you can omit the trailing step which then defaults to 1.
450 Double colons ("::") are not allowed to avoid clashes with Perl's
451 namespace syntax. So if you want to use steps different from the
452 default you have to also at least specify the stop position. Exam‐
453 ples:
454 $a(::2); # this won't work (in the way you probably intended)
456 $a(:-1:2); # this will select every 2nd element in the 1st dim
457 Just as with slice negative indices count from the end of the dimen‐
459 sion backwards with "-1" being the last element. If the start index
460 is larger than the stop index the resulting piddle will have the ele‐
461 ments in reverse order between these limits:
462 print $a(-2:0:2);
464 [8 6 4 2 0]
465 A single index just selects the given index in the slice
467 print $a(5);
469 [5]
470 Note, however, that the corresponding dimension is not removed from
472 the resulting piddle but rather reduced to size 1:
473 print $a(5)->info
475 PDL: Double D [1]
476 If you want to get completely rid of that dimension enclose the index
478 in parentheses (again similar to the slice syntax):
479 print $a((5));
481 5
482 In this particular example a 0D piddle results. Note that this syntax
484 is only allowed with a single index. All these will be errors:
485 print $a((0,4)); # will work but not in the intended way
487 print $a((0:4)); # compile time error
488 An empty argument selects the whole dimension, in this example all of
490 the first dimension:
491 print $a(,(0));
493 Alternative ways to select a whole dimension are
495 $a = sequence 5, 5;
497 print $a(:,(0));
498 print $a(0:-1,(0));
499 print $a(:-1,(0));
500 print $a(0:,(0));
501 Arguments for trailing dimensions can be omitted. In that case these
503 dimensions will be fully kept in the sliced piddle:
504 $a = random 3,4,5;
506 print $a->info;
507 PDL: Double D [3,4,5]
508 print $a((0))->info;
509 PDL: Double D [4,5]
510 print $a((0),:,:)->info; # a more explicit way
511 PDL: Double D [4,5]
512 print $a((0),,)->info; # similar
513 PDL: Double D [4,5]
514 * dummy dimensions
516 As in slice, you can insert a dummy dimension by preceding a single
517 index argument with '*'. A lone '*' inserts a dummy dimension of
518 order 1; a '*' followed by a number inserts a dummy dimension of that
519 order.
520 * piddle index lists
522 The second way to select indices from a dimension is via 1D piddles
523 of indices. A simple example:
524 $a = random 10;
526 $idx = long 3,4,7,0;
527 $b = $a($idx);
528 This way of selecting indices was previously only possible using dice
530 ("PDL::NiceSlice" attempts to unify the "slice" and "dice" inter‐
531 faces). Note that the indexing piddles must be 1D or 0D. Higher
532 dimensional piddles as indices will raise an error:
533 $a = sequence 5, 5;
535 $idx2 = ones 2,2;
536 $sum = $a($idx2)->sum;
537 piddle must be <= 1D at /home/XXXX/.perldlrc line 93
538 Note that using index piddles is not as efficient as using ranges.
540 If you can represent the indices you want to select using a range use
541 that rather than an equivalent index piddle. In particular, memory
542 requirements are increased with index piddles (and execution time may
543 be longer). That said, if an index piddle is the way to go use it!
544 As you might have expected ranges and index piddles can be freely mixed
546 in slicing expressions:
547 $a = random 5, 5;
549 $b = $a(-1:2,pdl(3,0,1));
550 piddles as indices in ranges
552 You can use piddles to specify indices in ranges. No need to turn them
554 into proper perl scalars with the new slicing syntax. However, make
555 sure they contain not more than one element! Otherwise a runtime error
556 will be triggered. First a couple of examples that illustrate proper
557 usage:
558 $a = sequence 5, 5;
560 $rg = pdl(1,-1,3);
561 print $a($rg(0):$rg(1):$rg(2),2);
562 [
563 [11 14]
564 ]
565 print $a($rg+1,:$rg(0));
566 [
567 [2 0 4]
568 [7 5 9]
569 ]
570 The next one raises an error
572 print $a($rg+1,:$rg(0:1));
574 multielement piddle where only one allowed at XXX/Core.pm line 1170.
575 The problem is caused by using the 2-element piddle "$rg(0:1)" as the
577 stop index in the second argument ":$rg(0:1)" that is interpreted as a
578 range by "PDL::NiceSlice". You can use multielement piddles as index
579 piddles as described above but not in ranges. And "PDL::NiceSlice"
580 treats any expression with unprotected ":"'s as a range. Unprotected
581 means as usual "not occurring between matched parentheses".
582
584 "PDL::NiceSlice" exploits the ability of Perl to use source filtering
585 (see also perlfilter). A source filter basically filters (or rewrites)
586 your perl code before it is seen by the compiler. "PDL::NiceSlice"
587 searches through your Perl source code and when it finds the new slic‐
588 ing syntax it rewrites the argument list appropriately and splices a
589 call to the "nslice" method using the modified arg list into your perl
590 code. You can see how this works in the perldl shell by switching on
591 reporting (see above how to do that).
592 The "nslice" method is an extended version of mslice that knows how to
594 deal with index piddles (and therefore combines slicing and dicing).
595 Full documentation of "nslice" will be in the next PDL release.
596
598 Conditional operator
599 The conditional operator can't be used in slice expressions (see
601 above).
602 The "DATA" file handle
604 Note: To avoid clobbering the "DATA" filehandle "PDL::NiceSlice"
606 switches itself off when encountering the "__END__" or "__DATA__"
607 tokens. This should not be a problem for you unless you use "Self‐
608 Loader" to load PDL code including the new slicing from that section.
609 It is even desirable when working with Inline::Pdlpp, see below.
610 Possible interaction with Inline::Pdlpp
612 There is currently an undesired interaction between "PDL::NiceSlice"
614 and the new Inline::Pdlpp module (currently only in PDL CVS). Since PP
615 code generally contains expressions of the type "$var()" (to access
616 piddles, etc) "PDL::NiceSlice" recognizes those incorrectly as slice
617 expressions and does its substitutions. This is not a problem if you
618 use the "DATA" section for your Pdlpp code -- the recommended place for
619 Inline code anyway. In that case "PDL::NiceSlice" will have switched
620 itself off before encountering any Pdlpp code (see above):
621 # use with Inline modules
623 use PDL;
624 use PDL::NiceSlice;
625 use Inline Pdlpp;
626 $a = sequence(10);
628 print $a(0:5);
629 __END__
631 __Pdlpp__
633 ... inline stuff
635 Otherwise switch "PDL::NiceSlice" explicitly off around the
637 Inline::Pdlpp code:
638 use PDL::NiceSlice;
640 $a = sequence 10;
642 $a(0:3)++;
643 $a->inc;
644 no PDL::NiceSlice; # switch off before Pdlpp code
646 use Inline Pdlpp => "Pdlpp source code";
647 The cleaner solution is to always stick with the "DATA" way of includ‐
649 ing your "Inline" code as in the first example. That way you keep your
650 nice Perl code at the top and all the ugly Pdlpp stuff etc at the bot‐
651 tom.
652 Bug reports
654 Feedback and bug reports are welcome. Please include an example that
656 demonstrates the problem. Log bug reports in the PDL bug database at
657 http://sourceforge.net/bugs/?group_id=612
659 or send them to the pdl-porters mailing list
661 <pdl-porters@jach.hawaii.edu>.
662
664 Copyright (c) 2001, 2002 Christian Soeller. All Rights Reserved. This
665 module is free software. It may be used, redistributed and/or modified
666 under the same terms as PDL itself (see http://pdl.perl.org).
667perl v5.8.8 2004-04-09 NiceSlice(3)