App::Cme::Command::run(3pm)

1App::Cme::Command::run(U3s)er Contributed Perl DocumentatAipopn::Cme::Command::run(3)
2
3
4

NAME

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

VERSION

9       version 1.032
10

SYNOPSIS

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
21        $ cme run remove-mia -arg mia=longgone@d3bian.org
22
23        # 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
28        $ 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
35        # show the script documentation
36        $ cme run remove-mia -doc
37        remove mia from Uploaders. require mia parameter
38
39        # list scripts
40        $ cme run -list
41        Available scripts:
42        - update-copyright
43        - add-me-to-uploaders
44

DESCRIPTION

46       Run a script written with cme DSL (Design specific language) or in
47       plain Perl.
48
49       A script passed by name is searched in "~/.cme/scripts",
50       "/etc/cme/scripts" or "/usr/share/perl5/Config/Model/scripts".  E.g.
51       with "cme run foo", "cme" loads either "~/.cme/scripts/foo",
52       "/etc/cme/scripts/foo" or "/usr/share/perl5/Config/Model/scripts/foo"
53
54       No search is done if the script is passed with a path (e.g. "cme run
55       ./foo")
56
57       "cme run" can also run plain Perl script. This is syntactic sugar to
58       avoid polluting global namespace, i.e. there's no need to store a
59       script using cme function in "/usr/local/bin/".
60
61       When run, this script:
62
63       ·   opens the configuration file of "app"
64
65       ·   applies the modifications specified with "load" instructions
66
67       ·   save the configuration files
68
69       ·   commits the result if "commit" is specified (either in script or on
70           command line).
71
72       See App::Cme::Command::run for details.
73

Syntax

75       The script accepts instructions in the form:
76
77        key: value
78
79       The key line can be repeated when needed.
80
81       Multi line values can also be:
82
83        --- key
84        multi line value
85        ---
86
87       The script accepts the following instructions:
88
89       app Specify the target application. Must be one of the application
90           listed by "cme list" command. Mandatory. Only one "app" instruction
91           is allowed.
92
93       var Use Perl code to specify variables usable in this script. The Perl
94           code must store data in %var hash. For instance:
95
96               var: my @l = localtime; $var{year} =  $l[5]+1900;
97
98           The hash %args contains the variables passed with the "-arg"
99           option. Reading a value from %args which is not set by user
100           triggers a missing option error. Use "exists" if you need to test
101           if a argument was set by user:
102
103               var: $var{foo} = exists $var{bar} ? $var{bar} : 'default' # good
104               var: $var{foo} = $var{bar} || 'default' # triggers a "missing arg" error
105
106       load
107           Specify the modifications to apply using a string as specified in
108           Config::Model::Loader. This string can contain variable (e.g. $foo)
109           which are replaced by command argument (e.g. "-arg foo=bar") or by
110           a variable set in var: line (e.g. $var{foo} as set above) or by an
111           environment variable (e.g. $ENV{foo})
112
113       commit
114           Specify that the change must be committed with the passed commit
115           message. When this option is used, "cme" raises an error if used on
116           a non-clean workspace. This option works only with git.
117
118       All instructions can use variables like $stuff whose value can be
119       specified with "-arg" options, with a Perl variable (from "var:"
120       section explained above) or with an environment variable:
121
122       For instance:
123
124         cme run -arg var1=foo -arg var2=bar
125
126       transforms the instruction:
127
128         load: ! a=$var1 b=$var2
129
130       in
131
132         load: ! a=foo b=bar
133

Options

135   list
136       List available scripts and exits.
137
138   arg
139       Arguments for the cme scripts which are used to substitute variables.
140
141   doc
142       Show the script documentation. (Note that "--help" options show the
143       documentation of "cme run" command)
144
145   cat
146       Pop the hood and show the content of the script.
147
148   commit
149       Like the commit instruction in script. Specify that the change must be
150       committed with the passed commit message.
151
152   no-commit
153       Don't commit to git (even if the above option is set)
154
155   verbose
156       Show effect of the modify instructions.
157

Common options

159       See "Global Options" in cme.
160

Examples

162   update copyright years in "debian/copyright"
163        $ cme run update-copyright -cat
164        app: dpkg-copyright
165        load: Files:~ Copyright=~"s/2016,?\s+$name/2017, $name/g"
166        commit: updated copyright year of $name
167
168        $ cme run update-copyright -arg "name=Dominique Dumont"
169        cme: using Dpkg::Copyright model
170        Changes applied to dpkg-copyright configuration:
171        - Files:"*" Copyright: '2005-2016, Dominique Dumont <dod@debian.org>' -> '2005-2017, Dominique Dumont <dod@debian.org>'
172        - Files:"lib/Dpkg/Copyright/Scanner.pm" Copyright:
173        @@ -1,2 +1,2 @@
174        -2014-2016, Dominique Dumont <dod@debian.org>
175        +2014-2017, Dominique Dumont <dod@debian.org>
176          2005-2012, Jonas Smedegaard <dr@jones.dk>
177
178        [master ac2e6410] updated copyright year of Dominique Dumont
179         1 file changed, 2 insertions(+), 2 deletions(-)
180
181   update VcsGit in debian/control
182        $ cme run set-vcs-git  -cat
183        doc: update control Vcs-Browser and Vcs-git from git remote value
184        doc: parameters: remote (default is origin)
185        doc:
186        doc: example:
187        doc:  cme run set-vcs-git
188        doc:  cme run set-vcs-git -arg remote=debian
189
190        app: dpkg-control
191        default: remote: origin
192
193        var: chomp ( $var{url} = `git remote get-url $args{remote}` ) ;
194        var: $var{url} =~ s!^git@!https://!;
195        var: $var{url} =~ s!(https?://[\w.]+):!$1/!;
196        var: $var{browser} = $var{url};
197        var: $var{browser} =~ s/.git$//;
198
199        load: ! source Vcs-Browser="$browser" Vcs-Git="$url"
200        commit: control: update Vcs-Browser and Vcs-Git
201
202       This script can also be written using multi line instructions:
203
204        $ cme run set-vcs-git  -cat
205        --- doc
206        update control Vcs-Browser and Vcs-git from git remote value
207        parameters: remote (default is origin)
208
209        example:
210         cme run set-vcs-git
211         cme run set-vcs-git -arg remote=debian
212        ---
213
214        app: dpkg-control
215        default: remote: origin
216
217        --- var
218        chomp ( $var{url} = `git remote get-url $args{remote}` ) ;
219        $var{url} =~ s!^git@!https://!;
220        $var{url} =~ s!(https?://[\w.]+):!$1/!;
221        $var{browser} = $var{url};
222        $var{browser} =~ s/.git$//;
223        ---
224
225        load: ! source Vcs-Browser="$browser" Vcs-Git="$url"
226        commit: control: update Vcs-Browser and Vcs-Git
227

AUTHOR

232       Dominique Dumont
233

COPYRIGHT AND LICENSE

235       This software is Copyright (c) 2014-2020 by Dominique Dumont.
236
237       This is free software, licensed under:
238
239         The GNU Lesser General Public License, Version 2.1, February 1999
240
241
242
243perl v5.32.0                      2020-07-28         App::Cme::Command::run(3)