1PERLDL(1)             User Contributed Perl Documentation            PERLDL(1)
2
3
4

NAME

6       perldl - Simple shell for PDL (see also pdl2)
7

SYNOPSIS

9       Use PDL interactively:
10
11         bash$ perldl
12         pdl> $x = sequence(10) # or any other perl or PDL command
13
14         bash$ pdl
15         pdl> print "Hello, world!\n";
16
17         pdl> with_time { print +($A->matmult($B))->info, "\n" } for 1..5;
18
19       Run a script:
20
21         bash$ cat > pdlscript
22         #!/usr/bin/pdl
23         print "Hello, world!\n";
24         ...
25

DESCRIPTION

27       The program perldl is a simple shell (written in perl) for interactive
28       use of PDL.  It consists of a command-line interface that supports
29       immediate interpretation of perl commands and expressions.  Perl
30       expressions, including PDL constructs, can be entered directly at the
31       keyboard and are compiled and executed immediately.  The syntax is not
32       exactly identical to Perl, in that under most circumstances ending a
33       line causes immediate execution of the command entered so far (no
34       trailing ';' is required).
35
36       The synonym pdl is a compiled executable that is useful as a script
37       interpreter using UNIX shebang ("#!") syntax.  This is useful for
38       generating and re-executing command-journal files from perldl.
39
40       The perldl shell runs an initial startup file ("~/.perldlrc") that can
41       be used to pre-load perl modules or configure the global perl
42       environment.  It features a path mechanism for autoloading perl
43       subroutines.  There is a command-history mechanism, and several other
44       useful features such as command preprocessing, shortcuts for commonly
45       used commands such as "print", and the ability to execute arbitrary
46       code whenever a prompt is printed.
47
48       Depending on your configuration settings, perldl can be set to honor or
49       ignore the ^D (end-of-file) character when sent from a terminal, or to
50       attempt to do the Right Thing when a block construct spanning multiple
51       lines is encountered.
52
53       perldl and pdl support several command-line options, which are
54       discussed near the end of this document.
55
56   Reference manual & online help
57       The PDL reference manual and online help are available from within
58       perldl, using the help and apropos commands (which may also be
59       abbreviated ? and ??.)   The help command alone prints a summary of
60       help syntax, and help <module-name> will print POD documentation from
61       the module you mention (POD is the Perl format for embedding
62       documentation in your perl code; see perlpod for details).
63
64       If you include POD documentation in your autoload subroutines (see path
65       mechanism below), then both help and apropos will find it and be able
66       to format and display it on demand.
67
68   History mechanism
69       If you have the perl modules ReadLines and ReadKeys installed, then
70       perldl supports a history and line-editing mechanism using editing keys
71       similar to "emacs". The last 500 commands are always stored in the file
72       .perldl_hist in your home directory between sessions.  Set
73       $PERLDL::HISTFILESIZE to change the number of lines saved.  The command
74       "l [number]" shows you the last "number" commands you typed where
75       "number" defaults to 20.
76
77       e.g.:
78
79          bash$ perldl
80          ReadLines enabled
81          pdl> $x = rfits "foo.fits"
82          BITPIX =  -32  size = 88504 pixels
83          Reading  354016 bytes
84          BSCALE =  &&  BZERO =
85
86          pdl> imag log($x+400)
87          Displaying 299 x 296 image from 4.6939525604248 to 9.67116928100586 ...
88
89   Command execution
90       If you enter a simple command at the perldl command line, it is
91       immediately executed in a Perl eval().  The environment is almost
92       identical to that within a perl script, with some important exceptions:
93
94       •  $_ is not preserved across lines
95
96          $_ is used to hold the command line for initial processing, so at
97          the beginning of processing of each command line, $_ contains the
98          command itself.  Use variables other than $_ to store values across
99          lines.
100
101       •  Scope is not preserved across lines
102
103          Each command line is executed in a separate "eval" block within
104          perl, so scoping commands such as "my" and "local" may not perform
105          exactly as expected -- in particular, if you declare a variable with
106          "my", it is local to the particular command line on which you typed
107          the "my" command, which means that it will evaporate before the next
108          prompt is printed.  (You can use "my" variables in a multi-line
109          block or to isolate values within a single command line, of course).
110
111            NOTE: pdl2 preserves lexical scope between lines.
112
113       •  Execution is immediate
114
115          Under most circumstances, as soon as you end a line of input the
116          line is parsed and executed.  This breaks Perl's normal dependence
117          on semicolons as command delimiters.  For example, the two-line
118          expression
119
120            print "Hello ",
121               "world";
122
123          prints the phrase "Hello world" in Perl, but (under most
124          circumstances) "Hello " in perldl.
125
126       •  Multi-line execution
127
128          In multiline mode (which is enabled by default, see Shell variables,
129          below), perldl searches for searches for block-like constructs with
130          curly braces, parentheses, quotes, and related delimiters.  If you
131          leave such a construct open, perldl accepts more lines of input
132          until you close the construct or explicitly end the multi-line
133          expression with ^D.   Following the example above, the phrase
134
135            { print "Hello ",
136                 "world"; }
137
138          will print "Hello world" from either Perl or (in multi-line mode)
139          perldl.
140
141          Warning: The multi-line parsing uses Damian Conway's Text::Balanced
142          module, which contains some flaws -- so it can be fooled by quote-
143          like operators such as "q/.../", included POD documentation, multi-
144          line "<<" quotes, and some particularly bizarre-but-valid "m/.../"
145          matches and "s/.../.../" substitutions.  In such cases, use ^D to
146          close out the multi-line construct and force compilation-and-
147          execution.
148
149       If you want to preserve this behavior in a script (for example to
150       replay a command journal file; see below on how to create one), you can
151       use pdl instead of perl as the interpreter in the script's initial
152       shebang line.
153
154   Terminating "perldl"
155       A "perldl" session can be terminated with any of the commands "quit",
156       "exit" or the shorthands "x" or "q".  If EOF handling is switched on
157       (the default) you can also type ^D at the command prompt.
158
159       If the command input is NOT a terminal (for example if you are running
160       from a command journal file), then EOF will always terminate perldl.
161
162   Terminating commands (Ctrl-C handling)
163       Commands executed within "perldl" can be terminated prematurely using
164       "Ctrl-C" (or whichever key sequence sends an INT signal to the process
165       on your terminal). Provided your PDL code does not ignore "sigint"s
166       this should throw you back at the "perldl" command prompt:
167
168         pdl> $result = start_lengthy_computation()
169          <Ctrl-C>
170         Ctrl-C detected
171
172         pdl>
173
174       As of 2.077, this requires Sys::SigAction to be installed (without
175       that, and before 2.077, for Perl >5.8 it didn't actually interrupt
176       things).
177
178   Shortcuts and aliases
179       •   The shell aliases "p" to be a convenient short form of "print",
180           e.g.
181
182              pdl> p ones 5,3
183
184              [
185               [1 1 1 1 1]
186               [1 1 1 1 1]
187               [1 1 1 1 1]
188              ]
189
190       •   "q" and "x" are short-hand for "quit".
191
192       •   "l" lists the history buffer
193
194             pdl> l # list last 20 commands
195
196             pdl> l 40 # list last 40 commands
197
198       •   "?" is an alias for help
199
200             pdl> ? pdl2    # get help for new pdl2 shell
201
202       •   "??" is an alias for apropos
203
204             pdl> ?? PDL::Doc
205
206       •   help, apropos, usage and sig: all words after these commands are
207           used verbatim and not evaluated by perl. So you can write, e.g.,
208
209             pdl> help help
210
211           instead of
212
213             pdl> help 'help'
214
215       •   "with_time" runs the following code-block, and tells you how long
216           it took, in milliseconds. Requires Time::HiRes.
217
218             pdl> with_time { print +($A->matmult($B))->info, "\n" } for 1..5;
219
220   Command-line options
221       perldl and pdl support several command-line options to adjust the
222       behavior of the session.  Most of them are equivalent to commands that
223       can be entered at the pdl> prompt.  They are:
224
225       -glut
226           Load OpenGL when starting the shell (the perl OpenGL module, which
227           is available from CPAN must be installed).  This enables readline
228           event loop processing.  Don't use with -tk.
229
230       -tk Load Tk when starting the shell (the perl Tk module, which is
231           available from CPAN must be installed).  This enables readline
232           event loop processing.  Don't use with -glut.
233
234       -f file
235           Loads the file before processing any user input. Any errors during
236           the execution of the file are fatal.
237
238       -w  Runs with warning messages (i.e. the normal perl "-w" warnings)
239           turned-on.
240
241       -M module
242           Loads the module before processing any user input.  Compare
243           corresponding "perl" switch.
244
245       -m module
246           Unloads the module before processing any user input.
247
248       -I directory
249           Adds directory to the include path. (i.e. the @INC array) Compare
250           corresponding "perl" switch.
251
252       -V  Prints a summary of PDL config. This information should be included
253           with any PDL bug report. Compare corresponding "perl" switch.
254
255   The startup file ~/.perldlrc
256       If the file ~/.perldlrc is found it is sourced at start-up to load
257       default modules, set shell variables, etc. If it is NOT found the
258       distribution file PDL/default.perldlrc is read instead. This loads
259       various modules considered useful by default, and which ensure
260       compatibility with v1.11. If you don't like this and want a more
261       streamlined set of your own favourite modules simple create your own
262       ~/.perldlrc.  You may wish to start from the existing
263       PDL/default.perldlrc as a template since it will not be sourced once
264       you replace it with your own version.
265
266       To set even more local defaults the file  local.perldlrc (in the
267       current directory) is sourced if found. This lets you load modules and
268       define subroutines for the project in the current directory.
269
270       The name is chosen specifically because it was found hidden files were
271       NOT wanted in these circumstances.
272
273       The startup file should normally include "use PDL::AutoLoader;", as
274       many of the nicer interactive features won't work without it.
275
276   Shell variables
277       Shell variables: (Note: if you don't like the defaults change them in
278       ~/.perldlrc)
279
280       •   $PERLDL::ESCAPE  - default value '#'
281
282           Any line starting with this character is treated as a shell escape.
283           The default value is chosen because it escapes the code from the
284           standard perl interpreter.
285
286       •   $PERLDL::HISTFILESIZE  - default value 500
287
288           This is the number of lines of perldl shell command history to
289           keep.
290
291       •   $PERLDL::PAGER - default value "more"
292
293           External program to filter the output of commands.  Using "more"
294           prints output one screenful at a time.  On Unix, setting page(1)
295           and $PERLDL::PAGER to "tee -a outfile" will keep a record of the
296           output generated by subsequent perldl commands (without paging).
297
298       •   $PERLDL::PROMPT - default value 'pdl> '
299
300           Enough said  But can also be set to a subroutine reference, e.g.
301           $PERLDL::PROMPT = sub {join(':',(gmtime)[2,1,0]).'> '} puts the
302           current time into the prompt.
303
304       •   $PERLDL::MULTI - default value 1
305
306           If this is set to a true value, then perldl will parse multi-line
307           perl blocks: your input will not be executed until you finish a
308           line with no outstanding group operators (such as quotes, blocks,
309           parenthesis, or brackets) still active.  Continuation lines have a
310           different prompt that shows you what delimiters are still active.
311
312           Note that this is not (yet!) a complete perl parser.  In
313           particular, Text::Balanced appears to be able to ignore quoting
314           operatores like "q/ ... /" within a line, but not to be able to
315           extend them across lines.  Likewise, there is no support for the
316           '<<' operator.
317
318           Multiline conventional strings and {}, [], and () groupings are
319           well supported.
320
321       •   $PERLDL::NO_EOF - default value 0 / 1 on MSWin32
322
323           Protects against accidental use of "^D" from the terminal.  If this
324           is set to a true value, then you can't accidentally exit perldl by
325           typing "^D".  If you set it to a value larger than 1 (and
326           PERLDL::MULTI is set), then you can't use "^D" to exit multiline
327           commands either.  If you're piping commands in from a file or pipe,
328           this variable has no effect.
329
330       •   $HOME
331
332           The user's home directory
333
334       •   $PERLDL::TERM
335
336           This is the Term::ReadLine object associated with the perldl shell.
337           It can be used by routines called from perldl if your command is
338           interactive.
339
340       •   $PDL::toolongtoprint
341
342           The maximal size pdls to print (defaults to 10,000 elements).  This
343           is not just a "perldl" or "pdl2" variable but it is something that
344           is usually needed in an interactive debugging session.
345
346   Executing scripts from the "perldl" prompt
347       A useful idiom for developing perldl scripts or editing functions on-
348       line is
349
350         pdl> # emacs script &
351           -- add perldl code to script and save the file
352
353         pdl> do 'script'
354
355       -- substitute your favourite window-based editor for 'emacs' (you may
356       also need to change the '&' on non-Unix systems).
357
358       Running "do 'script'" again updates any variables and function
359       definitions from the current version of 'script'.
360
361   Executing perldl scripts from the command line
362       PDL scripts are just perl scripts that happen to use PDL (and possibly
363       PDL::NiceSlice).  But for the truly lazy, perldl can be invokes as a
364       script interpreter.  Because perldl is itself an interpreted perl
365       script, most unices won't allow you to say "#!/usr/bin/perldl" at the
366       top of your script.
367
368       Instead, say "#!/usr/bin/pdl" and your script will be executed exactly
369       as if you typed it, line-by-line, into the perldl shell.
370
371   Command preprocessing
372       NOTE: This feature is used by default by PDL::NiceSlice.  See below for
373       more about slicing at the "perldl" prompt
374
375       In some cases, it is convenient to process commands before they are
376       sent to perl for execution. For example, this is the case where the
377       shell is being presented to people unfamiliar with perl but who wish to
378       take advantage of commands added locally (eg by automatically quoting
379       arguments to certain commands).
380
381       *NOTE*: The preprocessing interface has changed from earlier versions!
382       The old way using $PERLDL::PREPROCESS will still work but is strongly
383       deprecated and might go away in the future.
384
385       You can enable preprocessing by registering a filter with the
386       "preproc_add" function. "preproc_add" takes one argument which is the
387       filter to be installed. A filter is a Perl code reference (usually set
388       in a local configuration file) that will be called, with the current
389       command string as argument, just prior to the string being executed by
390       the shell. The modified string should be returned. Note that you can
391       make "perldl" completely unusable if you fail to return the modified
392       string; quitting is then your only option.
393
394       Filters can be removed from the preprocessing pipeline by calling
395       "preproc_del" with the filter to be removed as argument.  To find out
396       if a filter is currently installed in the preprocessing pipeline use
397       "preproc_registered":
398
399         pdl> preproc_add $myfilter unless preproc_registered $myfilter;
400
401       Previous versions of "perldl" used the variable $PERLDL::PREPROCESS.
402       This will still work but should be avoided. Please change your scripts
403       to use the "preproc_add" etc functions.
404
405       The following code would check for a call to function 'mysub' and
406       bracket arguments with qw.
407
408         $filter = preproc_add sub {
409            my $str = shift;
410            $str =~ s/^\s+//;  # Strip leading space
411            if ($str =~ /^mysub/) {
412               my ($command, $arguments) = split(/\s+/,$str, 2);
413               $str = "$command qw( $arguments )"
414               if (defined $arguments && $arguments !~ /^qw/);
415            };
416            # Return the input string, modified as required
417            return $str;
418          };
419
420       This would convert:
421
422         pdl> mysub arg1 arg2
423
424       to
425
426         pdl> mysub qw( arg1 arg2 )
427
428       which Perl will understand as a list.  Obviously, a little more effort
429       is required to check for cases where the caller has supplied a normal
430       list (and so does not require automatic quoting) or variable
431       interpolation is required.
432
433       You can remove this preprocessor using the "preproc_del" function which
434       takes one argument (the filter to be removed, it must be the same
435       coderef that was returned from a previous "preproc_add" call):
436
437         pdl> preproc_del $filter;
438
439       An example of actual usage can be found in the "perldl" script. Look at
440       the function "trans" to see how the niceslicing preprocessor is
441       enabled/disabled.
442
443   "perldl" and PDL::NiceSlice
444       PDL::NiceSlice introduces a more convenient slicing syntax for
445       ndarrays. In current versions of "perldl" and "pdl2" niceslicing is
446       enabled by default (if the required CPAN modules are installed on your
447       machine).
448
449       At startup "perldl" will let you know if niceslicing is enabled. The
450       startup message will contain info to this end, something like this:
451
452          perlDL shell v1.XX
453           PDL comes with ABSOLUTELY NO WARRANTY. For details, see the file
454           'COPYING' in the PDL distribution. This is free software and you
455           are welcome to redistribute it under certain conditions, see
456           the same file for details.
457          ReadLines, NiceSlice  enabled
458          Reading /home/csoelle/.perldlrc...
459          Type 'demo' for online demos
460          Loaded PDL v2.XX
461
462       When you get such a message that indicates "NiceSlice" is enabled you
463       can use the enhanced slicing syntax:
464
465         pdl> $x = sequence 10;
466         pdl> p $x(3:8:2)
467
468       For details consult PDL::NiceSlice.
469
470       PDL::NiceSlice installs a filter in the preprocessing pipeline (see
471       above) to enable the enhanced slicing syntax. You can use a few
472       commands in the "perldl" shell to switch this preprocessing on or off
473       and also explicitly check the substitutions that the NiceSlice filter
474       makes.
475
476       You can switch the PDL::NiceSlice filter on and off by typing
477
478         pdl> trans # switch niceslicing on
479
480       and
481
482         pdl> notrans # switch niceslicing off
483
484       respectively. The filter is on by default.
485
486       To see how your commands are translated switch reporting on:
487
488         pdl> report 1;
489         pdl> p $x(3:8:2)
490         processed p $x->slice([3,8,2])
491         [3 5 7]
492
493       Similarly, switch reporting off as needed
494
495         pdl> report 0;
496         pdl>  p $x(3:8:2)
497         [3 5 7]
498
499       Reporting is off by default.
500
501   Automatically execute your own hooks
502       The variable @PERLDL::AUTO is a simple list of perl code strings and/or
503       code reference. It is used to define code to be executed automatically
504       every time the user enters a new line.
505
506       A simple example would be to print the time of each command:
507
508         pdl> push @PERLDL::AUTO,'print scalar(gmtime),"\n"'
509
510         pdl> print zeroes(3,3)
511         Sun May  3 04:49:05 1998
512
513         [
514          [0 0 0]
515          [0 0 0]
516          [0 0 0]
517         ]
518
519         pdl> print "Boo"
520         Sun May  3 04:49:18 1998
521         Boo
522         pdl>
523
524       Or to make sure any changes in the file 'local.perldlrc' are always
525       picked up :-
526
527         pdl> push @PERLDL::AUTO,"do 'local.perldlrc'"
528
529       This code can of course be put *in* 'local.perldlrc', but be careful
530       :-) [Hint: add "unless ($started++)" to above to ensure it only gets
531       done once!]
532
533       Another example application is as a hook for Autoloaders (e.g.
534       PDL::AutoLoader) to add code too which allows them to automatically re-
535       scan their files for changes. This is extremely convenient at the
536       interactive command line. Since this hook is only in the shell it
537       imposes no inefficiency on PDL scripts.
538
539       Finally note this is a very powerful facility - which means it should
540       be used with caution!
541
542
543
544perl v5.38.0                      2023-07-21                         PERLDL(1)
Impressum