NAME

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

VERSION

       version 1.026

SYNOPSIS

        $ cat ~/.cme/scripts/remove-mia
        doc: remove mia from Uploders. 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 Uploders. 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 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)

Common options

       See "Global Options" in cme.

Examples

   update copyright years in "debian/copyright"
        $ cat ~/.cme/scripts/update-copyright
        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(-)

SEE ALSO

       cme

AUTHOR

       Dominique Dumont

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2017 by Dominique Dumont.

       This is free software, licensed under:

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