@subsection Goals

This section exists to organize files related to @code{shell}

functionality of @file{centos-art.sh} script.

@subsection Description

The @code{shell} functionality of @file{centos-art.sh} script helps

you to maintain bash scripts inside repository. For example, suppose

you've created many functionalities for @file{centos-art.sh} script,

and you want to use a common copyright and license note for

consistency in all your script files. If you have a bunch of files,

doing this one by one wouldn't be a big deal. In contrast, if the

amount of files grows, updating the copyright and license note for all

of them would be a task rather tedious. The @code{shell} functionality

exists to solve maintainance tasks just as the one previously

mentioned.

When you use @code{shell} functionality to update copyright inside

script files, it is required that your script files contain (at least)

the following top commentary structure:

@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:1

@verbatim

 1| #!/bin/bash

 2| #

 3| # doSomething.sh -- The function description goes here.

 4| # 

 5| # Copyright

 6| #

 7| # ...

 8| #

 9| # ----------------------------------------------------------------------

10| # $Id$

11| # ----------------------------------------------------------------------

12|

13| function doSomething {

14|     

15| }

@end verbatim

@caption{The functions script base comment structure}

@end float

Relevant lines in the above structure are lines from 5 to 9.

Everything else in the file is left immutable.

When you are updating copyright through @code{shell}

functionality,  the @file{centos-art.sh} script replaces everything

in-between line 5 ---the first one matching @samp{^# Copyright .+$}

string--- and line 9---the first long dash separator matching @samp{^#

-+$}--- with the content of copyright template instance.

@quotation

@strong{Caution} Be sure to add the long dash separator that matches

@samp{^# -+$} regular expression @emph{before} the function

definition. Otherwise, if the @samp{Copyright} line is present but no

long dash separator exists, @file{centos-art.sh} will remove anything

in-between the @samp{Copyright} line and the end of file. This way you

may lost your function definitions entirely.

@end quotation

The copyright template instance is created from one copyright template

stored in the @file{Config/tpl_forCopyright.sed} file.  The template

instance is created once, and later removed when no longer needed. At

this moment, when template instance is created, the

@file{centos-art.sh} script takes advantage of automation in order to

set copyright full name and date dynamically.

When you use @code{shell} functionality to update copyright, the first

thing @file{shell} functionality does is requesting copyright

information to user, and later, if values were left empty (i.e., no

value was typed before pressing @key{RET} key), the @file{shell}

functionality uses its own default values.

When @code{shell} functionality uses its own default values, the final

copyright note looks like the following:

@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:2

@verbatim

 1| #!/bin/bash

 2| #

 3| # doSomthing.sh -- The function description goes here.

 4| #

 5| # Copyright (C) 2003, 2010 The CentOS Project

 6| # 

 7| # This program is free software; you can redistribute it and/or modify

 8| # it under the terms of the GNU General Public License as published by

 9| # the Free Software Foundation; either version 2 of the License, or

10| # (at your option) any later version.

11| # 

12| # This program is distributed in the hope that it will be useful, but

13| # WITHOUT ANY WARRANTY; without even the implied warranty of

14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

15| # General Public License for more details.

16| #

17| # You should have received a copy of the GNU General Public License

18| # along with this program; if not, write to the Free Software

19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307

20| # USA.

21| #

22| # ----------------------------------------------------------------------

23| # $Id$

24| # ----------------------------------------------------------------------

25|

26| function doSomething {

27|

28| }

@end verbatim

@caption{The function script comment example}

@end float

Relevant lines in the above structure are lines from 5 to 22.  Pay

attention how the copyright line was built, and how the license was

added into the top comment where previously was just three dots.

Everything else in the file was left immutable. 

To change copyright information (i.e., full name or year information),

run the @code{shell} functionality over the root directory containing

the script files you want to update copyright in and enter the

appropriate information when it be requested. You can run the

@code{shell} functionality as many times as you need to.

To change copyright license (i.e., the text in-between lines 7 and

20), you need to edit the @file{Config/tpl_forCopyright.sed} file, set

the appropriate information, and run the @code{shell} functionality

once again for changes to take effect over the files you specify.

@quotation

@strong{Important} The @file{centos-art.sh} script is released as: 

@verbatim

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.

59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

@end verbatim

Do not change the license information under which @file{centos-art.sh}

script is released. Instead, if you think a different license must be

used, please share your reasons at @email{centos-devel@@centos-art.sh,

CentOS Developers mailing list}.

@end quotation

@subsection Usage

@table @command

@item centos-art sh --update-copyright='path/to/dir'

@itemx centos-art sh --update-copyright='path/to/dir' --filter='regex'

Use these commands to update copyright information in @samp{.sh} files

under @samp{path/to/dir} directory. 

@end table

When you provide @option{--filter='regex'} argument, the list of files

to process is reduced as specified in @samp{regex} regular expression.

Inside @file{centos-art.sh} script, the @samp{regex} regular

expression is used in combination with @command{find} command to look

for files matching the regular expression path pattern.

@quotation

@strong{Warning} In order for @samp{regex} regular expression to match

a file, the @samp{regex} regular expresion must match the whole file

path not just the file name. 

@end quotation

For example, if you want to match all @file{render.conf.sh} files

inside @file{path/to/dir}, use the @code{.+/render.conf} regular

expression.  Later, @file{centos-art.sh} script uses this value inside

@code{^$REGEX\.sh$} expression in order to build the final regular

expression (i.e., @code{^.+/render.conf\.sh$}) that is evaluated

against available file paths inside the list of files to process.

Exceptionally, when you provide @option{--filter='regex'} in the way

that @samp{regex}, appended to @samp{path/to/dir/} (i.e.

@samp{path/to/dir/regex}), matches a regular file; the

@file{centos-art.sh} script uses the file matching as only file in the

list of files to process. 

@subsection See also

@menu

* trunk Scripts Bash::

* trunk Scripts Bash Functions::

@end menu