Blob Blame History Raw
<sect1 id="scripts-bash-cliref">

    <title>Command-line Interface</title>

    <para>
        The <command>centos-art.sh</command> script follows a
        conventional GNU/Linux command-line interface where there
        might be options and non-option arguments in it. As convention
        to <command>centos-art.sh</command>, the first non-option
        argument passed through the command-line will be the name of
        the specific function you want to execute (e.g., <xref
        linkend="scripts-bash-render" />, <xref
        linkend="scripts-bash-locale" />, <xref
        linkend="scripts-bash-help" />, etc.).  This first argument
        will be immediately removed from the list of arguments passed
        to <command>centos-art.sh</command> script leaving just the
        remaining options and non-option arguments passed to it. From
        this point on, the <command>centos-art.sh</command> script
        uses the <command>getopt</command> command to retrieve option
        arguments and remove them from the list of arguments passed to
        <command>centos-art.sh</command> script.
    </para>

    <para>
        To better understand the <command>centos-art.sh</command>
        command-line interface, consider the command shown in <xref
        linkend="scripts-bash-cliref-example1" />.  This example
        shows the entire command as a list of space-separated
        arguments. Each argument passed in the command-line can be
        reached using positional variables as described in <xref
        linkend="scripts-bash-cliref-implementation-example1" />.
    </para>

    <example id="scripts-bash-cliref-example1">
    <title>The command-line interface</title>
    <screenshot>
    <screeninfo>The command-line interface</screeninfo>
    <mediaobject>
    <textobject>
<programlisting>
centos-art render Identity/Images/Themes --with-brands
</programlisting>
    </textobject>
    </mediaobject>
    </screenshot>
    </example>

    <sect2 id="scripts-bash-cliref-options">
    <title>Option Arguments</title>

    <para>
        As convention inside the <command>centos-art.sh</command>, all
        specific function environments should provide support for the
        following option arguments:
    </para>

    <variablelist>
    <varlistentry>
    <term><option>-h</option> | <option>--help</option></term>
    <listitem>
    <para>
        This option makes <command>centos-art.sh</command> to shows
        information about the specific function environment (e.g., how
        to execute it, available options, etc.) set as first
        non-option argument. For example, if you provide the
        <command>centos-art render --help</command>, the
        <command>centos-art.sh</command> script will display to you
        the information related to <xref linkend="scripts-bash-render"
        /> functionality.
    </para>
    <para>
        This information is retrieved from <quote>The CentOS Artwork
        Repository File System (tcar-fs)</quote> documentation manual.
        This manual is written in Texinfo format and provides a quick
        way for you to read and browse documentation related to each
        directory inside &TCAR; as you work with it from a text
        terminal.
    </para>

    <!--
        Enhancement
        ===========
        At some point, documentation written in Texinfo format will be
        replaced by Docbook format and profiling will be used to reach
        documentation model files which will be also transformed
        automatically based on the output required. In the case of
        centos-art.sh help functionality, man pages will be used as
        default output format.
    -->

    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>-q</option> | <option>--quiet</option></term>
    <listitem>
    <para>
        This option makes the <command>centos-art.sh</command> script
        to suppress messages sent to standard output. This option
        doesn't suppress error messages, nor questions related to
        script execution.
    </para>
    </listitem>
    </varlistentry>

    </variablelist>

    <para>
        The specific option arguments used by function environments
        are described individually, as part of each function
        environment documentation.  To know more about the specific
        options used by function environments, see <xref
        linkend="scripts-bash-cliref-specificfuncs" /> and <xref
        linkend="scripts-bash-cliref-commonfuncs" />.
    </para>

    <table id="scripts-bash-cliref-specificfuncs">
    <title>Specific functions environment</title>
    <tgroup cols="2" align="left">
    <thead>
        <row>
            <entry>Name</entry>
            <entry>Description</entry>
        </row>
    </thead>

    <tbody>
        <row>
            <entry><xref linkend="scripts-bash-prepare" /></entry>
            <entry>Standardize configuration tasks inside &TCAR;</entry>
        </row>
        <row>
            <entry><xref linkend="scripts-bash-render" /></entry>
            <entry>Standardize rendition tasks inside &TCAR;</entry>
        </row>
        <row>
            <entry><xref linkend="scripts-bash-locale" /></entry>
            <entry>Standardize localization tasks inside &TCAR;</entry>
        </row>
        <row>
            <entry><xref linkend="scripts-bash-help" /></entry>
            <entry>Standardize documentation tasks inside &TCAR;</entry>
        </row>
        <row>
            <entry><xref linkend="scripts-bash-pack" /></entry>
            <entry>Standardize packing tasks inside &TCAR;</entry>
        </row>
        <row>
            <entry><xref linkend="scripts-bash-tuneup" /></entry>
            <entry>Standardize maintainance tasks inside &TCAR;</entry>
        </row>
        <row>
            <entry><xref linkend="scripts-bash-vcs" /></entry>
            <entry>Standardize version control tasks inside &TCAR;</entry>
        </row>
    </tbody>
    
    </tgroup>
    </table>

    <table id="scripts-bash-cliref-commonfuncs">
    <title>Common functions environment</title>
    <tgroup cols="2" align="left">
    <thead>
        <row>
            <entry>Name</entry>
            <entry>Description</entry>
        </row>
    </thead>

    <tbody>
        <row>
            <entry>
                <literal>cli_checkFiles</literal>
            </entry>
            <entry>
                Standardize conditional expressions applied to files
                (including links and directories) inside the
                <command>centos-art.sh</command> script.
            </entry>
        </row>
        <row>
            <entry>cli_checkRepoDirSource</entry>
            <entry>
                Standardize directories' path construction inside the
                working copy, using absolute paths.
            </entry>
        </row>
        <row>
            <entry>cli_expandTMarkers</entry>   
            <entry>
                Standardize translation markers construction and their
                related expansion.
            </entry>
        </row>
        <row>
            <entry>cli_exportFunctions</entry>
            <entry>
                Standardize the way specific functionalities are
                exported to <command>centos-art.sh</command> script
                environment.
            </entry>
        </row>
        <row>
            <entry>cli_getConfigLines</entry>
            <entry>
                Standardize the way configuration lines are retrieved
                form configuration files.
            </entry>
        </row>
        <row>
            <entry>cli_getConfigSectionNames</entry>
            <entry>
                Standardize the way section names are retrieved from
                configuration files.
            </entry>
        </row>
        <row>
            <entry>cli_getConfigValue</entry>
            <entry>
                Standardize the way configuration values are retrieved
                from configuration files. 
            </entry>
        </row>
        <row>
            <entry>cli_getFilesList</entry>
            <entry>
                Standardize the way list of files are built inside
                <command>centos-art.sh</command> script.
            </entry>
        </row>
        <row>
            <entry>cli_getPathComponent</entry>
            <entry>
                Standardize the way directory structures are organized
                inside the working copy of &TCAR;.
            </entry>
        </row>
        <row>
            <entry>cli_getRepoName</entry>
            <entry>
                Standardize files and directories name convection
                inside the working copy of &TCAR;.
            </entry>
        </row>
        <row>
            <entry>cli_getTemporalFile</entry>
            <entry>
                Standardize temporal files creation.
            </entry>
        </row>
        <row>
            <entry>cli_parseArgumentsReDef</entry>
            <entry>
                Initiate/reset and sanitize positional parameters
                passed to this function and creates the list of
                arguments that <command>getopt</command> will process.
            </entry>
        </row>
        <row>
            <entry>cli_parseArguments</entry>
            <entry>
                Redefine the <varname>ARGUMENTS</varname> global
                variable using <command>getopt</command> output.
            </entry>
        </row>
        <row>
            <entry>cli_printCopyrightInfo</entry>
            <entry>
                Standardize the copyright information printed on
                content produced by <command>centos-art.sh</command>
                script.
            </entry>
        </row>
        <row>
            <entry>cli_printMailingList</entry>
            <entry>
                Standardize the way mailing list addresses are printed
                on content produced by
                <command>centos-art.sh</command> script.
            </entry>
        </row>
        <row>
            <entry>cli_printMessage</entry>
            <entry>
                Standardize the way messages are printed by
                <command>centos-art.sh</command> script.
            </entry>
        </row>
        <row>
            <entry>cli_printUrl</entry>
            <entry>
                Standardize the way URLs are printed by
                <command>centos-art.sh</command> script. 
            </entry>
        </row>
        <row>
            <entry>cli_runFnEnvironment</entry>
            <entry>
                Standardize the way <command>centos-art.sh</command>
                script is called to itself. 
            </entry>
        </row>
        <row>
            <entry>cli</entry>
            <entry>
                Initiates the <command>centos-art.sh</command> script
                command-line interface.
            </entry>
        </row>
        <row>
            <entry>cli_synchronizeRepoChanges</entry>
            <entry>
                Standardize the way changes are synchronized between
                the working copy and the central repository. 
            </entry>
        </row>
        <row>
            <entry>cli_terminateScriptExecution</entry>
            <entry>
                Standardize the actions that must be realized just
                before leaving the script execution (e.g., cleaning
                temporal files).
            </entry>
        </row>
        <row>
            <entry>cli_unsetFunctions</entry>
            <entry>
                Unset functionalities from
                <command>centos-art.sh</command> script execution
                environment.
            </entry>
        </row>

    </tbody>
    
    </tgroup>
    </table>

    </sect2>

    <sect2>
    <title>Non-Option Arguments</title>

    <para>
        Once option arguments have been removed from the list of
        arguments passed to <command>centos-art.sh</command>
        command-line, non-option arguments are processed then.
        Non-option arguments will always be paths pointing to
        directories inside your working copy of &TCAR; or
        documentation entries pointing to specific sections in a
        documentation manual. Paths provided in the command-line can
        be absolute or relative considering the root directory of the
        working copy as start point.  For example, both the absolute
        path <quote><filename
        class="directory">${HOME}/Projects/CentOS/artwork/Identity/Themes/</filename></quote>
        and the relative path <quote><filename
        class="directory">Identity/Themes</filename></quote> point to
        the same location. Documentation entries, on the other hand,
        exist to specify the files inside the <quote><filename
        class="directory">Documentation/Models/</filename></quote>
        directory structure you want to work with, based on specific
        documentation manual components (e.g., manual name, part,
        chapter or section). To know more about documentation entries,
        see the <xref linkend="scripts-bash-help"/> functionality
        reference.
    </para>

    </sect2>

    <sect2 id="scripts-bash-cliref-implementation">

        <title>Implementation</title>

        <para>
            The command-line interface of
            <command>centos-art.sh</command> script is implemented
            individually for each specific function environments it is
            made of. Each specific function environment inside the
            <command>centos-art.sh</command> has its own command-line
            definition and can differ in options when they are
            compared one another. The command-line differences between
            specific function environments exist as consequence of the
            purpose they were designed for (e.g., different purposes,
            different options and arguments).  Nevertheless, all
            specific function environments use the same base
            construction to implement their unique command-line
            interfaces (see <xref
            linkend="scripts-bash-cliref-implementation-example1" />).
        </para>

        <para>
            The specific function environments the
            <command>centos-art.sh</command> script is made of use the
            <quote><filename>Scripts/Bash/Functions/<replaceable>Fname</replaceable>/<replaceable>fname</replaceable>_getOptions.sh</filename></quote>
            file to store the
            <function><replaceable>fname</replaceable>_getOptions</function>
            function definition. This function definition is where you
            set the relation between actions to be executed and
            arguments passed to <command>centos-art.sh</command>
            script.  
        </para>
        
        <para>
            Basically, when you decide to create new function
            environments for the <command>centos-art.sh</command>
            script, you need to consider whether they will use
            arguments from the command-line or not. When the function
            environment doesn't need arguments (e.g., it exists to
            redefine values related to variables only) there is not
            need to consider a parsing feature for it.  However, when
            you need to interact with a specific function through the
            command-line, you should use the
            <function><replaceable>fname</replaceable>_getOptions</function>
            function related to your
            <function><replaceable>fname</replaceable></function>
            function environment to define the way such interaction
            will take place.  This way you can control the possible
            arguments your function environment will be able to
            interpret from the command-line. 
        </para>

    <example id="scripts-bash-cliref-implementation-example1">
    <title>The command-line implementation</title>
    <screenshot>
    <screeninfo>The command-line implementation</screeninfo>
    <mediaobject>
    <textobject>
<programlisting>
function <replaceable>fname</replaceable>_getOptions {

    # Define short options we want to support.
    local ARGSS="h,q"

    # Define long options we want to support.
    local ARGSL="help,quiet"

    # Redefine ARGUMENTS using getopt(1) command parser.
    cli_parseArguments

    # Redefine positional parameters using ARGUMENTS variable.
    eval set -- "$ARGUMENTS"

    # Look for options passed through command-line.
    while true; do

        case "$1" in

            -h | --help )
                cli_runFnEnvironment help --read --format="texinfo" "tcar-fs::scripts:bash-functions-<replaceable>fname</replaceable>"
                shift 1
                exit
                ;;

            -q | --quiet )
                FLAG_QUIET="true"
                shift 1
                ;;

            -- )
                # Remove the `--' argument from the list of arguments
                # in order for processing non-option arguments
                # correctly. At this point all option arguments have
                # been processed already but the `--' argument still
                # remains to mark ending of option arguments and
                # beginning of non-option arguments. The `--' argument
                # needs to be removed here in order to avoid
                # centos-art.sh script to process it as a path inside
                # the repository, which obviously is not.
                shift 1
                break
                ;;
        esac
    done

    # Redefine ARGUMENTS variable using current positional parameters. 
    cli_parseArgumentsReDef "$@"

}
</programlisting>
</textobject>
</mediaobject>
</screenshot>
</example>

        <para>
            Using the base structure described in <xref
            linkend="scripts-bash-cliref-implementation-example1"/>, you can
            create new options so your specific function environment
            can express its usefulness.  For example, if you want your
            specific function environment to print a greeting on the
            screen when the <option>--hello</option> option is passed
            through its command-line, you can modify the base
            structure shown above with the following:
        </para>

<programlisting>
...

    # Define long options we want to support.
    local ARGSL="help,quiet,hello"

...

            --hello )
                cli_printMessage "`gettext "Hello World!"`"
                shift 1
                ;;
...
</programlisting>

    <para>
        In case you want to provide an option value in the form
        <option>--hello="World"</option>, you can do it as described
        below:
    </para>

<programlisting>
...

    # Define long options we want to support.
    local ARGSL="help,quiet,hello:"

...

            --hello )
                cli_printMessage "`gettext "Hello"` ${2}"
                shift 2
                ;;
...
</programlisting>

    <para>
        In this last case, the option value is required. So, if you
        provide the <option>--hello</option> option but do not provide
        a value for it, an error will be triggered and the script will
        finish its execution. To make an option value not-required,
        you need to use two colons instead of one when you define the
        options, see the following lines: 
    </para>

<programlisting>
...

    # Define long options we want to support.
    local ARGSL="help,quiet,hello::"

...

            --hello )
                cli_printMessage "`gettext "Hello"` ${2}"
                shift 2
                ;;
...
</programlisting>

    <para>
        To know more about the features provided by
        <command>getopt</command> command, read its man page (e.g.,
        typing the <command>man getopt</command> command in your
        terminal). This information will also help you to understand
        how to improve the command-line interfaces you create for
        the function environments of <command>centos-art.sh</command>
        script.
    </para>

    </sect2>

</sect1>