Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PSH 1" | |
132 | .TH PSH 1 "2003-01-02" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | psh \- Perl SHell | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | The Perl Shell documentation has been split into a number of different | |
138 | manpages: | |
139 | .PP | |
140 | psh This overview | |
141 | .PP | |
142 | pshdevel Developing for the Perl Shell | |
143 | .PP | |
144 | pshconfig Configuring the Perl Shell | |
145 | .PP | |
146 | pshcomplete \s-1TAB\s0 completions in the Perl Shell | |
147 | .SH "DESCRIPTION" | |
148 | .IX Header "DESCRIPTION" | |
149 | \&\fBpsh\fR is a Perl program which executes a read-eval loop with enough | |
150 | options so that general behavior reasonably similar to more | |
151 | traditional shells like '\fBsh\fR' or '\fBbash\fR' can be achieved, while still | |
152 | allowing arbitrary perl expressions to be evaluated. | |
153 | .PP | |
154 | By default within \fBpsh\fR, the Perl \fB\-w\fR flag and '\f(CW\*(C`use strict\*(C'\fR' are not | |
155 | employed so that the user is not bound by their stipulations. | |
156 | They can both be turned on via a command-line flag; or setting | |
157 | \&\f(CW\*(C`$^W = 1\*(C'\fR will turn on warnings, and calling '\f(CW\*(C`use strict\*(C'\fR' will | |
158 | (almost) do the usual thing if called by the user (see \s-1LIMITATIONS\s0, below). | |
159 | .PP | |
160 | Each line of input is read. \fBpsh\fR knows a number of possible | |
161 | strategies for evaluating the line, such as "send it to \f(CW\*(C`system()\*(C'\fR if it | |
162 | starts with the name of an executable visible in \f(CW$ENV{PATH}\fR". (See | |
163 | below for a complete list.) | |
164 | Each strategy in turn (from a user-definable | |
165 | list) examines the command line to see if it can apply, and the first | |
166 | matching strategy evaluates the line. There is a \fBpsh\fR configuration | |
167 | variable (see below) which controls whether the perl value of the | |
168 | evaluation is saved and printed after each command. | |
169 | .PP | |
170 | \&\fBpsh\fR automatically collects several lines of input into a unit | |
171 | processed as a single line if there are unfinished Perl constructs on | |
172 | the line. In particular, if there is an unmatched quote, paren, brace, | |
173 | or square bracket, input is read until these characters match. If an | |
174 | input line contains the Perl \*(L"here document\*(R" construct as in | |
175 | \&\f(CW\*(C`<<XXX\*(C'\fR, (anywhere on the line), then input is read and | |
176 | accumulated until \f(CW\*(C`XXX\*(C'\fR occurs on a line by itself. Then the | |
177 | accumulated input is processed as if it were a single line. | |
178 | .SH "OPTIONS" | |
179 | .IX Header "OPTIONS" | |
180 | The command-line arguments to \fBpsh\fR are: | |
181 | .PP | |
182 | .Vb 1 | |
183 | \& psh [-d [options]] [-w] [-F] [-f RC_FILE] [-c STRING ] [FILE1 FILE2 ....] | |
184 | .Ve | |
185 | .PP | |
186 | They are processed in the following order, regardless of what order | |
187 | they are specified in: | |
188 | .IP "\(bu \fB\-w\fR" 4 | |
189 | .IX Item "-w" | |
190 | Enables Perl's warning mode. The \fB\-w\fR switch runs perl with the | |
191 | \&\fB\-w\fR switch and \*(L"use strict;\*(R". | |
192 | .IP "\(bu \fB\-d\fR [debug options]" 4 | |
193 | .IX Item "-d [debug options]" | |
194 | The \fB\-d\fR option puts \fBpsh\fR into \*(L"debugging\*(R" mode, which prints | |
195 | diagnostic output. Note that you can also enter/leave this | |
196 | debugging mode in a running \fBpsh\fR via the \f(CW$Psh::debugging\fR variable. | |
197 | .IP "\(bu \fB\-i\fR" 4 | |
198 | .IX Item "-i" | |
199 | Only for compatibility reasons and ignored by Perl Shell. | |
200 | .IP "\(bu \fB\-f\fR \fIfile\fR" 4 | |
201 | .IX Item "-f file" | |
202 | The \fB\-f\fR option specifies a file of commands to be read in and | |
203 | evaluated before processing begins. If it is not set, and | |
204 | \&\f(CW$ENV{HOME}\fR is set, and the file \fI$ENV{\s-1HOME\s0}/.pshrc\fR is present, it | |
205 | will be used. If \fB\-r\fR is not specified and the current directory is | |
206 | different from \f(CW$ENV{HOME}\fR and it contains a \fI.pshrc\fR file, that | |
207 | file will be read and executed in addition to | |
208 | \&\fI$ENV{\s-1HOME\s0}/.pshrc\fR. | |
209 | .IP "\(bu \fB\-F\fR" 4 | |
210 | .IX Item "-F" | |
211 | No pshrc files will be read and executed. | |
212 | .IP "\(bu \fB\-c\fR \fIstring\fR" 4 | |
213 | .IX Item "-c string" | |
214 | If the \fB\-c\fR flag is present, then commands are read from | |
215 | \&\f(CW\*(C`string\*(C'\fR, and then \fBpsh\fR exits. In particular, any \s-1FILE1\s0 | |
216 | \&... arguments will be ignored. | |
217 | .PP | |
218 | If any \s-1FILE1\s0 ... arguments are specified on the command line, they | |
219 | will be read and executed and then \fBpsh\fR will exit. Otherwise, \fBpsh\fR | |
220 | will enter an interactive command loop. | |
221 | .Sh "\s-1TOKENIZATION\s0" | |
222 | .IX Subsection "TOKENIZATION" | |
223 | Some evaluation strategies examine the \*(L"words\*(R" of the input. These are | |
224 | produced by a tokenizer which behaves very similarly to traditional | |
225 | shells: words are broken at whitespace, '&' is a metacharacter which | |
226 | means that it always forms its own word, and backslash and double and | |
227 | single quotes act as quoting characters, preventing word breaks at | |
228 | whitespace and the \*(L"meta\-ness\*(R" of &. | |
229 | .PP | |
230 | If the description of the strategy does not mention the \*(L"words\*(R", then | |
231 | the tokenization is irrelevant to that strategy. | |
232 | .Sh "\s-1STANDARD\s0 \s-1EVALUATION\s0 \s-1STRATEGIES\s0" | |
233 | .IX Subsection "STANDARD EVALUATION STRATEGIES" | |
234 | \&\fBpsh\fR includes the following evaluation strategies, sorted by the | |
235 | default order. For adding/removing evaluation | |
236 | strategies we suggest the usage of the built-in command \*(L"strategy\*(R" | |
237 | from within psh. | |
238 | .ie n .IP "\(bu ""comment""" 4 | |
239 | .el .IP "\(bu \f(CWcomment\fR" 4 | |
240 | .IX Item "comment" | |
241 | If the first word of the input line begins with a '#' character, ignore | |
242 | the line. | |
243 | .ie n .IP "\(bu ""bang""" 4 | |
244 | .el .IP "\(bu \f(CWbang\fR" 4 | |
245 | .IX Item "bang" | |
246 | If the first word of the input line begins with a '!' character, send | |
247 | everything after the '!' to \fIsystem()\fR. | |
248 | .ie n .IP "\(bu ""perl""" 4 | |
249 | .el .IP "\(bu \f(CWperl\fR" 4 | |
250 | .IX Item "perl" | |
251 | If the line begins with 'p!', send the everything after the '!' to the | |
252 | perl interpreter unchanged. | |
253 | .ie n .IP "\(bu ""brace""" 4 | |
254 | .el .IP "\(bu \f(CWbrace\fR" 4 | |
255 | .IX Item "brace" | |
256 | If the first word of the input line begins with a '{' character, | |
257 | evaluate the entire line as a Perl expression (including the brace). | |
258 | .ie n .IP "\(bu ""built_in""" 4 | |
259 | .el .IP "\(bu \f(CWbuilt_in\fR" 4 | |
260 | .IX Item "built_in" | |
261 | If the first word of the input line matches a \fBpsh\fR \*(L"built\-in\*(R" | |
262 | function, call the subroutine associated with that built\-in; the | |
263 | subroutine receives a single argument, which is the remainder of the | |
264 | input line exactly as entered. | |
265 | .ie n .IP "\(bu ""perlfunc""" 4 | |
266 | .el .IP "\(bu \f(CWperlfunc\fR" 4 | |
267 | .IX Item "perlfunc" | |
268 | If the first word of the input line matches the name of a defined | |
269 | Perl subroutine \- or \- if \f(CW$Psh::Strategy::Perlfunc::builtins\fR is set a built-in | |
270 | Perl function (as determined by the \f(CW%Psh::Strategy::Perlfunc::perl_builtins\fR hash), | |
271 | pass the line to eval. If \f(CW$Psh::Strategy::Perlfunc::expand_arguments\fR is | |
272 | true and the line | |
273 | contains no parens, or braces or commas (except for {a,b,c} as in | |
274 | shell brace\-expansion), then this strategy tries to | |
275 | interpret the arguments on the command line in a \*(L"shell\-like\*(R" manner: | |
276 | strings are literal except for variable expansion, brace expansion, | |
277 | and glob expansion. | |
278 | .Sp | |
279 | The idea of this strategy is to allow perl functions, especially | |
280 | subroutines in main, to be called like \*(L"ordinary commands\*(R" (i.e., | |
281 | executables on disk). Or put another way, the idea is to replace | |
282 | bash's \*(L"shell function\*(R" capacity with ordinary Perl subroutines. The | |
283 | slogan is, \*(L"If the command line looks like an ordinary shell command, | |
284 | interpret it like one, even if the first word is a Perl subroutine.\*(R" | |
285 | .ie n .IP "\(bu ""auto_resume"" (not enabled by default)" 4 | |
286 | .el .IP "\(bu \f(CWauto_resume\fR (not enabled by default)" 4 | |
287 | .IX Item "auto_resume (not enabled by default)" | |
288 | If the input line matches the name of a stopped job then brings that | |
289 | job to the foreground instead of starting a new programm with that | |
290 | name. | |
291 | .ie n .IP "\(bu ""auto_cd"" (not enabled by default)" 4 | |
292 | .el .IP "\(bu \f(CWauto_cd\fR (not enabled by default)" 4 | |
293 | .IX Item "auto_cd (not enabled by default)" | |
294 | If the input line matches the name of a directory in the current | |
295 | directory, then change to that directory. | |
296 | .ie n .IP "\(bu ""perlscript"" (not enabled by default)" 4 | |
297 | .el .IP "\(bu \f(CWperlscript\fR (not enabled by default)" 4 | |
298 | .IX Item "perlscript (not enabled by default)" | |
299 | If (1) the first word of the input line matches the name of a file found in | |
300 | one of the directories listed in the path (\f(CW$ENV{PATH}\fR), and (2) that file | |
301 | starts with \f(CW\*(C`#!/.../perl\*(C'\fR, and (3) that \f(CW\*(C`perl\*(C'\fR is the | |
302 | same as the Perl under which \fBpsh\fR is running, \fBpsh\fR will fork and run | |
303 | the script using the already-loaded Perl interpreter. The idea is to | |
304 | save the exec half of the fork-exec that the executable strategy would | |
305 | do; typically the exec is more expensive. Right now this strategy can | |
306 | only handle the \fB\-w\fR command-line switch on the \f(CW\*(C`#!\*(C'\fR line. Note this | |
307 | strategy only makes sense before the \*(L"executable\*(R" strategy; if it came | |
308 | after, it could never trigger. | |
309 | .ie n .IP "\(bu ""executable""" 4 | |
310 | .el .IP "\(bu \f(CWexecutable\fR" 4 | |
311 | .IX Item "executable" | |
312 | If the first word of the input line matches the name of an executable | |
313 | file in the path given by \f(CW$ENV{PATH}\fR, then pass the line to | |
314 | system. Perl variable substitution will be done on the line first if | |
315 | the \f(CW$Psh::executable_expand_arguments\fR configuration variable is | |
316 | true and the binary which is executed does not match one of the | |
317 | regular expresions in \f(CW@Psh::executable_noexpand\fR | |
318 | .ie n .IP "\(bu ""fallback_builtin""" 4 | |
319 | .el .IP "\(bu \f(CWfallback_builtin\fR" 4 | |
320 | .IX Item "fallback_builtin" | |
321 | If the first word of the input line is a \*(L"fallback builtin\*(R" provided | |
322 | for operating systems that do not have common binaries \*(-- such as | |
323 | \&\*(L"ls\*(R", \*(L"env\*(R", etc, then call the associated subroutine like an ordinary | |
324 | builtin. If you want all of these commands to be executed within the | |
325 | shell, you can move this strategy ahead of executable. | |
326 | .ie n .IP "\(bu ""eval""" 4 | |
327 | .el .IP "\(bu \f(CWeval\fR" 4 | |
328 | .IX Item "eval" | |
329 | Pass the line to eval, regardless of any condition. This is a catch-all | |
330 | strategy; strategies placed after it will never be triggered. | |
331 | .Sh "\s-1GLOBBING\s0" | |
332 | .IX Subsection "GLOBBING" | |
333 | Globbing is used to expand filenames against patterns. Perl Shell | |
334 | understands the sh '*' and '?' globbing characters (where * matches | |
335 | any string and ? matches exactly one character). | |
336 | .PP | |
337 | In addition, Perl Shell knows the very powerful '**' globbing, | |
338 | replacing many \f(CW\*(C`find\*(C'\fRs in your daily work. '**' will be replaced | |
339 | by 'current directories and all sub directories'. For example: | |
340 | .PP | |
341 | .Vb 1 | |
342 | \& grep foo lib/**/*.pm | |
343 | .Ve | |
344 | .PP | |
345 | will search for foo in all *.pm files which are somewhere | |
346 | (recursivly) within the lib directory. | |
347 | .Sh "\s-1REDIRECTS\s0" | |
348 | .IX Subsection "REDIRECTS" | |
349 | The standard output may be redirected to a file with | |
350 | .PP | |
351 | .Vb 1 | |
352 | \& command > file | |
353 | .Ve | |
354 | .PP | |
355 | and the standard input may be taken from a file with | |
356 | .PP | |
357 | .Vb 1 | |
358 | \& command < file | |
359 | .Ve | |
360 | .PP | |
361 | File descriptors other than 0 and 1 may be specified in an rc-like | |
362 | syntax. | |
363 | .PP | |
364 | To redirect standard error to a file use: | |
365 | .PP | |
366 | .Vb 1 | |
367 | \& command >[2] file | |
368 | .Ve | |
369 | .PP | |
370 | (this is 'command 2> file' in sh\-derivatives! sh-syntax is not | |
371 | supported) | |
372 | .PP | |
373 | To redirect both, standard output and standard error use: | |
374 | .PP | |
375 | .Vb 1 | |
376 | \& command >[all] file | |
377 | .Ve | |
378 | .PP | |
379 | It's also possible to redirect to opened Perl filehandles. If you e.g. | |
380 | opened a handle \*(L"\s-1FOO\s0\*(R" for writing you may use: | |
381 | .PP | |
382 | .Vb 1 | |
383 | \& command >[=FOO] | |
384 | .Ve | |
385 | .PP | |
386 | to write to that filehandle. | |
387 | .Sh "\s-1PIPELINES\s0" | |
388 | .IX Subsection "PIPELINES" | |
389 | Pipelines are used to construct processing chains. | |
390 | .PP | |
391 | .Vb 1 | |
392 | \& cat a.txt b.txt | wc -l | |
393 | .Ve | |
394 | .PP | |
395 | This is the same as in other shells \- standard output of the first | |
396 | command will be standard input of the second command. | |
397 | .PP | |
398 | To redirect different file descriptors, use e.g. | |
399 | .PP | |
400 | .Vb 1 | |
401 | \& command |[5] command2 | |
402 | .Ve | |
403 | .PP | |
404 | to redirect file descriptor 5 to standard input of command. | |
405 | .PP | |
406 | It is also possible to redirect to a different filedescriptor than | |
407 | standard input for the right-hand command: | |
408 | .PP | |
409 | .Vb 1 | |
410 | \& command |[1=5] command2 | |
411 | .Ve | |
412 | .PP | |
413 | will redirect standard output from the first command to a newly opened | |
414 | stream on file descriptor 5 for command. Thus, 'command | command' is | |
415 | only a short hand version of 'command |[1=0] command'. | |
416 | .PP | |
417 | An alias is provided for piping standard error and standard output at | |
418 | the same time: | |
419 | .PP | |
420 | .Vb 1 | |
421 | \& command |[all] command2 | |
422 | .Ve | |
423 | .PP | |
424 | will pipe both to command2 and is so an easier to remember version of | |
425 | .PP | |
426 | .Vb 1 | |
427 | \& command >[2=1] | command2 | |
428 | .Ve | |
429 | .Sh "\s-1MANIFEST\s0 \s-1FILTERS\s0" | |
430 | .IX Subsection "MANIFEST FILTERS" | |
431 | A manifest filter is a chunk of code that causes the creation of a | |
432 | filter process. They are handy for creating simple one-time filters | |
433 | because they don't require creating a program file, setting permissions | |
434 | and so on. | |
435 | .PP | |
436 | There are three kinds of manifest filters: quick, grep and substitution. | |
437 | .PP | |
438 | A quick filter consists of a block of code surrounded by curly braces, | |
439 | with a trailing '\f(CW\*(C`q\*(C'\fR' modifier. The Perl Shell turns this into a line-by-line | |
440 | filter. For the code in the braces, \f(CW$_\fR will contain the line as it was | |
441 | read from input (including any end-of-line character). The filter block | |
442 | should | |
443 | .PP | |
444 | .Vb 1 | |
445 | \& ls | { print ++$i, ": $_"; }q | |
446 | .Ve | |
447 | .PP | |
448 | A grep filter consists of a block of code surrounded by curly braces, | |
449 | with a trailing '\f(CW\*(C`g\*(C'\fR' modifier. The Perl Shell turns this into a line-by-line | |
450 | filter. Only those lines for which the code in the braces returns a true | |
451 | value will be printed. For the code in the braces, \f(CW@_\fR will contain the | |
452 | results of splitting \f(CW$_\fR with the pattern \f(CW\*(C`\es+\*(C'\fR. | |
453 | .PP | |
454 | .Vb 1 | |
455 | \& netstat | { $_[1]>2; }g | |
456 | .Ve | |
457 | .PP | |
458 | A substitution filter consists of a perl-style s/// operator instance. | |
459 | The Perl Shell will turn this into a line-by-line filter that performs the | |
460 | substitution on each line, and then prints the line. For example: | |
461 | .PP | |
462 | .Vb 1 | |
463 | \& ls | s/a/b/ | |
464 | .Ve | |
465 | .PP | |
466 | A substitution filter is logically equivalent to a block filter containing | |
467 | the substitution and a statement to print the resulting line. The example | |
468 | above is equivalent to: | |
469 | .PP | |
470 | .Vb 1 | |
471 | \& ls | { s/a/b/; print; }q | |
472 | .Ve | |
473 | .Sh "BUILT-IN \s-1FUNCTIONS\s0" | |
474 | .IX Subsection "BUILT-IN FUNCTIONS" | |
475 | A list of built in functions is available from within \f(CW\*(C`psh\*(C'\fR using | |
476 | the \*(L"help\*(R" command. | |
477 | .PP | |
478 | For details about the implementation of built\-ins, please see the | |
479 | \&\fBpshdevel\fR manpage. | |
480 | .Sh "\s-1PSH\s0 \s-1FUNCTIONS\s0" | |
481 | .IX Subsection "PSH FUNCTIONS" | |
482 | .ie n .IP "&Psh::evl" 4 | |
483 | .el .IP "\f(CW&Psh::evl\fR" 4 | |
484 | .IX Item "&Psh::evl" | |
485 | This function takes a string, evaluates it as if it were a line of | |
486 | \&\fBpsh\fR input, and returns the value. Useful in loops like: | |
487 | .Sp | |
488 | .Vb 1 | |
489 | \& C<psh$ for $file (glob $pat) { Psh::evl("ls -ld $file"); }> | |
490 | .Ve | |
491 | .ie n .IP "&Psh::is_number" 4 | |
492 | .el .IP "\f(CW&Psh::is_number\fR" 4 | |
493 | .IX Item "&Psh::is_number" | |
494 | Returns true if its first argument is a number. Intended for use in | |
495 | filter subroutines placed in \f(CW$Psh::echo\fR. For example, | |
496 | \&\f(CW\*(C`$Psh::echo = \e&Psh::is_number;\*(C'\fR will cause only numeric return | |
497 | values to be printed. | |
498 | .ie n .IP """&Psh::Util::print_debug, print_error, print_out, print_warning""" 4 | |
499 | .el .IP "\f(CW&Psh::Util::print_debug, print_error, print_out, print_warning\fR" 4 | |
500 | .IX Item "&Psh::Util::print_debug, print_error, print_out, print_warning" | |
501 | These four functions are called whenever \fBpsh\fR wants to produce \fB\-d\fR\-mode | |
502 | output, error messages, normal output, and warnings, | |
503 | respectively. They could conceivably be redefined to implement logging | |
504 | or similar facilities. | |
505 | .PP | |
506 | There are other functions in the Psh:: package, but they are probably | |
507 | not useful except internally to \fBpsh\fR. | |
508 | .SH "LIMITATIONS" | |
509 | .IX Header "LIMITATIONS" | |
510 | Due to limitations of the Win32 type of operating system there's no | |
511 | job control available on those systems. | |
512 | .PP | |
513 | The loop inside \fBpsh\fR will clobber \fI$1\fR and other Perl-builtin variables | |
514 | because it uses matches to implement some of its special | |
515 | functions. | |
516 | .PP | |
517 | Right now, job control simply assumes that the \s-1POSIX\s0 interface is | |
518 | fully implemented. There should be a way to turn job control off if | |
519 | this is not the case. | |
520 | .PP | |
521 | The \*(L"exit status\*(R" of programs invoked in the foreground by the | |
522 | \&\*(L"executable\*(R" strategy (or even the \*(L"bang\*(R" strategy) isn't available | |
523 | from within \fBpsh\fR. | |
524 | .PP | |
525 | Note that since expressions like 'use foo' return undef when sent to | |
526 | \&\fIeval()\fR, it is not possible to use that return value as indication of | |
527 | an error. Instead, we use the heuristic that there was no error unless | |
528 | the special Perl variable '$@' is non\-empty. Note that the side | |
529 | effects of 'use foo' as a \fBpsh\fR command line appear to be exactly as | |
530 | expected. | |
531 | .SH "REQUIREMENTS" | |
532 | .IX Header "REQUIREMENTS" | |
533 | psh needs several optional Perl modules to offer full functionality: | |
534 | .IP "Term::ReadLine::Gnu or Term::ReadLine::Perl for readline support (command history, special editing chars etc.)." 4 | |
535 | .IX Item "Term::ReadLine::Gnu or Term::ReadLine::Perl for readline support (command history, special editing chars etc.)." | |
536 | .PD 0 | |
537 | .IP "Term::Size or Term::ReadKey to offer the ability to change the environment variables \s-1LINES\s0 and \s-1COLUMNS\s0 when the terminal window size changes while running as standard shell" 4 | |
538 | .IX Item "Term::Size or Term::ReadKey to offer the ability to change the environment variables LINES and COLUMNS when the terminal window size changes while running as standard shell" | |
539 | .IP "BSD::Resource is necessary for the ulimit builtin" 4 | |
540 | .IX Item "BSD::Resource is necessary for the ulimit builtin" | |
541 | .PD | |
542 | .SH "OTHER PERL SHELLS" | |
543 | .IX Header "OTHER PERL SHELLS" | |
544 | .Sh "Larry Walls' Perl Shell" | |
545 | .IX Subsection "Larry Walls' Perl Shell" | |
546 | Larry Wall exhibits the simple Perl shell \f(CW\*(C`while (<>) { eval; print $@; }\*(C'\fR on | |
547 | page 161 of the Camel Book (2nd Edition). | |
548 | .Sh "lpsh" | |
549 | .IX Subsection "lpsh" | |
550 | Lee Eakin <\fIleakin@dfw.nostrum.com\fR> has written the Fancy Poor Man's Perl SHell | |
551 | (called lpsh for Lee's Perl Shell), a simple Perl shell that he has used for a number of | |
552 | years now (it is derived from Larry Wall's Perl Shell). He has added some numeric | |
553 | conversion functions because he often uses it as a calculator. | |
554 | .PP | |
555 | He has placed it on the web at \f(CW\*(C`http://www.dfw.nostrum.com/~leakin/psh\*(C'\fR (for the | |
556 | code) and \f(CW\*(C`http://www.dfw.nostrum.com/~leakin/psh.README\*(C'\fR for a short explanation | |
557 | of the code and a reference to the main Perl Shell site. | |
558 | .Sh "Perl Debugger Shell" | |
559 | .IX Subsection "Perl Debugger Shell" | |
560 | Rich Graves <\fIrcgraves@brandeis.edu\fR> posted a comment to the original | |
561 | psh\-0.001 announcement on \f(CW\*(C`http://freshmeat.net\*(C'\fR, which contained this | |
562 | gem that leverages the Perl debugger: \f(CW\*(C`perl \-d \-e 1\*(C'\fR; | |
563 | .Sh "perlsh" | |
564 | .IX Subsection "perlsh" | |
565 | Hiroo Hayashi <\fIhiroo.hayashi@computer.org\fR> includes \fBperlsh\fR, a | |
566 | ``one\-line perl evaluator with line editing function and variable name | |
567 | completion function'' as an example with his Term::ReadLine::Gnu Perl module. | |
568 | .Sh "\s-1PSH\s0.pm" | |
569 | .IX Subsection "PSH.pm" | |
570 | In an example of convergent evolution, at \f(CW\*(C`http://jenda.krynicky.cz/\*(C'\fR | |
571 | there is a Perl shell module called \fI\s-1PSH\s0.pm\fR which is quite similar | |
572 | to this \fBpsh\fR. It is designed to provide a command line that can be called | |
573 | inside some other program via \f(CW\*(C`PSH::prompt();\*(C'\fR, but a small file | |
574 | \&\fIpsh.pl\fR is also included that uses \s-1PSH\s0 to provide a standalone | |
575 | shell. Perhaps some merger of these efforts would be beneficial to all? | |
576 | .Sh "SoftList" | |
577 | .IX Subsection "SoftList" | |
578 | Some versions of the Perl faq mention an interactive Perl shell called | |
579 | SoftList, which can still be found at | |
580 | \&\f(CW\*(C`http://www.mit.edu/afs/sipb/contrib/perl/SoftList/\*(C'\fR. It predates | |
581 | Term::Readline and was apparently last touched in 1993, so it seems to | |
582 | be obsolescent. | |
583 | .Sh "timtosh" | |
584 | .IX Subsection "timtosh" | |
585 | Tim Newsome, <\fInuisance@cmu.edu\fR>, has developed a shell he calls | |
586 | \&\fBtimtosh\fR (There Is More Than One SHell). Per his web site | |
587 | (\f(CW\*(C`http://www.wiw.org/~drz/timtosh\*(C'\fR), | |
588 | it is a shell written entirely in Perl. The goal is to get a shell which you | |
589 | can extend in Perl and can do some other niceties related to | |
590 | Perl (like perl re file matching). As of 1999\-12\-13 (Perl Shell 0.004 release date), | |
591 | Tim says \fBtimtosh\fR ``is focused quite differently than \fBpsh\fR is, but is currently | |
592 | still waiting for a rewrite of the command line parsing. | |
593 | (It has been for almost a year now)''. | |
594 | .Sh "vbsh" | |
595 | .IX Subsection "vbsh" | |
596 | Tom Christiansen and Nathan Torkington's book \fBPerl Cookbook\fR, published by | |
597 | O'Reilly in 1998 (\s-1ISBN\s0 1\-56592\-243\-3) has \*(L"Example 15\-4. vbsh\*(R" on page 531 for | |
598 | section 15.11 (Editing Input). It stands for Very Bad SHell. | |
599 | .Sh "Comparison of perl shells" | |
600 | .IX Subsection "Comparison of perl shells" | |
601 | As an aid to comparing/contrasting these different shells, here is a | |
602 | brief table indicating whether or not each has certain features. | |
603 | .PP | |
604 | .Vb 7 | |
605 | \& Key to features: | |
606 | \& PE : Perl evaluation of Perl expressions | |
607 | \& SHE: shell-like evaluation of shell-like expressions, including | |
608 | \& 'exec'ing executables searched for in PATH | |
609 | \& CLE: command-line editing | |
610 | \& JC : job control | |
611 | \& PL : pipelines | |
612 | .Ve | |
613 | .PP | |
614 | .Vb 4 | |
615 | \& Key to symbols: | |
616 | \& * : feature present | |
617 | \& - : feature absent | |
618 | \& ? : don't know | |
619 | .Ve | |
620 | .PP | |
621 | .Vb 1 | |
622 | \& The shells: | |
623 | .Ve | |
624 | .PP | |
625 | .Vb 1 | |
626 | \& Shell Name PE SHE CLE JC PL | |
627 | .Ve | |
628 | .PP | |
629 | .Vb 9 | |
630 | \& psh (this one) * * * * * | |
631 | \& Larry Wall shell * - - - - | |
632 | \& lpsh * - * - - | |
633 | \& Perl debugger shell * - * - - | |
634 | \& perlsh * - * - - | |
635 | \& Krynicky PSH.pm * * ? - ? | |
636 | \& SoftList * ? * ? ? | |
637 | \& timtosh - * * * * | |
638 | \& vbsh ? ? ? ? - | |
639 | .Ve | |
640 | .SH "FILES" | |
641 | .IX Header "FILES" | |
642 | \&\fIpsh\fR \- The Perl Shell executable script. | |
643 | .PP | |
644 | \&\fI.pshrc\fR \- The user's Perl Shell `profile'. May be in \f(CW$HOME\fR or the | |
645 | current directory; if both are present, both will be read in the order | |
646 | mentioned. | |
647 | .SH "COPYRIGHT" | |
648 | .IX Header "COPYRIGHT" | |
649 | Copyright (C) 1999\-2003 Gregor N. Purdy. All rights reserved. | |
650 | This script is free software. It may be copied or modified according | |
651 | to the same terms as Perl itself. | |
652 | .PP | |
653 | .Vb 1 | |
654 | \& E<lt>F<gregor@focusresearch.com>E<gt> | |
655 | .Ve | |
656 | .SH "CREDITS" | |
657 | .IX Header "CREDITS" | |
658 | The following people have contributed to the development of \f(CW\*(C`psh\*(C'\fR: | |
659 | .IP "Prodigious Contributors" 4 | |
660 | .IX Item "Prodigious Contributors" | |
661 | Markus Peter <\fIwarp@spin.de\fR> added job and signal handling, | |
662 | globbing, redirection, pipelines, parts of completion code, Win32 port, | |
663 | i18n code, some bash compatibility builtins and environment variables | |
664 | and some more minor updates. | |
665 | .Sp | |
666 | Glen Whitney <\fIgwhitney@post.harvard.edu\fR> added evaluation | |
667 | strategies, improved interrupt/job handling, \f(CW&Psh::evl\fR, \f(CW$Psh::echo\fR, | |
668 | more extensive documentation, and other more minor features. | |
669 | .Sp | |
670 | Omer Shenker <\fIoshenker@iname.com\fR> added file locking, Win32 | |
671 | code, login shell handling, various bits of documentation, and other minor | |
672 | features and updates. | |
673 | .Sp | |
674 | Hiroo Hayashi <\fIhiroo.hayashi@computer.org\fR> added the current, | |
675 | bash compatible support for programmable completions and some small fixes. | |
676 | We also have to thank him for the existence of the Term::ReadLine::Gnu module. | |
677 | .IP "ReadLine Support" 4 | |
678 | .IX Item "ReadLine Support" | |
679 | Code examples showing how to apply the Term::ReadLine package were contributed | |
680 | by Billy Naylor <\fIbilly.naylor@eu.net\fR> (in his \f(CW\*(C`pash.pl\*(C'\fR program, | |
681 | which is his own Perl shell). | |
682 | .IP "Symbol Table Dumping" 4 | |
683 | .IX Item "Symbol Table Dumping" | |
684 | Billy Naylor <\fIbilly.naylor@eu.net\fR> also had an example of a symbol | |
685 | table printing function that was used as the starting point for the \f(CW\*(C`psh\*(C'\fR | |
686 | function \f(CW\*(C`psh::symbols()\*(C'\fR. The \f(CW\*(C`psh\*(C'\fR version adds the ability to specify a | |
687 | package name, and it also filters out some special variables. The implementation | |
688 | technique is also different from Billy's. | |
689 | .IP "Prompt String Variables" 4 | |
690 | .IX Item "Prompt String Variables" | |
691 | Matthew D. Allen <\fIs2mdalle@titan.vcu.edu\fR> contributed an enhanced | |
692 | prompt string handling routine that emulates the \f(CW\*(C`bash\*(C'\fR prompt variables. This | |
693 | was expanded into the form now present. | |
694 | .IP "Typo Spotting" 4 | |
695 | .IX Item "Typo Spotting" | |
696 | Allan Kelly <\fIakelly@holyrood.ed.ac.uk\fR> found some problems with the | |
697 | generated documentation. |