App::Cme::Command::run - Run a cme script
version 1.040
$ 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
Run a script written for cme
cme
A script passed by name is searched in ~/.cme/scripts, /etc/cme/scripts or /usr/share/perl5/Config/Model/scripts. E.g. with cme run foo, cme loads either ~/.cme/scripts/foo, /etc/cme/scripts/foo or /usr/share/perl5/Config/Model/scripts/foo
~/.cme/scripts
/etc/cme/scripts
/usr/share/perl5/Config/Model/scripts
cme run foo
~/.cme/scripts/foo
/etc/cme/scripts/foo
/usr/share/perl5/Config/Model/scripts/foo
No search is done if the script is passed with a path (e.g. cme run ./foo)
cme run ./foo
cme run accepts scripts written with different syntaxes:
cme run
For simple script, this DSL text specifies the target app, the doc, optional variables and a load string used by Config::Model::Loader or Perl code.
Like text above, but using Yaml syntax.
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).
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 cme function in /usr/local/bin/. Note that the script must begin with the usual shebang line (#!) and be executable.
/usr/local/bin/
#!
When run, this script:
opens the configuration file of app
app
applies the modifications specified with load instructions or the Perl code.
load
save the configuration files
commits the result if commit is specified (either in script or on command line).
commit
See App::Cme::Command::run for details.
The script accepts instructions in the form:
key: value
The key line can be repeated when needed.
Multi line values can also be:
--- key multi line value ---
The script accepts the following instructions:
Specify the target application. Must be one of the application listed by cme list command. Mandatory. Only one app instruction is allowed.
cme list
Specify default values that can be used in load or var sections.
var
For instance:
default: name=foobar
Use Perl code to specify variables usable in this script. The Perl code must store data in %var hash. For instance:
%var
var: my @l = localtime; $var{year} = $l[5]+1900;
The hash %args contains the variables passed with the -arg option. Reading a value from %args which is not set by user triggers a missing option error. Use exists if you need to test if a argument was set by user:
%args
-arg
exists
var: $var{foo} = exists $var{bar} ? $var{bar} : 'default' # good var: $var{foo} = $var{bar} || 'default' # triggers a "missing arg" error
Specify the modifications to apply using a string as specified in Config::Model::Loader. This string can contain variable (e.g. $foo) which are replaced by command argument (e.g. -arg foo=bar) or by a variable set in var: line (e.g. $var{foo} as set above) or by an environment variable (e.g. $ENV{foo})
$foo
-arg foo=bar
$var{foo}
$ENV{foo}
Specify Perl code to run. See "code section" for details.
Specify that the change must be committed with the passed commit message. When this option is used, cme raises an error if used on a non-clean workspace. This option works only with git.
All instructions can use variables like $stuff whose value can be specified with -arg options, with a Perl variable (from var: section explained above) or with an environment variable:
$stuff
var:
cme run -arg var1=foo -arg var2=bar
transforms the instruction:
load: ! a=$var1 b=$var2
in
load: ! a=foo b=bar
Here's an example from libconfig-model-dpkg-perl scripts:
doc: add myself to Uploaders app: dpkg-control load: source Uploaders:.insort("$DEBFULLNAME <$DEBEMAIL>") commit: add $DEBEMAIL to Uploaders
The code section can contain variable (e.g. $foo) which are replaced by command argument (e.g. -arg foo=bar) or by a variable set in var: line (e.g. $var{foo} as set above).
When evaluated the following variables are also set:
Root node of the configuration (See Config::Model::Node)
Configuration instance (See Config::Model::Instance)
Message used to commit the modification.
Since the code is run in an eval, other variables are available (like $self) to shoot yourself in the foot.
eval
$self
For example:
app: popcon ---code $root->fetch_element('MY_HOSTID')->store($to_store); ---
This format is intented for people not wanting to user the text format above. It supoorts the same parameters as the text format.
# Format: YAML --- app: popcon default: defname: foobar var: "$var{name} = $args{defname}" load: "! MY_HOSTID=$name"
This format is intended for more complex script where using load instructions is not enough.
This script must then begin with # Format: perl and specifies a hash. For instance:
# Format: perl
# 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}); } }
$root is the root if the configuration tree (See Config::Model::Node). $arg is a hash containing the arguments passed to cme run with -arg options.
$root
$arg
The sub parameter value must be a sub ref. Its parameters are $root (a Config::Model::Node object containing the root of the configuration tree) and $arg (a hash ref containing the keys and values passed to cme run with --arg options).
sub
--arg
Note that this format does not support var, default and load parameters as you can easily achieve the same result with Perl code.
default
List available scripts and exits.
Arguments for the cme scripts which are used to substitute variables.
Show the script documentation. (Note that --help options show the documentation of cme run command)
--help
Pop the hood and show the content of the script.
Like the commit instruction in script. Specify that the change must be committed with the passed commit message.
Don't commit to git (even if the above option is set)
Show effect of the modify instructions.
See "Global Options" in cme.
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(-)
$ 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) example: cme run set-vcs-git 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{url} =~ s!^git@!https://!; $var{url} =~ s!(https?://[\w.]+):!$1/!; $var{browser} = $var{url}; $var{browser} =~ s/.git$//; --- load: ! source Vcs-Browser="$browser" Vcs-Git="$url" commit: control: update Vcs-Browser and Vcs-Git
Dominique Dumont
This software is Copyright (c) 2014-2022 by Dominique Dumont <ddumont@cpan.org>.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999
To install App::Cme, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Cme
CPAN shell
perl -MCPAN -e shell install App::Cme
For more information on module installation, please visit the detailed CPAN module installation guide.