Perlbrew.pm untested

filter: Statementstmt 0.0% 0 / 156 Branchbran 0.0% 0 / 84 Conditioncond 0.0% 0 / 26 MC/DCmcdc 0.0% 0 / 16 Subroutinesub 0.0% 0 / 22 Podpod 0.0% 0 / 14 totaltotal 0.0% 0 / 318 CC 40 SCAR 41.3
CC
40
Cov
0%
spoil
156.0
register
132.0
brew
42.0
CRAP 62.1
1 package Devel::IPerl::Plugin::Perlbrew;
2  
3 use strict;
4 use warnings;
5 use feature 'say';
6 use Symbol 'delete_package';
7 use constant DEBUG => $ENV{IPERL_PLUGIN_PERLBREW_DEBUG} ? 1 : 0;
8  
9 use constant PERLBREW_CLASS => $ENV{IPERL_PLUGIN_PERLBREW_CLASS}
10 ? $ENV{IPERL_PLUGIN_PERLBREW_CLASS}
11 : 'App::perlbrew';
12  
13 use constant PERLBREW_INSTALLED => eval 'use '. PERLBREW_CLASS.'; 1' ? 1 : 0;
14  
15 our $VERSION = '0.03';
16  
17 sub brew {
18 my $self = shift;
19 my %env = %{$self->env || {}};
20 my %save = ();
21 for my $var(_filtered_env_keys(\%env)) {
22 say STDERR "@$self{name} ", join " = ", $var, $env{$var} if DEBUG;
23 $save{$var} = $ENV{$var} if exists $ENV{$var};
24 $ENV{$var} = $env{$var};
25 }
26 if ($env{PERL5LIB}) {
27 say STDERR join " = ", 'PERL5LIB', $env{'PERL5LIB'} if DEBUG;
28 eval "use lib split ':', q[$env{PERL5LIB}];";
29 warn $@ if $@; ## uncoverable branch true
30 }
31 return $self->saved(\%save);
32 }
33  
34 sub env { return $_[0]{env} if @_ == 1; $_[0]{env} = $_[1]; $_[0]; }
35  
36 sub new {
37 my $class = shift;
38 bless @_ ? @_ > 1 ? {@_} : {%{$_[0]}} : {}, ref $class || $class;
39 }
40  
41 sub name { return $_[0]{name} if @_ == 1; $_[0]{name} = $_[1]; $_[0]; }
42  
43 sub register {
44 my ($class, $iperl) = @_;
45  
46 my $domain = sub {
47 my $instance = $_[0]->instance;
48 return $instance->{'perlbrew_domain'} if @_ == 1;
49 $instance->{'perlbrew_domain'} = $_[1];
50 $instance;
51 };
52  
53 $domain->($iperl, $ENV{'PERLBREW_HOME'});
54  
55 for my $name (qw{perlbrew}) {
56 my $current = $class->new->name('@@@'); ## impossible name
57  
58 $iperl->helper($name => sub {
59 my ($ip, $lib, $unload, $ret) = (shift, shift, shift || 0, -1);
60 return $ret if not defined $lib;
61 return $ret if 0 == PERLBREW_INSTALLED;
62  
63 my $new = $class->new->name($class->_make_name($lib));
64 if ($current->unload($unload)->name ne $new->name) {
65 my $pb = PERLBREW_CLASS->new();
66 $pb->home($domain->($ip));
67 $new->env({ $pb->perlbrew_env($new->name) });
68 ## ensure the timing of the DESTROY, spoil
69 undef($current = $current->spoil);
70 $current = $new->brew;
71 }
72 return $new->success;
73 });
74 }
75  
76 for my $name (qw{list list_modules}) {
77 $iperl->helper("perlbrew_$name" => sub {
78 my ($ip, $ret) = (shift, -1);
79 return $ret if 0 == PERLBREW_INSTALLED;
80 my $pb = PERLBREW_CLASS->new();
81 $pb->home($domain->($ip));
82 local $App::perlbrew::PERLBREW_HOME = $pb->home
83 if ($name eq 'list_modules');
84 return $pb->run_command($name, @_);
85 });
86 }
87  
88 for my $name (qw{lib_create}) {
89 $iperl->helper("perlbrew_$name" => sub {
90 my ($ip, $lib, $ret) = (shift, shift, -1);
91 return $ret if not defined $lib;
92 return $ret if 0 == PERLBREW_INSTALLED;
93 my $pb = PERLBREW_CLASS->new();
94 $pb->home($domain->($ip));
95 eval { $pb->run_command_lib_create($class->_make_name($lib)); };
96 return $@ ? 0 : 1;
97 });
98 }
99  
100 $iperl->helper('perlbrew_domain' => sub {
101 my ($ip, $dir) = (shift, shift);
102 return $domain->($ip) unless $dir && -d $dir;
103 return $domain->($ip, $dir)->{'perlbrew_domain'};
104 });
105  
106 return 1;
107 }
108  
109 sub saved { return $_[0]{saved} if @_ == 1; $_[0]{saved} = $_[1]; $_[0]; }
110  
111 sub spoil {
112 my $self = shift;
113 my %env = %{$self->env || {}};
114 my %save = %{$self->saved || {}};
115 for my $var(_filtered_env_keys(\%env)) {
116 if (exists $save{$var}) {
117 say STDERR "revert ", join " = ", $var, $save{$var} if DEBUG;
118 $ENV{$var} = $save{$var};
119 } else {
120 say STDERR "unset ", $var if DEBUG;
121 delete $ENV{$var};
122 }
123 }
124 if ($env{PERL5LIB}) {
125 say STDERR join " = ", 'PERL5LIB', $env{'PERL5LIB'} if DEBUG;
126 eval "no lib split ':', q[$env{PERL5LIB}];";
127 warn $@ if $@; ## uncoverable branch true
128 if ($self->unload) {
129 my $path_re = qr{\Q$env{PERL5LIB}\E};
130 for my $module_path(keys %INC) {
131 ## autosplit modules
132 next if $module_path =~ m{\.(al|ix)$} && delete $INC{$module_path};
133 ## global destruction ?
134 next if not defined $INC{$module_path};
135 ## FatPacked ?
136 next if ref($INC{$module_path});
137 ## Not part of this PERL5LIB
138 next if $INC{$module_path} !~ m{^$path_re};
139 ## translate to class_path
140 (my $class = $module_path) =~ s{/}{::}g;
141 $class =~ s/\.pm//;
142 ## notify and unload
143 say "unloading $class ($module_path) from $INC{$module_path}";
144 _teardown( $class );
145 delete $INC{$module_path};
146 }
147 }
148 }
149 # no need to revert again.
150 return $self->env({})->saved({});
151 }
152  
153 sub success { scalar(keys %{$_[0]->{env}}) ? 1 : 0; }
154  
155 sub unload { return $_[0]{unload} if @_ == 1; $_[0]{unload} = $_[1]; $_[0]; }
156  
157 sub _filtered_env_keys {
158 return (sort grep { m/^PERL/i && $_ ne "PERL5LIB" } keys %{+pop});
159 }
160  
161 sub _from_binary_path {
162 say STDERR $^X if DEBUG;
163 if ($^X =~ m{/perls/([^/]+)/bin/perl}) { return $1; }
164 (my $v = $^V->normal) =~ s/v/perl-/;
165 return $v;
166 }
167  
168 sub _make_name {
169 my ($class, $name, $current) =
170 (shift, shift, $ENV{PERLBREW_PERL} || _from_binary_path());
171 my ($perl, $lib) =
172 split /\@/, ($name =~ m/\@/ || $name eq $current ? $name : "\@$name");
173 $perl = $current;
174 return $perl unless $lib;
175 return join '@', $perl, $lib;
176 }
177  
178 ## from Mojo::Util
179 sub _teardown {
180 return unless my $class = shift;
181 # @ISA has to be cleared first because of circular references
182 no strict 'refs';
183 @{"${class}::ISA"} = ();
184 delete_package $class;
185 }
186  
187 sub DESTROY {
188 my $self = shift;
189 say STDERR "DESTROY $self @$self{name}" if DEBUG;
190 $self->spoil;
191 return ;
192 }
193  
194 1;
195  
196 =pod
197  
198 =head1 NAME
199  
200 Devel::IPerl::Plugin::Perlbrew - interact with L<perlbrew> in L<Jupyter|https://jupyter.org> IPerl kernel
201  
202 =begin html
203  
204 <!--- Travis --->
205 <a href="https://travis-ci.org/kiwiroy/Devel-IPerl-Plugin-Perlbrew">
206 <img src="https://travis-ci.org/kiwiroy/Devel-IPerl-Plugin-Perlbrew.svg?branch=master"
207 alt="Build Status" />
208 </a>
209  
210 <!-- Coveralls -->
211 <a href='https://coveralls.io/github/kiwiroy/Devel-IPerl-Plugin-Perlbrew?branch=master'>
212 <img src='https://coveralls.io/repos/github/kiwiroy/Devel-IPerl-Plugin-Perlbrew/badge.svg?branch=master'
213 alt='Coverage Status' />
214 </a>
215  
216 <!-- Kritika -->
217 <a href="https://kritika.io/users/kiwiroy/repos/6870682787977901/heads/master/">
218 <img src="https://kritika.io/users/kiwiroy/repos/6870682787977901/heads/master/status.svg"
219 alt="Kritika Analysis Status"/>
220 </a>
221  
222 =end html
223  
224 =head1 DESCRIPTION
225  
226 In a shared server environment the Perl module needs of multiple users can be
227 met most easily with access to L<perlbrew> and the ability to install perl
228 modules under their own libraries. A user can generate a L<cpanfile> to
229 facilitate the creation of these libraries in a reproducible manner. At the
230 command line a typical workflow in such an environment might appear thus:
231  
232 perlbrew lib create perl-5.26.0@reproducible
233 perlbrew use perl-5.26.0@reproducible
234 ## assuming a cpanfile
235 cpanm --installdeps .
236  
237 During the analysis that utilises such codebases using a JupyterHub on the same
238 environment a user will wish to access these installed modules in a way that is
239 as simple as the command line and within the framework of a Jupyter notebook.
240  
241 This plugin is designed to easily transition between command line and Jupyter
242 with similar syntax and little overhead.
243  
244 =begin html
245  
246 <p>There are some Jupyter notebooks in the <a href="./examples/">examples directory</a></p>
247  
248 =end html
249  
250 =head1 SYNOPSIS
251  
252 IPerl->load_plugin('Perlbrew') unless IPerl->can('perlbrew');
253 IPerl->perlbrew_list();
254 IPerl->perlbrew_list_modules();
255  
256 IPerl->perlbrew('perl-5.26.0@reproducible');
257  
258 =head1 INSTALLATION AND REQUISITES
259  
260 ## install dependencies
261 cpanm --installdeps --quiet .
262 ## install
263 cpanm .
264  
265 If there are some issues with L<Devel::IPerl> installing refer to their
266 L<README.md|https://github.com/EntropyOrg/p5-Devel-IPerl>. The C<.travis.yml> in
267 this repository might provide sources of help.
268  
269 L<App::perlbrew> is a requirement and it is B<suggested> that L<Devel::IPerl> is
270 deployed into a L<perlbrew> installed L<perl|perlbrew#COMMAND:-INSTALL> and call
271 the L</"perlbrew"> function to use each L<library|perlbrew#COMMAND:-LIB>.
272  
273 =over 4
274  
275 =item installing perlbrew
276  
277 For a single user use case the recommended install proceedure at
278 L<https://perlbrew.pl> should be used. If installing for a shared environment
279 and JupyterHub, the following may act as a template.
280  
281 version=0.82
282 mkdir -p /sw/perlbrew-$version
283 export PERLBREW_ROOT=!$
284 curl -L https://install.perlbrew.pl | bash
285  
286 =item installing iperl
287  
288 The kernel specification needs to be installed so that Jupyter can find it. This
289 is achieved thus:
290  
291 iperl --version
292  
293 =item perlbrew-ise the kernel
294  
295 The kernel specification should be updated to make the environment variables,
296 that L<App::perlbrew> relies on, available. Included in this dist is the command
297 C<perlbrewise-spec>.
298  
299 perlbrewise-spec
300  
301 =back
302  
303 =head1 IPerl Interface Method
304  
305 =head2 register
306  
307 Called by C<<< IPerl->load_plugin('Perlbrew') >>>.
308  
309 =head1 REGISTERED METHODS
310  
311 =head2 perlbrew
312  
313 # 1 - success
314 IPerl->perlbrew('perl-5.26.0@reproducible');
315 # 0 - it is already loaded
316 IPerl->perlbrew('perl-5.26.0@reproducible');
317 # -1 - no library specified
318 IPerl->perlbrew();
319 # 1 - success switching off reproducible and reverting to perl-5.26.0
320 IPerl->perlbrew($ENV{'PERLBREW_PERL'});
321  
322 This is identical to C<<< perlbrew use perl-5.26.0@reproducible >>> and will
323 switch any from any previous call. Returns C<1>, C<0> or C<-1> for I<success>,
324 I<no change> and I<error> respectively. A name for the library is required. To
325 revert to the I<"system"> or non-library version pass the value of
326 C<$ENV{PERLBREW_PERL}>.
327  
328 IPerl->perlbrew('perl-5.26.0@tutorial', 1);
329  
330 The function takes a Boolean as an optional second argument. A I<true> value will
331 result in all the modules that were loaded during the activity of the previous
332 library to be unloaded using L<delete_package|Symbol>. The default value is
333 I<false> as setting is to true might expose the L<unexpected|Symbol#BUGS>
334 behaviour.
335  
336 When using multiple L<perlbrew> libraries it may be possible to use modules from
337 both, although this is not a recommended use.
338  
339 IPerl->perlbrew('perl-5.26.0@tutorial');
340 use Jupyter::Tutorial::Simple;
341 ## run some code
342  
343 ## load @reproducible, but do not unload Jupyter::Tutorial::Simple
344 IPerl->perlbrew('perl-5.26.0@reproducible', 0);
345 use Bio::Taxonomy;
346 ## ... more code, possibly using Jupyter::Tutorial::Simple
347  
348 =head2 perlbrew_domain
349  
350 B<This is experimental>.
351  
352 # /home/username/.perlbrew
353 IPerl->perlbrew_domain;
354 # /work/username/perlbrew-libs
355 IPerl->perlbrew_domain('/work/username/perlbrew-libs');
356  
357 Users often generate a large number of libraries which can quickly result in a
358 long list generated in the output of L</"perlbrew_list">. This experimental
359 feature allows for switching between I<domains> to reduce the size of these
360 lists. Thus, a collection of libraries are organised under domains. These are
361 only directories, must exist before use and are synonymous with
362 C<$ENV{PERLBREW_HOME}>. Indeed, this is a convenient alternative to
363 C<$App::perlbrew::PERLBREW_HOME>.
364  
365 =head2 perlbrew_lib_create
366  
367 # 1 - success
368 IPerl->perlbrew_lib_create('reproducible');
369 # 0 - already exists
370 IPerl->perlbrew_lib_create('reproducible');
371 # -1 - no library name given
372 IPerl->perlbrew_lib_create();
373  
374 This is identical to C<<< perlbrew lib create >>>. Returns C<1>, C<0> or C<-1>
375 for I<success>, I<already exists> and I<error> respectively.
376  
377 =head2 perlbrew_list
378  
379 IPerl->perlbrew_list;
380  
381 This is identical to C<<< perlbrew list >>> and will output the same information.
382  
383 =head2 perlbrew_list_modules
384  
385 IPerl->perlbrew_list_modules;
386  
387 This is identical to C<<< perlbrew list_modules >>> and will output the same
388 information.
389  
390 =head1 ENVIRONMENT VARIABLES
391  
392 The following environment variables alter the behaviour of the plugin.
393  
394 =over 4
395  
396 =item IPERL_PLUGIN_PERLBREW_DEBUG
397  
398 A logical to control how verbose the plugin is during its activities.
399  
400 =item IPERL_PLUGIN_PERLBREW_CLASS
401  
402 This defaults to L<App::prelbrew>
403  
404 =back
405  
406 =head1 INTERNAL INTERFACES
407  
408 These are part of the internal interface and not designed for end user
409 consumption.
410  
411 =head2 brew
412  
413 $plugin->brew;
414  
415 Use the perlbrew library specified in L</"name">.
416  
417 =head2 env
418  
419 $plugin->env({PERLBREW_ROOT => '/sw/perlbrew', ...});
420 # {PERLBREW_ROOT => '/sw/perlbrew', ...}
421 $plugin->env;
422  
423 An accessor that stores the environment from L<App::perlbrew> for a subsequent
424 call to L</"brew">.
425  
426 =head2 new
427  
428 my $plugin = Devel::IPerl::Plugin::Perlbrew->new();
429  
430 Instantiate an object.
431  
432 =head2 name
433  
434 $plugin->name('perl-5.26.0@reproducible');
435 # perl-5.26.0@reproducible
436 $plugin->name;
437  
438 An accessor for the name of the perlbrew library.
439  
440 =head2 saved
441  
442 $plugin->saved;
443  
444 An accessor for the previous environment variables so they may be restored as
445 the L</"brew"> L</"spoil">s.
446  
447 =head2 spoil
448  
449 $plugin->spoil;
450  
451 When a L</"brew"> is finished with. This is called automatically during object
452 destruction.
453  
454 =head2 success
455  
456 # boolean where 1 == success, 0 == not success
457 $plugin->success;
458  
459 Was everything a success?
460  
461 =head2 unload
462  
463 $plugin->unload(1);
464 # 1
465 $plugin->unload;
466  
467 A flag to determine whether to unload all the modules that were used as part of
468 this library during cleanup.
469  
470 =cut