App-Cme
view release on metacpan or search on metacpan
lib/App/Cme/Command/run.pm view on Meta::CPAN
);
$self->commit($processed_msg);
}
} else {
say "No change were applied";
}
if ($stashed) {
$self->pop_stash;
}
return;
}
package App::Cme::Run::Var; ## no critic (Modules::ProhibitMultiplePackages)
$App::Cme::Run::Var::VERSION = '1.049';
require Tie::Hash;
## no critic (ClassHierarchies::ProhibitExplicitISA)
our @ISA = qw(Tie::ExtraHash);
sub FETCH {
my ($self, $key) = @_ ;
my ($h, $missing, $default) = @$self;
my $res = $h->{$key} // $default->{$key} ;
$missing->{$key} = 1 unless defined $res;
return $res // '';
}
1;
__END__
=pod
=encoding UTF-8
=head1 NAME
App::Cme::Command::run - Run a cme script
=head1 VERSION
version 1.049
=head1 SYNOPSIS
$ cat ~/.cme/scripts/remove-mia
doc: remove mia from Uploaders. Require mia parameter
# declare app to configure
app: dpkg
# specify one or more instructions
load: ! control source Uploaders:-~/$mia$/
# commit the modifications with a message (git only)
commit: remove MIA dev $mia
$ cme run remove-mia -arg mia=longgone@d3bian.org
# cme run can also use environment variables
$ cat ~/.cme/scripts/add-me-to-uploaders
app: dpkg-control
load: source Uploaders:.push("$DEBFULLNAME <$DEBEMAIL>")
$ cme run add-me-to-uploaders
Reading package lists... Done
Building dependency tree
Reading state information... Done
Changes applied to dpkg-control configuration:
- source Uploaders:3: '<undef>' -> 'Dominique Dumont <dod@debian.org>'
# show the script documentation
$ cme run remove-mia -doc
remove mia from Uploaders. require mia parameter
# list scripts
$ cme run -list
Available scripts:
- update-copyright
- add-me-to-uploaders
# mass modification
$ cme run add-me-to-uploaders --foreach "raku-log raku-zef"
# similar result
$ echo "raku-*" | cme run add-me-to-uploaders --foreach -
=head1 DESCRIPTION
Run a script written for C<cme>
A script passed by name is searched in C<~/.cme/scripts>,
C</etc/cme/scripts> or C</usr/share/perl5/Config/Model/scripts>.
E.g. with C<cme run foo>, C<cme> loads either C<~/.cme/scripts/foo>,
C</etc/cme/scripts/foo> or
C</usr/share/perl5/Config/Model/scripts/foo>
No search is done if the script is passed with a path
(e.g. C<cme run ./foo>)
C<cme run> accepts scripts written with different syntaxes:
=over
=item cme DSL
For simple script, this DSL text specifies the target app, the doc,
optional variables and a load string used by L<Config::Model::Loader> or
Perl code.
=item YAML
Like text above, but using Yaml syntax.
=item Perl data structure
Writing Perl code in a text file or in a YAML field can be painful as
Perl syntax is not highlighted. With a Perl data structure, a cme
script specifies the target app, the doc, optional variables, and a
perl subroutine (see below).
=item plain Perl script
C<cme run> can also run plain Perl script. This is syntactic sugar to
avoid polluting global namespace, i.e. there's no need to store a
script using L<cme function|Config::Model/cme> in C</usr/local/bin/>.
Note that the script must begin with the usual shebang line (C<#!>)
and be executable.
To help management with C<cme run>, comment lines beginning with C<##>
are shown as doc (with C<cme run xxx --doc>), comment line beginning
with C<# app:> indicates the app shown by C<cme run --list> command.
=back
When run, this script:
=over
=item *
opens the configuration file of C<app>
=item *
applies the modifications specified with C<load> instructions or the Perl code.
lib/App/Cme/Command/run.pm view on Meta::CPAN
foo=bar>) or by a variable set in var: line (e.g. C<$var{foo}> as set
above) or by an environment variable (e.g. C<$ENV{foo}>)
=item code
Specify Perl code to run. See L</code section> for details.
=item commit
Specify that the change must be committed with the passed commit
message. When this option is used, C<cme> stashes and restores all
modifications if used on a non-clean workspace. This option works only
with L<git>.
Strings like C<{{ load path }}> are substituted with a value extracted
from configuration tree with the specified load path. See
L<Config::Model::Loader> for a valid load path.
For example, this specification:
load: source Standards-Version="4.7.0"
commit: declare compliance with policy {{source Standards-Version}}
yields this commit message:
declare compliance with policy 4.7.0
String like C<$some_value> are with substituted with a value coming
from an environment variable, a script argument or a value defined as
a C<var> line.
For example, this specification:
var: $var{close_str} = defined $args{closes} ? " (Closes: #$args{closes})" : ""
commit: set $DEBEMAIL as Maintainer$close_str
invoked with argument C<-arg closes=1234>, yields this commit message:
set dod@example.com as Maintainer (Closes: #1234)
=back
All instructions can use variables like C<$stuff> whose value can be
specified with C<-arg> options, with a Perl variable (from C<var:>
section explained above) or with an environment variable:
For instance:
cme run -arg var1=foo -arg var2=bar
transforms the instruction:
load: ! a=$var1 b=$var2
in
load: ! a=foo b=bar
=head2 Example
Here's an example from L<libconfig-model-dpkg-perl scripts|https://salsa.debian.org/perl-team/modules/packages/libconfig-model-dpkg-perl/-/blob/master/lib/Config/Model/scripts/add-me-to-uploaders>:
doc: add myself to Uploaders
app: dpkg-control
load: source Uploaders:.insort("$DEBFULLNAME <$DEBEMAIL>")
commit: add $DEBEMAIL to Uploaders
You can find other examples on L<script directory of libconfig-model-dpkg-perl|https://salsa.debian.org/perl-team/modules/packages/libconfig-model-dpkg-perl/-/blob/master/lib/Config/Model/scripts/>
=head2 Code section
The code section can contain variable (e.g. C<$foo>) which are replaced by
command argument (e.g. C<-arg foo=bar>) or by a variable set in var:
line (e.g. C<$var{foo}> as set above).
When evaluated the following variables are also set:
=over
=item $root
Root node of the configuration (See L<Config::Model::Node>)
=item $inst
Configuration instance (See L<Config::Model::Instance>)
=item $commit_msg
Message used to commit the modification.
=back
Since the code is run in an C<eval>, other variables are available
(like C<$self>) to shoot yourself in the foot.
For example:
app: popcon
---code
$root->fetch_element('MY_HOSTID')->store($to_store);
---
=head1 Syntax of YAML format
This format is intented for people not wanting to user the text format
above. It supports the same parameters as the text format.
When using "!" and "$" characters in a string, using YAML block scalar
is probably easier.
For instance:
# Format: YAML
---
app: popcon
default:
defname: foobar
var: |-
$var{name} = $args{defname}
load: |-
lib/App/Cme/Command/run.pm view on Meta::CPAN
This script must then begin with C<# Format: perl> and specifies a
hash. For instance:
# Format: perl
{
app => 'popcon', # mandatory
doc => "Use --arg to_store=a_value to store a_value in MY_HOSTID',
commit => "control: update Vcs-Browser and Vcs-Git"
sub => sub ($root, $arg) { $root->fetch_element('MY_HOSTID')->store($arg->{to_store}); }
}
C<$root> is the root if the configuration tree (See L<Config::Model::Node>).
C<$arg> is a hash containing the arguments passed to C<cme run> with C<-arg> options.
The C<sub> parameter value must be a sub ref. Its parameters are
C<$root> (a L<Config::Model::Node> object containing the root of the
configuration tree) and C<$arg> (a hash ref containing the keys and
values passed to C<cme run> with C<--arg> options).
Note that this format does not support C<var>, C<default> and C<load>
parameters as you can easily achieve the same result with Perl code.
=head1 Options
=head2 list
List available scripts and exits.
=head2 arg
Arguments for the cme scripts which are used to substitute variables.
=head2 doc
Show the script documentation. (Note that C<--help> options show the
documentation of C<cme run> command)
=head2 cat
Pop the hood and show the content of the script.
=head2 commit
Like the commit instruction in script. Specify that the change must be
committed with the passed commit message.
=head2 no-commit
Don't commit to git (even if the above option is set)
=head2 foreach
Apply the script in specific directories. This option is available
only when dealing with application (See the list returned by C<cme list>).
For instance, if your directory contains several Debian packages and
you want to apply the same modification to all packages, you can run
something like:
cme run add-me-to-uploaders --foreach "raku-log raku-zef"
or use C<STDIN> to send the package directories:
ls "raku-*" | cme run add-me-to-uploaders --foreach -
=head2 verbose
Show effect of the modify instructions.
=head1 Common options
See L<cme/"Global Options">.
=head1 Examples
=head2 update copyright years in C<debian/copyright>
$ cme run update-copyright -cat
app: dpkg-copyright
load: Files:~ Copyright=~"s/2016,?\s+$name/2017, $name/g"
commit: updated copyright year of $name
$ cme run update-copyright -arg "name=Dominique Dumont"
cme: using Dpkg::Copyright model
Changes applied to dpkg-copyright configuration:
- Files:"*" Copyright: '2005-2016, Dominique Dumont <dod@debian.org>' -> '2005-2017, Dominique Dumont <dod@debian.org>'
- Files:"lib/Dpkg/Copyright/Scanner.pm" Copyright:
@@ -1,2 +1,2 @@
-2014-2016, Dominique Dumont <dod@debian.org>
+2014-2017, Dominique Dumont <dod@debian.org>
2005-2012, Jonas Smedegaard <dr@jones.dk>
[master ac2e6410] updated copyright year of Dominique Dumont
1 file changed, 2 insertions(+), 2 deletions(-)
=head2 update VcsGit in debian/control
$ cme run set-vcs-git -cat
doc: update control Vcs-Browser and Vcs-git from git remote value
doc: parameters: remote (default is origin)
doc:
doc: example:
doc: cme run set-vcs-git
doc: cme run set-vcs-git -arg remote=debian
app: dpkg-control
default: remote: origin
var: chomp ( $var{url} = `git remote get-url $args{remote}` ) ;
var: $var{url} =~ s!^git@!https://!;
var: $var{url} =~ s!(https?://[\w.]+):!$1/!;
var: $var{browser} = $var{url};
var: $var{browser} =~ s/.git$//;
load: ! source Vcs-Browser="$browser" Vcs-Git="$url"
commit: control: update Vcs-Browser and Vcs-Git
This script can also be written using multi line instructions:
$ cme run set-vcs-git -cat
--- doc
update control Vcs-Browser and Vcs-git from git remote value
parameters: remote (default is origin)
( run in 1.720 second using v1.01-cache-2.11-cpan-b16cb0d3907 )