1Shell::Config::GenerateU(s3e)r Contributed Perl DocumentaSthieolnl::Config::Generate(3)
2
3
4

NAME

6       Shell::Config::Generate - Portably generate config for any shell
7

VERSION

9       version 0.34
10

SYNOPSIS

12       With this start up:
13
14        use Shell::Guess;
15        use Shell::Config::Generate;
16
17        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
29       This:
30
31        $config->generate_file(Shell::Guess->bourne_shell, 'config.sh');
32
33       will generate a config.sh file with this:
34
35        # 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
48       and this:
49
50        $config->generate_file(Shell::Guess->c_shell, 'config.csh');
51
52       will generate a config.csh with this:
53
54        # 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
59       and this:
60
61        $config->generate_file(Shell::Guess->cmd_shell, 'config.cmd');
62
63       will generate a "config.cmd" (Windows "cmd.exe" script) with this:
64
65        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

DESCRIPTION

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
105       which can be used in Windows.  The configuration can be imported back
106       into 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

CONSTRUCTOR

137   new
138        my $config = Shell::Config::Generate->new;
139
140       creates an instance of She::Config::Generate.
141

METHODS

143       There are two types of instance methods for this class:
144
145       •   modifiers
146
147           adjust the configuration in an internal portable format
148
149       •   generators
150
151           generate shell configuration in a specific format given the
152           internal portable format stored inside the instance.
153
154       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
159       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
163   set
164        $config->set( $name => $value );
165
166       Set an environment variable.
167
168   set_path
169        $config->set_path( $name => @values );
170
171       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
177       This will replace the existing path value if it already exists.
178
179   append_path
180        $config->append_path( $name => @values );
181
182       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
186   prepend_path
187        $config->prepend_path( $name => @values );
188
189       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
193   comment
194        $config->comment( $comment );
195
196       This will generate a comment in the appropriate format.
197
198       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
202   shebang
203        $config->shebang;
204        $config->shebang($location);
205
206       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
212       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
216   echo_off
217        $config->echo_off;
218
219       For DOS/Windows configurations ("command.com" or "cmd.exe"), issue this
220       as the first line of the config:
221
222        @echo off
223
224   echo_on
225        $config->echo_on;
226
227       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
231   set_alias
232        $config->set_alias( $alias => $command )
233
234       Sets the given alias to the given command.
235
236       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
244   set_path_sep
245        $config->set_path_sep( $sep );
246
247       Use $sep as the path separator instead of the shell default path
248       separator (generally ":" for Unix shells and ";" for Windows shells).
249
250       Not all characters are supported, it is usually best to stick with the
251       shell default or to use ":" or ";".
252
253   generate
254        my $command_text = $config->generate;
255        my $command_text = $config->generate( $shell );
256
257       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
261       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
265   generate_file
266        $config->generate_file( $shell, $filename );
267
268       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

FUNCTIONS

273   win32_space_be_gone
274        my @new_path_list = win32_space_be_gone( @orig_path_list );
275
276       On "MSWin32" and "cygwin":
277
278       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
283       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
287       In addition, on just "Cygwin":
288
289       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
293       Elsewhere:
294
295       Returns the same list passed into it
296
297   cmd_escape_path
298        my @new_path_list = cmd_escape_path( @orig_path_list )
299
300       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
303   powershell_escape_path
304        my @new_path_list = powershell_escape_path( @orig_path_list )
305
306       Given a list of directory paths (or filenames), this will return an
307       equivalent list of paths escaped for PowerShell.
308

CAVEATS

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
317       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
323       The incantation for prepending and appending elements to a path on csh
324       probably deserve a comment here.  It looks like this:
325
326        test "$?PATH" = 0 && setenv PATH '/foo/bar/bin:/bar/foo/bin' || setenv PATH "$PATH":'/foo/bar/bin:/bar/foo/bin';
327
328       •   one line
329
330           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
334            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
340           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
345       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
348       Only UNIX (bourne, bash, csh, ksh, fish and their derivatives) and
349       Windows (command.com, cmd.exe and PowerShell) are supported so far.
350
351       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
357       Patches welcome for your favorite shell / operating system.
358

AUTHOR

360       Author: Graham Ollis <plicease@cpan.org>
361
362       Contributors:
363
364       Brad Macpherson (BRAD, brad-mac)
365
366       mohawk
367
369       This software is copyright (c) 2017 by Graham Ollis.
370
371       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.
373
374
375
376perl v5.38.0                      2023-07-21        Shell::Config::Generate(3)
Impressum