1Shell::Config::GenerateU(s3e)r Contributed Perl DocumentaSthieolnl::Config::Generate(3)
2
6 Shell::Config::Generate - Portably generate config for any shell
7
9 version 0.34
10
12 With this start up:
13 use Shell::Guess;
15 use Shell::Config::Generate;
16 my $config = Shell::Config::Generate->new;
18 $config->comment( 'this is my config file' );
19 $config->set( FOO => 'bar' );
20 $config->set_path(
21 PERL5LIB => '/foo/bar/lib/perl5',
22 '/foo/bar/lib/perl5/perl5/site',
23 );
24 $config->append_path(
25 PATH => '/foo/bar/bin',
26 '/bar/foo/bin',
27 );
28 This:
30 $config->generate_file(Shell::Guess->bourne_shell, 'config.sh');
32 will generate a config.sh file with this:
34 # this is my config file
36 FOO='bar';
37 export FOO;
38 PERL5LIB='/foo/bar/lib/perl5:/foo/bar/lib/perl5/perl5/site';
39 export PERL5LIB;
40 if [ -n "$PATH" ] ; then
41 PATH=$PATH:'/foo/bar/bin:/bar/foo/bin';
42 export PATH
43 else
44 PATH='/foo/bar/bin:/bar/foo/bin';
45 export PATH;
46 fi;
47 and this:
49 $config->generate_file(Shell::Guess->c_shell, 'config.csh');
51 will generate a config.csh with this:
53 # this is my config file
55 setenv FOO 'bar';
56 setenv PERL5LIB '/foo/bar/lib/perl5:/foo/bar/lib/perl5/perl5/site';
57 test "$?PATH" = 0 && setenv PATH '/foo/bar/bin:/bar/foo/bin' || setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin';
58 and this:
60 $config->generate_file(Shell::Guess->cmd_shell, 'config.cmd');
62 will generate a "config.cmd" (Windows "cmd.exe" script) with this:
64 rem this is my config file
66 set FOO=bar
67 set PERL5LIB=/foo/bar/lib/perl5;/foo/bar/lib/perl5/perl5/site
68 if defined PATH (set PATH=%PATH%;/foo/bar/bin;/bar/foo/bin) else (set PATH=/foo/bar/bin;/bar/foo/bin)
69
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 It does not modify the current environment, but it can be used to
77 create shell configurations which do modify the environment.
78 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 #!/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 This will create foo.sh and foo.csh versions of the configurations,
94 which can be sourced like so:
95 #!/bin/sh
97 . ./foo.sh
98 or
100 #!/bin/csh
102 source foo.csh
103 It also creates ".cmd" and ".bat" files with the same configuration
105 which can be used in Windows. The configuration can be imported back
106 into your shell by simply executing these files:
107 C:\> foo.cmd
109 or
111 C:\> foo.bat
113 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 #!/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 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 #!/bin/sh
129 eval `script.pl`
130 or
132 #!/bin/csh
134 eval `script.pl`
135
137 new
138 my $config = Shell::Config::Generate->new;
139 creates an instance of She::Config::Generate.
141
143 There are two types of instance methods for this class:
144 • modifiers
146 adjust the configuration in an internal portable format
148 • generators
150 generate shell configuration in a specific format given the
152 internal portable format stored inside the instance.
153 The idea is that you can create multiple modifications to the
155 environment without worrying about specific shells, then when you are
156 done you can create shell specific versions of those modifications
157 using the generators.
158 This may be useful for system administrators that must support users
160 that use different shells, with a single configuration generation
161 script written in Perl.
162 set
164 $config->set( $name => $value );
165 Set an environment variable.
167 set_path
169 $config->set_path( $name => @values );
170 Sets an environment variable which is stored in standard 'path' format
172 (Like PATH or PERL5LIB). In UNIX land this is a colon separated list
173 stored as a string. In Windows this is a semicolon separated list
174 stored as a string. You can do the same thing using the "set" method,
175 but if you do so you have to determine the correct separator.
176 This will replace the existing path value if it already exists.
178 append_path
180 $config->append_path( $name => @values );
181 Appends to an environment variable which is stored in standard 'path'
183 format. This will create a new environment variable if it doesn't
184 already exist, or add to an existing value.
185 prepend_path
187 $config->prepend_path( $name => @values );
188 Prepend to an environment variable which is stored in standard 'path'
190 format. This will create a new environment variable if it doesn't
191 already exist, or add to an existing value.
192 comment
194 $config->comment( $comment );
195 This will generate a comment in the appropriate format.
197 note that including comments in your configuration may mean it will not
199 work with the "eval" backticks method for importing configurations into
200 your shell.
201 shebang
203 $config->shebang;
204 $config->shebang($location);
205 This will generate a shebang at the beginning of the configuration,
207 making it appropriate for use as a script. For non UNIX shells this
208 will be ignored. If specified, $location will be used as the
209 interpreter location. If it is not specified, then the default
210 location for the shell will be used.
211 note that the shebang in your configuration may mean it will not work
213 with the "eval" backticks method for importing configurations into your
214 shell.
215 echo_off
217 $config->echo_off;
218 For DOS/Windows configurations ("command.com" or "cmd.exe"), issue this
220 as the first line of the config:
221 @echo off
223 echo_on
225 $config->echo_on;
226 Turn off the echo off (that is do not put anything at the beginning of
228 the config) for DOS/Windows configurations ("command.com" or
229 "cmd.exe").
230 set_alias
232 $config->set_alias( $alias => $command )
233 Sets the given alias to the given command.
235 Caveat: some older shells do not support aliases, such as the original
237 bourne shell. This module will generate aliases for those shells
238 anyway, since /bin/sh may actually be a more modern shell that DOES
239 support aliases, so do not use this method unless you can be reasonable
240 sure that the shell you are generating supports aliases. On Windows,
241 for PowerShell, a simple function is used instead of an alias so that
242 arguments may be specified.
243 set_path_sep
245 $config->set_path_sep( $sep );
246 Use $sep as the path separator instead of the shell default path
248 separator (generally ":" for Unix shells and ";" for Windows shells).
249 Not all characters are supported, it is usually best to stick with the
251 shell default or to use ":" or ";".
252 generate
254 my $command_text = $config->generate;
255 my $command_text = $config->generate( $shell );
256 Generate shell configuration code for the given shell. $shell is an
258 instance of Shell::Guess. If $shell is not provided, then this method
259 will use Shell::Guess to guess the shell that called your perl script.
260 You can also pass in the shell name as a string for $shell. This
262 should correspond to the appropriate name_shell from Shell::Guess. So
263 for csh you would pass in "c" and for tcsh you would pass in "tc", etc.
264 generate_file
266 $config->generate_file( $shell, $filename );
267 Generate shell configuration code for the given shell and write it to
269 the given file. $shell is an instance of Shell::Guess. If there is an
270 IO error it will throw an exception.
271
273 win32_space_be_gone
274 my @new_path_list = win32_space_be_gone( @orig_path_list );
275 On "MSWin32" and "cygwin":
277 Given a list of directory paths (or filenames), this will return an
279 equivalent list of paths pointing to the same file system objects
280 without spaces. To do this Win32::GetShortPathName() is used on to
281 find alternative path names without spaces.
282 NOTE that this breaks when Windows is told not to create short ("8+3")
284 filenames; see <http://www.perlmonks.org/?node_id=333930> for a
285 discussion of this behaviour.
286 In addition, on just "Cygwin":
288 The input paths are first converted from POSIX to Windows paths using
290 "Cygwin::posix_to_win_path", and then converted back to POSIX paths
291 using "Cygwin::win_to_posix_path".
292 Elsewhere:
294 Returns the same list passed into it
296 cmd_escape_path
298 my @new_path_list = cmd_escape_path( @orig_path_list )
299 Given a list of directory paths (or filenames), this will return an
301 equivalent list of paths escaped for cmd.exe and command.com.
302 powershell_escape_path
304 my @new_path_list = powershell_escape_path( @orig_path_list )
305 Given a list of directory paths (or filenames), this will return an
307 equivalent list of paths escaped for PowerShell.
308
310 The test suite tests this module's output against the actual shells
311 that should understand them, if they can be found in the path. You can
312 generate configurations for shells which are not available (for example
313 "cmd.exe" configurations from UNIX or bourne configurations under
314 windows), but the test suite only tests them if they are found during
315 the build of this module.
316 The implementation for "csh" depends on the external command "test".
318 As far as I can tell "test" should be available on all modern flavors
319 of UNIX which are using "csh". If anyone can figure out how to prepend
320 or append to path type environment variable without an external command
321 in "csh", then a patch would be appreciated.
322 The incantation for prepending and appending elements to a path on csh
324 probably deserve a comment here. It looks like this:
325 test "$?PATH" = 0 && setenv PATH '/foo/bar/bin:/bar/foo/bin' || setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin';
327 • one line
329 The command is all on one line, and doesn't use if, which is
331 probably more clear and ideomatic. This for example, might make
332 more sense:
333 if ( $?PATH == 0 ) then
335 setenv PATH '/foo/bar/bin:/bar/foo/bin'
336 else
337 setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin'
338 endif
339 However, this only works if the code interpreted using the csh
341 "source" command or is included in a csh script inline. If you try
342 to invoke this code using csh "eval" then it will helpfully convert
343 it to one line and if does not work under csh in one line.
344 There are probably more clever or prettier ways to append/prepend path
346 environment variables as I am not a shell programmer. Patches welcome.
347 Only UNIX (bourne, bash, csh, ksh, fish and their derivatives) and
349 Windows (command.com, cmd.exe and PowerShell) are supported so far.
350 Fish shell support should be considered a tech preview. The Fish shell
352 itself is somewhat in flux, and thus some tests are skipped for the
353 Fish shell since behavior is different for different versions. In
354 particular, new lines in environment variables may not work on newer
355 versions.
356 Patches welcome for your favorite shell / operating system.
358
360 Author: Graham Ollis <plicease@cpan.org>
361 Contributors:
363 Brad Macpherson (BRAD, brad-mac)
365 mohawk
367
369 This software is copyright (c) 2017 by Graham Ollis.
370 This is free software; you can redistribute it and/or modify it under
372 the same terms as the Perl 5 programming language system itself.
373perl v5.38.0 2023-07-21 Shell::Config::Generate(3)