1App::Cme::Command::run(U3s)er Contributed Perl DocumentatAipopn::Cme::Command::run(3)
2
6 App::Cme::Command::run - Run a cme script
7
9 version 1.038
10
12 $ cat ~/.cme/scripts/remove-mia
13 doc: remove mia from Uploaders. Require mia parameter
14 # declare app to configure
15 app: dpkg
16 # specify one or more instructions
17 load: ! control source Uploaders:-~/$mia$/
18 # commit the modifications with a message (git only)
19 commit: remove MIA dev $mia
20 $ cme run remove-mia -arg mia=longgone@d3bian.org
22 # cme run can also use environment variables
24 $ cat ~/.cme/scripts/add-me-to-uploaders
25 app: dpkg-control
26 load: source Uploaders:.push("$DEBFULLNAME <$DEBEMAIL>")
27 $ cme run add-me-to-uploaders
29 Reading package lists... Done
30 Building dependency tree
31 Reading state information... Done
32 Changes applied to dpkg-control configuration:
33 - source Uploaders:3: '<undef>' -> 'Dominique Dumont <dod@debian.org>'
34 # show the script documentation
36 $ cme run remove-mia -doc
37 remove mia from Uploaders. require mia parameter
38 # list scripts
40 $ cme run -list
41 Available scripts:
42 - update-copyright
43 - add-me-to-uploaders
44
46 Run a script written for "cme"
47 A script passed by name is searched in "~/.cme/scripts",
49 "/etc/cme/scripts" or "/usr/share/perl5/Config/Model/scripts". E.g.
50 with "cme run foo", "cme" loads either "~/.cme/scripts/foo",
51 "/etc/cme/scripts/foo" or "/usr/share/perl5/Config/Model/scripts/foo"
52 No search is done if the script is passed with a path (e.g. "cme run
54 ./foo")
55 "cme run" accepts scripts written with different syntaxes:
57 in text
59 For simple script, this text specifies the target app, the doc,
60 optional variables and a load string used by Config::Model::Loader
61 or Perl code.
62 YAML
64 Like text above, but using Yaml syntax.
65 Perl data structure
67 Writing Perl code in a text file or in a YAML field can be painful
68 as Perl syntax is not highlighted. With a Perl data structure, a
69 cme script specifies the target app, the doc, optional variables,
70 and a perl subroutine (see below).
71 plain Perl script
73 "cme run" can also run plain Perl script. This is syntactic sugar
74 to avoid polluting global namespace, i.e. there's no need to store
75 a script using cme function in "/usr/local/bin/".
76 When run, this script:
78 • opens the configuration file of "app"
80 • applies the modifications specified with "load" instructions or the
82 Perl code.
83 • save the configuration files
85 • commits the result if "commit" is specified (either in script or on
87 command line).
88 See App::Cme::Command::run for details.
90
92 The script accepts instructions in the form:
93 key: value
95 The key line can be repeated when needed.
97 Multi line values can also be:
99 --- key
101 multi line value
102 ---
103 The script accepts the following instructions:
105 app Specify the target application. Must be one of the application
107 listed by "cme list" command. Mandatory. Only one "app" instruction
108 is allowed.
109 default
111 Specify default values that can be used in "load" or "var"
112 sections.
113 For instance:
115 default: name=foobar
117 var Use Perl code to specify variables usable in this script. The Perl
119 code must store data in %var hash. For instance:
120 var: my @l = localtime; $var{year} = $l[5]+1900;
122 The hash %args contains the variables passed with the "-arg"
124 option. Reading a value from %args which is not set by user
125 triggers a missing option error. Use "exists" if you need to test
126 if a argument was set by user:
127 var: $var{foo} = exists $var{bar} ? $var{bar} : 'default' # good
129 var: $var{foo} = $var{bar} || 'default' # triggers a "missing arg" error
130 load
132 Specify the modifications to apply using a string as specified in
133 Config::Model::Loader. This string can contain variable (e.g. $foo)
134 which are replaced by command argument (e.g. "-arg foo=bar") or by
135 a variable set in var: line (e.g. $var{foo} as set above) or by an
136 environment variable (e.g. $ENV{foo})
137 code
139 Specify Perl code to run. See "code section" for details.
140 commit
142 Specify that the change must be committed with the passed commit
143 message. When this option is used, "cme" raises an error if used on
144 a non-clean workspace. This option works only with git.
145 All instructions can use variables like $stuff whose value can be
147 specified with "-arg" options, with a Perl variable (from "var:"
148 section explained above) or with an environment variable:
149 For instance:
151 cme run -arg var1=foo -arg var2=bar
153 transforms the instruction:
155 load: ! a=$var1 b=$var2
157 in
159 load: ! a=foo b=bar
161 Example
163 Here's an example from libconfig-model-dpkg-perl scripts
164 <https://salsa.debian.org/perl-team/modules/packages/libconfig-model-
165 dpkg-perl/-/blob/master/lib/Config/Model/scripts/add-me-to-uploaders>:
166 doc: add myself to Uploaders
168 app: dpkg-control
169 load: source Uploaders:.insort("$DEBFULLNAME <$DEBEMAIL>")
170 commit: add $DEBEMAIL to Uploaders
171 Code section
173 The code section can contain variable (e.g. $foo) which are replaced by
174 command argument (e.g. "-arg foo=bar") or by a variable set in var:
175 line (e.g. $var{foo} as set above).
176 When evaluated the following variables are also set:
178 $root
180 Root node of the configuration (See Config::Model::Node)
181 $inst
183 Configuration instance (See Config::Model::Instance)
184 $commit_msg
186 Message used to commit the modification.
187 Since the code is run in an "eval", other variables are available (like
189 $self) to shoot yourself in the foot.
190 For example:
192 app: popcon
194 ---code
195 $root->fetch_element('MY_HOSTID')->store($to_store);
196 ---
197
199 This format is intented for people not wanting to user the text format
200 above. It supoorts the same parameters as the text format.
201 For instance:
203 # Format: YAML
205 ---
206 app: popcon
207 default:
208 defname: foobar
209 var: "$var{name} = $args{defname}"
210 load: "! MY_HOSTID=$name"
211
213 This format is intended for more complex script where using "load"
214 instructions is not enough.
215 This script must then begin with "# Format: perl" and specifies a hash.
217 For instance:
218 # Format: perl
220 {
221 app => 'popcon', # mandatory
222 doc => "Use --arg to_store=a_value to store a_value in MY_HOSTID',
223 commit => "control: update Vcs-Browser and Vcs-Git"
224 sub => sub ($root, $arg) { $root->fetch_element('MY_HOSTID')->store($arg->{to_store}); }
225 }
226 $root is the root if the configuration tree (See Config::Model::Node).
228 $arg is a hash containing the arguments passed to "cme run" with "-arg"
229 options.
230 The "sub" parameter value must be a sub ref. Its parameters are $root
232 (a Config::Model::Node object containing the root of the configuration
233 tree) and $arg (a hash ref containing the keys and values passed to
234 "cme run" with "--arg" options).
235 Note that this format does not support "var", "default" and "load"
237 parameters as you can easily achieve the same result with Perl code.
238
240 list
241 List available scripts and exits.
242 arg
244 Arguments for the cme scripts which are used to substitute variables.
245 doc
247 Show the script documentation. (Note that "--help" options show the
248 documentation of "cme run" command)
249 cat
251 Pop the hood and show the content of the script.
252 commit
254 Like the commit instruction in script. Specify that the change must be
255 committed with the passed commit message.
256 no-commit
258 Don't commit to git (even if the above option is set)
259 verbose
261 Show effect of the modify instructions.
262
264 See "Global Options" in cme.
265
267 update copyright years in "debian/copyright"
268 $ cme run update-copyright -cat
269 app: dpkg-copyright
270 load: Files:~ Copyright=~"s/2016,?\s+$name/2017, $name/g"
271 commit: updated copyright year of $name
272 $ cme run update-copyright -arg "name=Dominique Dumont"
274 cme: using Dpkg::Copyright model
275 Changes applied to dpkg-copyright configuration:
276 - Files:"*" Copyright: '2005-2016, Dominique Dumont <dod@debian.org>' -> '2005-2017, Dominique Dumont <dod@debian.org>'
277 - Files:"lib/Dpkg/Copyright/Scanner.pm" Copyright:
278 @@ -1,2 +1,2 @@
279 -2014-2016, Dominique Dumont <dod@debian.org>
280 +2014-2017, Dominique Dumont <dod@debian.org>
281 2005-2012, Jonas Smedegaard <dr@jones.dk>
282 [master ac2e6410] updated copyright year of Dominique Dumont
284 1 file changed, 2 insertions(+), 2 deletions(-)
285 update VcsGit in debian/control
287 $ cme run set-vcs-git -cat
288 doc: update control Vcs-Browser and Vcs-git from git remote value
289 doc: parameters: remote (default is origin)
290 doc:
291 doc: example:
292 doc: cme run set-vcs-git
293 doc: cme run set-vcs-git -arg remote=debian
294 app: dpkg-control
296 default: remote: origin
297 var: chomp ( $var{url} = `git remote get-url $args{remote}` ) ;
299 var: $var{url} =~ s!^git@!https://!;
300 var: $var{url} =~ s!(https?://[\w.]+):!$1/!;
301 var: $var{browser} = $var{url};
302 var: $var{browser} =~ s/.git$//;
303 load: ! source Vcs-Browser="$browser" Vcs-Git="$url"
305 commit: control: update Vcs-Browser and Vcs-Git
306 This script can also be written using multi line instructions:
308 $ cme run set-vcs-git -cat
310 --- doc
311 update control Vcs-Browser and Vcs-git from git remote value
312 parameters: remote (default is origin)
313 example:
315 cme run set-vcs-git
316 cme run set-vcs-git -arg remote=debian
317 ---
318 app: dpkg-control
320 default: remote: origin
321 --- var
323 chomp ( $var{url} = `git remote get-url $args{remote}` ) ;
324 $var{url} =~ s!^git@!https://!;
325 $var{url} =~ s!(https?://[\w.]+):!$1/!;
326 $var{browser} = $var{url};
327 $var{browser} =~ s/.git$//;
328 ---
329 load: ! source Vcs-Browser="$browser" Vcs-Git="$url"
331 commit: control: update Vcs-Browser and Vcs-Git
332
334 cme
335
337 Dominique Dumont
338
340 This software is Copyright (c) 2014-2022 by Dominique Dumont
341 <ddumont@cpan.org>.
342 This is free software, licensed under:
344 The GNU Lesser General Public License, Version 2.1, February 1999
346perl v5.34.0 2022-03-24 App::Cme::Command::run(3)