Debian Codegraph @

README

raw
1 NAME
2
3 Shell::Guess - Make an educated guess about the shell in use
4
5 VERSION
6
7 version 0.10
8
9 SYNOPSIS
10
11 guessing shell which called the Perl script:
12
13 use Shell::Guess;
14 my $shell = Shell::Guess->running_shell;
15 if($shell->is_c) {
16 print "setenv FOO bar\n";
17 } elsif($shell->is_bourne) {
18 print "export FOO=bar\n";
19 }
20
21 guessing the current user's login shell:
22
23 use Shell::Guess;
24 my $shell = Shell::Guess->login_shell;
25 print $shell->name, "\n";
26
27 guessing an arbitrary user's login shell:
28
29 use Shell::Guess;
30 my $shell = Shell::Guess->login_shell('bob');
31 print $shell->name, "\n";
32
33 DESCRIPTION
34
35 Shell::Guess makes a reasonably aggressive attempt to determine the
36 shell being employed by the user, either the shell that executed the
37 perl script directly (the "running" shell), or the users' login shell
38 (the "login" shell). It does this by a variety of means available to
39 it, depending on the platform that it is running on.
40
41 * getpwent
42
43 On UNIXy systems with getpwent, that can be used to determine the
44 login shell.
45
46 * dscl
47
48 Under Mac OS X getpwent will typically not provide any useful
49 information, so the dscl command is used instead.
50
51 * proc file systems
52
53 On UNIXy systems with a proc filesystems (such as Linux),
54 Shell::Guess will attempt to use that to determine the running shell.
55
56 * ps
57
58 On UNIXy systems without a proc filesystem, Shell::Guess will use the
59 ps command to determine the running shell.
60
61 * Win32::Getppid and Win32::Process::List
62
63 On Windows if these modules are installed they will be used to
64 determine the running shell. This method can differentiate between
65 PowerShell, command.com and cmd.exe.
66
67 * ComSpec
68
69 If the above method is inconclusive, the ComSpec environment variable
70 will be consulted to differentiate between command.com or cmd.exe
71 (PowerShell cannot be detected in this manner).
72
73 * reasonable defaults
74
75 If the running or login shell cannot be otherwise determined, a
76 reasonable default for your platform will be used as a fallback.
77 Under OpenVMS this is dcl, Windows 95/98 and MS-DOS this is
78 command.com and Windows NT/2000/XP/Vista/7 this is cmd.exe. UNIXy
79 platforms fallback to bourne shell.
80
81 The intended use of this module is to enable a Perl developer to write
82 a script that generates shell configurations for the calling shell so
83 they can be imported back into the calling shell using eval and
84 backticks or source. For example, if your script looks like this:
85
86 #!/usr/bin/perl
87 use Shell::Guess;
88 my $shell = Shell::Guess->running_shell;
89 if($shell->is_bourne) {
90 print "export FOO=bar\n";
91 } else($shell->is_c) {
92 print "setenv FOO bar\n";
93 } else {
94 die "I don't support ", $shell->name, " shell";
95 }
96
97 You can then import FOO into your bash or c shell like this:
98
99 % eval `perl script.pl`
100
101 or, you can write the output to a configuration file and source it:
102
103 % perl script.pl > foo.sh
104 % source foo.sh
105
106 Shell::Config::Generate provides a portable interface for generating
107 such shell configurations, and is designed to work with this module.
108
109 CLASS METHODS
110
111 These class methods return an instance of Shell::Guess, which can then
112 be interrogated by the instance methods in the next section below.
113
114 running_shell
115
116 my $shell = Shell::Guess->running_shell;
117
118 Returns an instance of Shell::Guess based on the shell which directly
119 started the current Perl script. If the running shell cannot be
120 determined, it will return the login shell.
121
122 login_shell
123
124 my $shell = Shell::Guess->login_shell;
125 my $shell = Shell::Guess->login_shell( $username )
126
127 Returns an instance of Shell::Guess for the given user. If no username
128 is specified then the current user will be used. If no shell can be
129 guessed then a reasonable fallback will be chosen based on your
130 platform.
131
132 bash_shell
133
134 my $shell = Shell::Guess->bash_shell;
135
136 Returns an instance of Shell::Guess for bash.
137
138 The following instance methods will return:
139
140 * $shell->name = bash
141
142 * $shell->is_bash = 1
143
144 * $shell->is_bourne = 1
145
146 * $shell->is_unix = 1
147
148 * $shell->default_location = /bin/bash
149
150 All other instance methods will return false
151
152 bourne_shell
153
154 my $shell = Shell::Guess->bourne_shell;
155
156 Returns an instance of Shell::Guess for the bourne shell.
157
158 The following instance methods will return:
159
160 * $shell->name = bourne
161
162 * $shell->is_bourne = 1
163
164 * $shell->is_unix = 1
165
166 * $shell->default_location = /bin/sh
167
168 All other instance methods will return false
169
170 c_shell
171
172 my $shell = Shell::Guess->c_shell;
173
174 Returns an instance of Shell::Guess for c shell.
175
176 The following instance methods will return:
177
178 * $shell->name = c
179
180 * $shell->is_c = 1
181
182 * $shell->is_unix = 1
183
184 * $shell->default_location = /bin/csh
185
186 All other instance methods will return false
187
188 cmd_shell
189
190 my $shell = Shell::Guess->cmd_shell;
191
192 Returns an instance of Shell::Guess for the Windows NT cmd shell
193 (cmd.exe).
194
195 The following instance methods will return:
196
197 * $shell->name = cmd
198
199 * $shell->is_cmd = 1
200
201 * $shell->is_win32 = 1
202
203 * $shell->default_location = C:\Windows\system32\cmd.exe
204
205 All other instance methods will return false
206
207 command_shell
208
209 my $shell = Shell::Guess->command_shell;
210
211 Returns an instance of Shell::Guess for the Windows 95 command shell
212 (command.com).
213
214 The following instance methods will return:
215
216 * $shell->name = command
217
218 * $shell->is_command = 1
219
220 * $shell->is_win32 = 1
221
222 * $shell->default_location = C:\Windows\system32\command.com
223
224 All other instance methods will return false
225
226 dcl_shell
227
228 my $shell = Shell::Guess->dcl_shell;
229
230 Returns an instance of Shell::Guess for the OpenVMS dcl shell.
231
232 The following instance methods will return:
233
234 * $shell->name = dcl
235
236 * $shell->is_dcl = 1
237
238 * $shell->is_vms = 1
239
240 All other instance methods will return false
241
242 fish_shell
243
244 my $shell = Shell::Guess->fish_shell;
245
246 Returns an instance of Shell::Guess for the fish shell.
247
248 The following instance methods will return:
249
250 * $shell->name = fish
251
252 * $shell->is_fish = 1
253
254 * $shell->is_unix = 1
255
256 korn_shell
257
258 my $shell = Shell::Guess->korn_shell;
259
260 Returns an instance of Shell::Guess for the korn shell.
261
262 The following instance methods will return:
263
264 * $shell->name = korn
265
266 * $shell->is_korn = 1
267
268 * $shell->is_bourne = 1
269
270 * $shell->is_unix = 1
271
272 * $shell->default_location = /bin/ksh
273
274 All other instance methods will return false
275
276 power_shell
277
278 my $shell = Shell::Guess->power_shell;
279
280 Returns an instance of Shell::Guess for Microsoft PowerShell (either
281 for Windows powershell.exe or Unix pwsh).
282
283 The following instance methods will return:
284
285 * $shell->name = power
286
287 * $shell->is_power = 1
288
289 * $shell->is_win32 = 1
290
291 All other instance methods will return false
292
293 tc_shell
294
295 my $shell = Shell::Guess->tc_shell;
296
297 Returns an instance of Shell::Guess for tcsh.
298
299 The following instance methods will return:
300
301 * $shell->name = tc
302
303 * $shell->is_tc = 1
304
305 * $shell->is_c = 1
306
307 * $shell->is_unix = 1
308
309 * $shell->default_location = /bin/tcsh
310
311 All other instance methods will return false
312
313 z_shell
314
315 my $shell = Shell::Guess->z_shell
316
317 Returns an instance of Shell::Guess for zsh.
318
319 The following instance methods will return:
320
321 * $shell->name = z
322
323 * $shell->is_z = 1
324
325 * $shell->is_bourne = 1
326
327 * $shell->is_unix = 1
328
329 * $shell->default_location = /bin/zsh
330
331 All other instance methods will return false
332
333 INSTANCE METHODS
334
335 The normal way to call these is by calling them on the result of either
336 running_shell or login_shell, but they can also be called as class
337 methods, in which case the currently running shell will be used, so
338
339 Shell::Guess->is_bourne
340
341 is the same as
342
343 Shell::Guess->running_shell->is_bourne
344
345 is_bash
346
347 my $bool = $shell->is_bash;
348
349 Returns true if the shell is bash.
350
351 is_bourne
352
353 my $bool = $shell->is_bourne;
354
355 Returns true if the shell is the bourne shell, or a shell which
356 supports bourne syntax (e.g. bash or korn).
357
358 is_c
359
360 my $bool = $shell->is_c;
361
362 Returns true if the shell is csh, or a shell which supports csh syntax
363 (e.g. tcsh).
364
365 is_cmd
366
367 my $bool = $shell->is_cmd;
368
369 Returns true if the shell is the Windows command.com shell.
370
371 is_command
372
373 my $bool = $shell->is_command;
374
375 Returns true if the shell is the Windows cmd.com shell.
376
377 is_dcl
378
379 my $bool = $shell->is_dcl;
380
381 Returns true if the shell is the OpenVMS dcl shell.
382
383 is_fish
384
385 my $bool = $shell->is_fish;
386
387 Returns true if the shell is Fish shell.
388
389 is_korn
390
391 my $bool = $shell->is_korn;
392
393 Returns true if the shell is the korn shell.
394
395 is_power
396
397 my $bool = $shell->is_power;
398
399 Returns true if the shell is Windows PowerShell.
400
401 is_tc
402
403 my $bool = $shell->is_tc;
404
405 Returns true if the shell is tcsh.
406
407 is_unix
408
409 my $bool = $shell->is_unix;
410
411 Returns true if the shell is traditionally a UNIX shell (e.g. bourne,
412 bash, korn)
413
414 is_vms
415
416 my $bool = $shell->is_vms;
417
418 Returns true if the shell is traditionally an OpenVMS shell (e.g. dcl)
419
420 is_win32
421
422 my $bool = $shell->is_win32;
423
424 Returns true if the shell is traditionally a Windows shell
425 (command.com, cmd.exe, powershell.exe, pwsh)
426
427 is_z
428
429 my $bool = $shell->is_z;
430
431 Returns true if the shell is zsh
432
433 name
434
435 my $name = $shell->name;
436
437 Returns the name of the shell.
438
439 default_location
440
441 my $location = $shell->default_location;
442
443 The usual location for this shell, for example /bin/sh for bourne shell
444 and /bin/csh for c shell. May not be defined for all shells.
445
446 CAVEATS
447
448 Shell::Guess shouldn't ever die or crash, instead it will attempt to
449 make a guess or use a fallback about either the login or running shell
450 even on unsupported operating systems. The fallback is the most common
451 shell on the particular platform that you are using, so on UNIXy
452 platforms the fallback is bourne, and on OpenVMS the fallback is dcl.
453
454 These are the operating systems that have been tested in development
455 and are most likely to guess reliably.
456
457 * Linux
458
459 * Cygwin
460
461 * FreeBSD
462
463 * Mac OS X
464
465 * Windows (Strawberry Perl)
466
467 * Solaris (x86)
468
469 * MS-DOS (djgpp)
470
471 * OpenVMS
472
473 Always detected as dcl (a more nuanced view of OpenVMS is probably
474 possible, patches welcome).
475
476 UNIXy platforms without a proc filesystem will use Unix::Process if
477 installed, which will execute ps to determine the running shell.
478
479 It is pretty easy to fool the ->running_shell method by using fork, or
480 if your Perl script is not otherwise being directly executed by the
481 shell.
482
483 Patches are welcome to make other platforms work more reliably.
484
485 AUTHOR
486
487 Author: Graham Ollis <[email protected]>
488
489 Contributors:
490
491 Buddy Burden (BAREFOOT)
492
493 Julien Fiegehenn (SIMBABQUE)
494
495 COPYRIGHT AND LICENSE
496
497 This software is copyright (c) 2012-2023 by Graham Ollis.
498
499 This is free software; you can redistribute it and/or modify it under
500 the same terms as the Perl 5 programming language system itself.
501