.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "App::Cme::Command::run 3pm"
.TH App::Cme::Command::run 3pm 2024-01-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
App::Cme::Command::run \- Run a cme script
.SH VERSION
.IX Header "VERSION"
version 1.040
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 8
\& $ 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: \*(Aq<undef>\*(Aq \-> \*(AqDominique Dumont <dod@debian.org>\*(Aq
\&
\& # 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
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Run a script written for \f(CW\*(C`cme\*(C'\fR
.PP
A script passed by name is searched in \f(CW\*(C`~/.cme/scripts\*(C'\fR,
\&\f(CW\*(C`/etc/cme/scripts\*(C'\fR or \f(CW\*(C`/usr/share/perl5/Config/Model/scripts\*(C'\fR.
E.g. with \f(CW\*(C`cme run foo\*(C'\fR, \f(CW\*(C`cme\*(C'\fR loads either \f(CW\*(C`~/.cme/scripts/foo\*(C'\fR,
\&\f(CW\*(C`/etc/cme/scripts/foo\*(C'\fR or
\&\f(CW\*(C`/usr/share/perl5/Config/Model/scripts/foo\*(C'\fR
.PP
No search is done if the script is passed with a path
(e.g. \f(CW\*(C`cme run ./foo\*(C'\fR)
.PP
\&\f(CW\*(C`cme run\*(C'\fR accepts scripts written with different syntaxes:
.IP "cme DSL" 4
.IX Item "cme DSL"
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.
.IP YAML 4
.IX Item "YAML"
Like text above, but using Yaml syntax.
.IP "Perl data structure" 4
.IX 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).
.IP "plain Perl script" 4
.IX Item "plain Perl script"
\&\f(CW\*(C`cme run\*(C'\fR 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 \f(CW\*(C`/usr/local/bin/\*(C'\fR.
Note that the script must begin with the usual shebang line (\f(CW\*(C`#!\*(C'\fR)
and be executable.
.PP
When run, this script:
.IP \(bu 4
opens the configuration file of \f(CW\*(C`app\*(C'\fR
.IP \(bu 4
applies the modifications specified with \f(CW\*(C`load\*(C'\fR instructions or the Perl code.
.IP \(bu 4
save the configuration files
.IP \(bu 4
commits the result if \f(CW\*(C`commit\*(C'\fR is specified (either in script or on command line).
.PP
See App::Cme::Command::run for details.
.SH "Syntax of text format"
.IX Header "Syntax of text format"
The script accepts instructions in the form:
.PP
.Vb 1
\& key: value
.Ve
.PP
The key line can be repeated when needed.
.PP
Multi line values can also be:
.PP
.Vb 3
\& \-\-\- key
\& multi line value
\& \-\-\-
.Ve
.PP
The script accepts the following instructions:
.IP app 4
.IX Item "app"
Specify the target application. Must be one of the application listed
by \f(CW\*(C`cme list\*(C'\fR command. Mandatory. Only one \f(CW\*(C`app\*(C'\fR instruction is
allowed.
.IP default 4
.IX Item "default"
Specify default values that can be used in \f(CW\*(C`load\*(C'\fR or \f(CW\*(C`var\*(C'\fR sections.
.Sp
For instance:
.Sp
.Vb 1
\& default: name=foobar
.Ve
.IP var 4
.IX Item "var"
Use Perl code to specify variables usable in this script. The Perl
code must store data in \f(CW%var\fR hash. For instance:
.Sp
.Vb 1
\&    var: my @l = localtime; $var{year} =  $l[5]+1900;
.Ve
.Sp
The hash \f(CW%args\fR contains the variables passed with the \f(CW\*(C`\-arg\*(C'\fR
option. Reading a value from \f(CW%args\fR which is not set by user
triggers a missing option error. Use \f(CW\*(C`exists\*(C'\fR if you need to test if
a argument was set by user:
.Sp
.Vb 2
\&    var: $var{foo} = exists $var{bar} ? $var{bar} : \*(Aqdefault\*(Aq # good
\&    var: $var{foo} = $var{bar} || \*(Aqdefault\*(Aq # triggers a "missing arg" error
.Ve
.IP load 4
.IX Item "load"
Specify the modifications to apply using a string as specified in
Config::Model::Loader. This string can contain variable
(e.g. \f(CW$foo\fR) which are replaced by command argument (e.g. \f(CW\*(C`\-arg
foo=bar\*(C'\fR) or by a variable set in var: line (e.g. \f(CW$var{foo}\fR as set
above) or by an environment variable (e.g. \f(CW$ENV{foo}\fR)
.IP code 4
.IX Item "code"
Specify Perl code to run. See "code section" for details.
.IP commit 4
.IX Item "commit"
Specify that the change must be committed with the passed commit
message. When this option is used, \f(CW\*(C`cme\*(C'\fR raises an error if used on a
non-clean workspace. This option works only with git.
.PP
All instructions can use variables like \f(CW$stuff\fR whose value can be
specified with \f(CW\*(C`\-arg\*(C'\fR options, with a Perl variable (from \f(CW\*(C`var:\*(C'\fR
section explained above) or with an environment variable:
.PP
For instance:
.PP
.Vb 1
\&  cme run \-arg var1=foo \-arg var2=bar
.Ve
.PP
transforms the instruction:
.PP
.Vb 1
\&  load: ! a=$var1 b=$var2
.Ve
.PP
in
.PP
.Vb 1
\&  load: ! a=foo b=bar
.Ve
.SS Example
.IX Subsection "Example"
Here's an example from 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>:
.PP
.Vb 4
\&  doc: add myself to Uploaders
\&  app: dpkg\-control
\&  load: source Uploaders:.insort("$DEBFULLNAME <$DEBEMAIL>")
\&  commit: add $DEBEMAIL to Uploaders
.Ve
.SS "Code section"
.IX Subsection "Code section"
The code section can contain variable (e.g. \f(CW$foo\fR) which are replaced by
command argument (e.g. \f(CW\*(C`\-arg foo=bar\*(C'\fR) or by a variable set in var:
line (e.g. \f(CW$var{foo}\fR as set above).
.PP
When evaluated the following variables are also set:
.ie n .IP $root 4
.el .IP \f(CW$root\fR 4
.IX Item "$root"
Root node of the configuration (See Config::Model::Node)
.ie n .IP $inst 4
.el .IP \f(CW$inst\fR 4
.IX Item "$inst"
Configuration instance (See Config::Model::Instance)
.ie n .IP $commit_msg 4
.el .IP \f(CW$commit_msg\fR 4
.IX Item "$commit_msg"
Message used to commit the modification.
.PP
Since the code is run in an \f(CW\*(C`eval\*(C'\fR, other variables are available
(like \f(CW$self\fR) to shoot yourself in the foot.
.PP
For example:
.PP
.Vb 4
\& app:  popcon
\& \-\-\-code
\& $root\->fetch_element(\*(AqMY_HOSTID\*(Aq)\->store($to_store);
\& \-\-\-
.Ve
.SH "Syntax of YAML format"
.IX Header "Syntax of YAML format"
This format is intented for people not wanting to user the text format
above. It supoorts the same parameters as the text format.
.PP
For instance:
.PP
.Vb 7
\& # Format: YAML
\& \-\-\-
\& app: popcon
\& default:
\&   defname: foobar
\& var: "$var{name} = $args{defname}"
\& load: "! MY_HOSTID=$name"
.Ve
.SH "Syntax of Perl format"
.IX Header "Syntax of Perl format"
This format is intended for more complex script where using \f(CW\*(C`load\*(C'\fR
instructions is not enough.
.PP
This script must then begin with \f(CW\*(C`# Format: perl\*(C'\fR and specifies a
hash. For instance:
.PP
.Vb 7
\& # Format: perl
\& {
\&      app => \*(Aqpopcon\*(Aq, # mandatory
\&      doc => "Use \-\-arg to_store=a_value to store a_value in MY_HOSTID\*(Aq,
\&      commit => "control: update Vcs\-Browser and Vcs\-Git"
\&      sub => sub ($root, $arg) { $root\->fetch_element(\*(AqMY_HOSTID\*(Aq)\->store($arg\->{to_store}); }
\& }
.Ve
.PP
\&\f(CW$root\fR is the root if the configuration tree (See Config::Model::Node).
\&\f(CW$arg\fR is a hash containing the arguments passed to \f(CW\*(C`cme run\*(C'\fR with \f(CW\*(C`\-arg\*(C'\fR options.
.PP
The \f(CW\*(C`sub\*(C'\fR parameter value must be a sub ref. Its parameters are
\&\f(CW$root\fR (a Config::Model::Node object containing the root of the
configuration tree) and \f(CW$arg\fR (a hash ref containing the keys and
values passed to \f(CW\*(C`cme run\*(C'\fR with \f(CW\*(C`\-\-arg\*(C'\fR options).
.PP
Note that this format does not support \f(CW\*(C`var\*(C'\fR, \f(CW\*(C`default\*(C'\fR and \f(CW\*(C`load\*(C'\fR
parameters as you can easily achieve the same result with Perl code.
.SH Options
.IX Header "Options"
.SS list
.IX Subsection "list"
List available scripts and exits.
.SS arg
.IX Subsection "arg"
Arguments for the cme scripts which are used to substitute variables.
.SS doc
.IX Subsection "doc"
Show the script documentation. (Note that \f(CW\*(C`\-\-help\*(C'\fR options show the
documentation of \f(CW\*(C`cme run\*(C'\fR command)
.SS cat
.IX Subsection "cat"
Pop the hood and show the content of the script.
.SS commit
.IX Subsection "commit"
Like the commit instruction in script. Specify that the change must be
committed with the passed commit message.
.SS no-commit
.IX Subsection "no-commit"
Don't commit to git (even if the above option is set)
.SS verbose
.IX Subsection "verbose"
Show effect of the modify instructions.
.SH "Common options"
.IX Header "Common options"
See "Global Options" in cme.
.SH Examples
.IX Header "Examples"
.ie n .SS "update copyright years in ""debian/copyright"""
.el .SS "update copyright years in \f(CWdebian/copyright\fP"
.IX Subsection "update copyright years in debian/copyright"
.Vb 4
\& $ cme run update\-copyright \-cat
\& app: dpkg\-copyright
\& load: Files:~ Copyright=~"s/2016,?\es+$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: \*(Aq2005\-2016, Dominique Dumont <dod@debian.org>\*(Aq \-> \*(Aq2005\-2017, Dominique Dumont <dod@debian.org>\*(Aq
\& \- 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(\-)
.Ve
.SS "update VcsGit in debian/control"
.IX Subsection "update VcsGit in debian/control"
.Vb 7
\& $ 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?://[\ew.]+):!$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
.Ve
.PP
This script can also be written using multi line instructions:
.PP
.Vb 4
\& $ 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?://[\ew.]+):!$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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
cme
.SH AUTHOR
.IX Header "AUTHOR"
Dominique Dumont
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2014\-2022 by Dominique Dumont <ddumont@cpan.org>.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU Lesser General Public License, Version 2.1, February 1999
.Ve