Goals
-----

This section exists to organize files related to shell functionality of centos-art.sh script.

Description
-----------

The shell functionality of centos-art.sh script helps you to maintain bash scripts inside repository. For example, suppose you've created many functionalities for 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 shell functionality exists to solve maintainance tasks just as the one previously mentioned.

When you use shell functionality to update copyright inside script files, it is required that your script files contain (at least) the following top commentary structure:

 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| }
Figure: The functions script base comment structure

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 shell functionality,  the centos-art.sh script replaces everything in-between line 5 ---the first one matching ^# Copyright .+$ string--- and line 9---the first long dash separator matching ^# -+$--- with the content of copyright template instance.

     Caution Be sure to add the long dash separator that matches ^# -+$ regular expression before the function definition. Otherwise, if the Copyright line is present but no long dash separator exists, centos-art.sh will remove anything in-between the Copyright line and the end of file. This way you may lost your function definitions entirely.

The copyright template instance is created from one copyright template stored in the 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 centos-art.sh script takes advantage of automation in order to set copyright full name and date dynamically.

When you use shell functionality to update copyright, the first thing shell functionality does is requesting copyright information to user, and later, if values were left empty (i.e., no value was typed before pressing RET key), the shell functionality uses its own default values.

When shell functionality uses its own default values, the final copyright note looks like the following:

 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| }
Figure: The function script comment example

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 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 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 Config/tpl_forCopyright.sed file, set the appropriate information, and run the shell functionality once again for changes to take effect over the files you specify.

     Important The centos-art.sh script is released as:

     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.

     Do not change the license information under which centos-art.sh script is released. Instead, if you think a different license must be used, please share your reasons at CentOS Developers mailing list.

Usage
-----

centos-art sh --update-copyright='path/to/dir'
centos-art sh --update-copyright='path/to/dir' --filter='regex'
     Use these commands to update copyright information in .sh files under path/to/dir directory.

When you provide --filter='regex' argument, the list of files to process is reduced as specified in regex regular expression. Inside centos-art.sh script, the regex regular expression is used in combination with find command to look for files matching the regular expression path pattern.

     Warning In order for regex regular expression to match a file, the regex regular expresion must match the whole file path not just the file name.

For example, if you want to match all render.conf.sh files inside path/to/dir, use the .+/render.conf regular expression.  Later, centos-art.sh script uses this value inside ^$REGEX\.sh$ expression in order to build the final regular expression (i.e., ^.+/render.conf\.sh$) that is evaluated against available file paths inside the list of files to process.

Exceptionally, when you provide --filter='regex' in the way that regex, appended to path/to/dir/ (i.e. path/to/dir/regex), matches a regular file; the centos-art.sh script uses the file matching as only file in the list of files to process.

See also
--------