/ 
App-Cme-1.034
River stage one • 1 direct dependent • 3 total dependents
/ App::Cme::Command::run

NAME

App::Cme::Command::run - Run a cme script

VERSION

version 1.034

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

DESCRIPTION

Run a script written with cme DSL (Design specific language) or in plain Perl.

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

No search is done if the script is passed with a path (e.g. cme run ./foo)

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/.

When run, this script:

  • opens the configuration file of app

  • applies the modifications specified with load instructions

  • save the configuration files

  • commits the result if commit is specified (either in script or on command line).

See App::Cme::Command::run for details.

Syntax

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:

app

Specify the target application. Must be one of the application listed by cme list command. Mandatory. Only one app instruction is allowed.

var

Use Perl code to specify variables usable in this script. The Perl code must store data in %var hash. For instance:

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:

var: $var{foo} = exists $var{bar} ? $var{bar} : 'default' # good
var: $var{foo} = $var{bar} || 'default' # triggers a "missing arg" error
load

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})

commit

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:

For instance:

cme run -arg var1=foo -arg var2=bar

transforms the instruction:

load: ! a=$var1 b=$var2

in

load: ! a=foo b=bar

Options

list

List available scripts and exits.

arg

Arguments for the cme scripts which are used to substitute variables.

doc

Show the script documentation. (Note that --help options show the documentation of cme run command)

cat

Pop the hood and show the content of the script.

commit

Like the commit instruction in script. Specify that the change must be committed with the passed commit message.

no-commit

Don't commit to git (even if the above option is set)

verbose

Show effect of the modify instructions.

Common options

See "Global Options" in cme.

Examples

$ 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(-)

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)

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

SEE ALSO

cme

AUTHOR

Dominique Dumont

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014-2021 by Dominique Dumont.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999