Debian Codegraph @

README

raw
1 NAME
2
3 Shell::Config::Generate - Portably generate config for any shell
4
5 VERSION
6
7 version 0.34
8
9 SYNOPSIS
10
11 With this start up:
12
13 use Shell::Guess;
14 use Shell::Config::Generate;
15
16 my $config = Shell::Config::Generate->new;
17 $config->comment( 'this is my config file' );
18 $config->set( FOO => 'bar' );
19 $config->set_path(
20 PERL5LIB => '/foo/bar/lib/perl5',
21 '/foo/bar/lib/perl5/perl5/site',
22 );
23 $config->append_path(
24 PATH => '/foo/bar/bin',
25 '/bar/foo/bin',
26 );
27
28 This:
29
30 $config->generate_file(Shell::Guess->bourne_shell, 'config.sh');
31
32 will generate a config.sh file with this:
33
34 # this is my config file
35 FOO='bar';
36 export FOO;
37 PERL5LIB='/foo/bar/lib/perl5:/foo/bar/lib/perl5/perl5/site';
38 export PERL5LIB;
39 if [ -n "$PATH" ] ; then
40 PATH=$PATH:'/foo/bar/bin:/bar/foo/bin';
41 export PATH
42 else
43 PATH='/foo/bar/bin:/bar/foo/bin';
44 export PATH;
45 fi;
46
47 and this:
48
49 $config->generate_file(Shell::Guess->c_shell, 'config.csh');
50
51 will generate a config.csh with this:
52
53 # this is my config file
54 setenv FOO 'bar';
55 setenv PERL5LIB '/foo/bar/lib/perl5:/foo/bar/lib/perl5/perl5/site';
56 test "$?PATH" = 0 && setenv PATH '/foo/bar/bin:/bar/foo/bin' || setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin';
57
58 and this:
59
60 $config->generate_file(Shell::Guess->cmd_shell, 'config.cmd');
61
62 will generate a config.cmd (Windows cmd.exe script) with this:
63
64 rem this is my config file
65 set FOO=bar
66 set PERL5LIB=/foo/bar/lib/perl5;/foo/bar/lib/perl5/perl5/site
67 if defined PATH (set PATH=%PATH%;/foo/bar/bin;/bar/foo/bin) else (set PATH=/foo/bar/bin;/bar/foo/bin)
68
69 DESCRIPTION
70
71 This module provides an interface for specifying shell configurations
72 for different shell environments without having to worry about the
73 arcane differences between shells such as csh, sh, cmd.exe and
74 command.com.
75
76 It does not modify the current environment, but it can be used to
77 create shell configurations which do modify the environment.
78
79 This module uses Shell::Guess to represent the different types of
80 shells that are supported. In this way you can statically specify just
81 one or more shells:
82
83 #!/usr/bin/perl
84 use Shell::Guess;
85 use Shell::Config::Generate;
86 my $config = Shell::Config::Generate->new;
87 # ... config config ...
88 $config->generate_file(Shell::Guess->bourne_shell, 'foo.sh' );
89 $config->generate_file(Shell::Guess->c_shell, 'foo.csh');
90 $config->generate_file(Shell::Guess->cmd_shell, 'foo.cmd');
91 $config->generate_file(Shell::Guess->command_shell, 'foo.bat');
92
93 This will create foo.sh and foo.csh versions of the configurations,
94 which can be sourced like so:
95
96 #!/bin/sh
97 . ./foo.sh
98
99 or
100
101 #!/bin/csh
102 source foo.csh
103
104 It also creates .cmd and .bat files with the same configuration which
105 can be used in Windows. The configuration can be imported back into
106 your shell by simply executing these files:
107
108 C:\> foo.cmd
109
110 or
111
112 C:\> foo.bat
113
114 Alternatively you can use the shell that called your Perl script using
115 Shell::Guess's running_shell method, and write the output to standard
116 out.
117
118 #!/usr/bin/perl
119 use Shell::Guess;
120 use Shell::Config::Generate;
121 my $config = Shell::Config::Generate->new;
122 # ... config config ...
123 print $config->generate(Shell::Guess->running_shell);
124
125 If you use this pattern, you can eval the output of your script using
126 your shell's back ticks to import the configuration into the shell.
127
128 #!/bin/sh
129 eval `script.pl`
130
131 or
132
133 #!/bin/csh
134 eval `script.pl`
135
136 CONSTRUCTOR
137
138 new
139
140 my $config = Shell::Config::Generate->new;
141
142 creates an instance of She::Config::Generate.
143
144 METHODS
145
146 There are two types of instance methods for this class:
147
148 * modifiers
149
150 adjust the configuration in an internal portable format
151
152 * generators
153
154 generate shell configuration in a specific format given the internal
155 portable format stored inside the instance.
156
157 The idea is that you can create multiple modifications to the
158 environment without worrying about specific shells, then when you are
159 done you can create shell specific versions of those modifications
160 using the generators.
161
162 This may be useful for system administrators that must support users
163 that use different shells, with a single configuration generation
164 script written in Perl.
165
166 set
167
168 $config->set( $name => $value );
169
170 Set an environment variable.
171
172 set_path
173
174 $config->set_path( $name => @values );
175
176 Sets an environment variable which is stored in standard 'path' format
177 (Like PATH or PERL5LIB). In UNIX land this is a colon separated list
178 stored as a string. In Windows this is a semicolon separated list
179 stored as a string. You can do the same thing using the set method, but
180 if you do so you have to determine the correct separator.
181
182 This will replace the existing path value if it already exists.
183
184 append_path
185
186 $config->append_path( $name => @values );
187
188 Appends to an environment variable which is stored in standard 'path'
189 format. This will create a new environment variable if it doesn't
190 already exist, or add to an existing value.
191
192 prepend_path
193
194 $config->prepend_path( $name => @values );
195
196 Prepend to an environment variable which is stored in standard 'path'
197 format. This will create a new environment variable if it doesn't
198 already exist, or add to an existing value.
199
200 comment
201
202 $config->comment( $comment );
203
204 This will generate a comment in the appropriate format.
205
206 note that including comments in your configuration may mean it will not
207 work with the eval backticks method for importing configurations into
208 your shell.
209
210 shebang
211
212 $config->shebang;
213 $config->shebang($location);
214
215 This will generate a shebang at the beginning of the configuration,
216 making it appropriate for use as a script. For non UNIX shells this
217 will be ignored. If specified, $location will be used as the
218 interpreter location. If it is not specified, then the default location
219 for the shell will be used.
220
221 note that the shebang in your configuration may mean it will not work
222 with the eval backticks method for importing configurations into your
223 shell.
224
225 echo_off
226
227 $config->echo_off;
228
229 For DOS/Windows configurations (command.com or cmd.exe), issue this as
230 the first line of the config:
231
232 @echo off
233
234 echo_on
235
236 $config->echo_on;
237
238 Turn off the echo off (that is do not put anything at the beginning of
239 the config) for DOS/Windows configurations (command.com or cmd.exe).
240
241 set_alias
242
243 $config->set_alias( $alias => $command )
244
245 Sets the given alias to the given command.
246
247 Caveat: some older shells do not support aliases, such as the original
248 bourne shell. This module will generate aliases for those shells
249 anyway, since /bin/sh may actually be a more modern shell that DOES
250 support aliases, so do not use this method unless you can be reasonable
251 sure that the shell you are generating supports aliases. On Windows,
252 for PowerShell, a simple function is used instead of an alias so that
253 arguments may be specified.
254
255 set_path_sep
256
257 $config->set_path_sep( $sep );
258
259 Use $sep as the path separator instead of the shell default path
260 separator (generally : for Unix shells and ; for Windows shells).
261
262 Not all characters are supported, it is usually best to stick with the
263 shell default or to use : or ;.
264
265 generate
266
267 my $command_text = $config->generate;
268 my $command_text = $config->generate( $shell );
269
270 Generate shell configuration code for the given shell. $shell is an
271 instance of Shell::Guess. If $shell is not provided, then this method
272 will use Shell::Guess to guess the shell that called your perl script.
273
274 You can also pass in the shell name as a string for $shell. This should
275 correspond to the appropriate name_shell from Shell::Guess. So for csh
276 you would pass in "c" and for tcsh you would pass in "tc", etc.
277
278 generate_file
279
280 $config->generate_file( $shell, $filename );
281
282 Generate shell configuration code for the given shell and write it to
283 the given file. $shell is an instance of Shell::Guess. If there is an
284 IO error it will throw an exception.
285
286 FUNCTIONS
287
288 win32_space_be_gone
289
290 my @new_path_list = win32_space_be_gone( @orig_path_list );
291
292 On MSWin32 and cygwin:
293
294 Given a list of directory paths (or filenames), this will return an
295 equivalent list of paths pointing to the same file system objects
296 without spaces. To do this Win32::GetShortPathName() is used on to find
297 alternative path names without spaces.
298
299 NOTE that this breaks when Windows is told not to create short (8+3)
300 filenames; see http://www.perlmonks.org/?node_id=333930 for a
301 discussion of this behaviour.
302
303 In addition, on just Cygwin:
304
305 The input paths are first converted from POSIX to Windows paths using
306 Cygwin::posix_to_win_path, and then converted back to POSIX paths using
307 Cygwin::win_to_posix_path.
308
309 Elsewhere:
310
311 Returns the same list passed into it
312
313 cmd_escape_path
314
315 my @new_path_list = cmd_escape_path( @orig_path_list )
316
317 Given a list of directory paths (or filenames), this will return an
318 equivalent list of paths escaped for cmd.exe and command.com.
319
320 powershell_escape_path
321
322 my @new_path_list = powershell_escape_path( @orig_path_list )
323
324 Given a list of directory paths (or filenames), this will return an
325 equivalent list of paths escaped for PowerShell.
326
327 CAVEATS
328
329 The test suite tests this module's output against the actual shells
330 that should understand them, if they can be found in the path. You can
331 generate configurations for shells which are not available (for example
332 cmd.exe configurations from UNIX or bourne configurations under
333 windows), but the test suite only tests them if they are found during
334 the build of this module.
335
336 The implementation for csh depends on the external command test. As far
337 as I can tell test should be available on all modern flavors of UNIX
338 which are using csh. If anyone can figure out how to prepend or append
339 to path type environment variable without an external command in csh,
340 then a patch would be appreciated.
341
342 The incantation for prepending and appending elements to a path on csh
343 probably deserve a comment here. It looks like this:
344
345 test "$?PATH" = 0 && setenv PATH '/foo/bar/bin:/bar/foo/bin' || setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin';
346
347 * one line
348
349 The command is all on one line, and doesn't use if, which is probably
350 more clear and ideomatic. This for example, might make more sense:
351
352 if ( $?PATH == 0 ) then
353 setenv PATH '/foo/bar/bin:/bar/foo/bin'
354 else
355 setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin'
356 endif
357
358 However, this only works if the code interpreted using the csh source
359 command or is included in a csh script inline. If you try to invoke
360 this code using csh eval then it will helpfully convert it to one
361 line and if does not work under csh in one line.
362
363 There are probably more clever or prettier ways to append/prepend path
364 environment variables as I am not a shell programmer. Patches welcome.
365
366 Only UNIX (bourne, bash, csh, ksh, fish and their derivatives) and
367 Windows (command.com, cmd.exe and PowerShell) are supported so far.
368
369 Fish shell support should be considered a tech preview. The Fish shell
370 itself is somewhat in flux, and thus some tests are skipped for the
371 Fish shell since behavior is different for different versions. In
372 particular, new lines in environment variables may not work on newer
373 versions.
374
375 Patches welcome for your favorite shell / operating system.
376
377 AUTHOR
378
379 Author: Graham Ollis <[email protected]>
380
381 Contributors:
382
383 Brad Macpherson (BRAD, brad-mac)
384
385 mohawk
386
387 COPYRIGHT AND LICENSE
388
389 This software is copyright (c) 2017 by Graham Ollis.
390
391 This is free software; you can redistribute it and/or modify it under
392 the same terms as the Perl 5 programming language system itself.
393