<sect1 id="scripts-bash-funref">
<title>Environment Functions Reference</title>
<para>
In addition to environment variables described above, the
centos-art.sh script makes available the following common
environment functions once it is executed:
</para>
<variablelist>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_checkFiles" xreflabel="cli_checkFiles">cli_checkFiles</command>
<arg choice="req">
<arg>-d</arg>
<arg>-e</arg>
<arg>-f</arg>
<arg>-h</arg>
<arg>-x</arg>
</arg>
<arg choice="req" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_checkFiles</function> standardizes the way
files are verified inside the centos-art.sh script. It tries
to answers questions like <emphasis>Is
<replaceable>LOCATION</replaceable> a regular file or
directory?</emphasis> or even, <emphasis>does
<replaceable>LOCATION</replaceable> have execution
rights?</emphasis>. You can provide several
<replaceable>LOCATION</replaceable> arguments to this function
in order to perform the verifications over them. Likewise, you
can combine different options to realize different
verifications over the same files. In case the verification
fails, an error message is printed and the script finishes its
execution.
</para>
<para>
The <function>cli_checkFiles</function> is an interface for
the <command>test</command> command and accepts the following
options:
</para>
<variablelist>
<varlistentry>
<term><option>-d</option></term>
<listitem>
<para>
Verifies whether <replaceable>LOCATION</replaceable> exists
and is a directory. If it doesn't exists or isn't a directory,
an error message is printed and the script finishes its
execution. Otherwise, if it exists and is a directory, the
script continues its execution normally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option></term>
<listitem>
<para>
Verifies whether <replaceable>LOCATION</replaceable> exists or
not. If it doesn't exist, an error message is printed and the
script finishes its execution. Otherwise, if it does exists,
the script continues its execution normally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>
Verifies whether <replaceable>LOCATION</replaceable> exists
and is a regular file. If it doesn't exists or isn't a regular
file, an error message is printed and the script finishes its
execution. Otherwise, if it exists and is a regular file, the
script continues its execution normally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option></term>
<listitem>
<para>
Verifies whether <replaceable>LOCATION</replaceable> exists
and is a symbolic link. If it doesn't exists or isn't a
symbolic link, an error message is printed and the script
finishes its execution immediately. Otherwise, if it does
exist and is a symbolic link, the script continue its
execution normally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option></term>
<listitem>
<para>
Verifies whether <replaceable>LOCATION</replaceable> exists
and execution permission is granted. If it doesn't exist or
hasn't execution permission, the script finishes its execution
immediately. Otherwise, if it exists and has execution
permissions, the script continues its execution normally.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Use the <function>cli_checkFiles</function> function whenever
you need to verify files inside the &TCAR;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_checkRepoDirSource" xreflabel="cli_checkRepoDirSource">cli_checkRepoDirSource</command>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_checkRepoDirSource</function> function
standardizes the path construction to directories inside it
the working copy, using absolute paths. This function
transforms relative paths passed as non-option arguments to
<command>centos-art.sh</command> script command-line into
absolute paths inside the working copy and verifies whether
they really exist as directories inside the working copy or
not. If the path provided doesn't exist as directory inside
the working copy, the script will finish its execution
immediately with an error message. Otherwise, if the directory
exists, the variable <varname>ACTIONVAL</varname> is redefined
with the related absolute path for further use.
</para>
<para>
Use the <function>cli_checkRepoDirSource</function> function
whenever you need to be sure that non-option arguments passed
to <command>centos-art.sh</command> script command-line will
always point to directories inside the working copy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_expandTMarkers" xreflabel="cli_expandTMarkers">cli_expandTMarkers</command>
<arg choice="req"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_expandTMarkers</function> standardizes
construction of translation markers and their related
expansion. As convention, translation markers are set inside
source files (e.g., DocBook, SVG) and expanded inside temporal
instances used to produce final contents. The
<replaceable>LOCATION</replaceable> argument should point to
the temporal file where translation markers expansion takes
place in.
</para>
<para>
Translation markers written in source files must comply the
<literal>=[A-Z_]+=</literal> regular expression pattern. For
example, <literal>=UNKNOWN_MARKER=</literal> is a valid
translation marker without any replacement. To prevent
<command>centos-art.sh</command> script from expanding
translation markers, add a backslash (<literal>\</literal>)
between the first equal sign and the following letter. For
example, <literal>=\...=</literal> won't be expanded.
</para>
<para>
The <function>cli_expandTMarkers</function> supports the
following translation markers:
</para>
<variablelist>
<varlistentry>
<term><literal>=\COPYRIGHT_YEAR_LAST=</literal></term>
<term><literal>=\COPYRIGHT_YEAR=</literal></term>
<listitem>
<para>
These translation markers expand to the last year used in
copyright notes. For example,
<literal>=COPYRIGHT_YEAR_LAST=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\COPYRIGHT_YEAR_LIST=</literal></term>
<term><literal>=\COPYRIGHT_YEARS_LIST=</literal></term>
<listitem>
<para>
This translation markers expand to the list of years used in
copyright notes. For example,
<literal>=COPYRIGHT_YEARS_LIST=</literal>. The first year
represents the time we began to work on &TCAR;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\COPYRIGHT_HOLDER=</literal></term>
<listitem>
<para>
This translation marker expands to the holder used in
copyright notes. For example,
<literal>=COPYRIGHT_HOLDER=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\COPYRIGHT_HOLDER_PREDICATE=</literal></term>
<listitem>
<para>
This translation marker expands both the holder and the
predicate used in copyright notes. For example,
<literal>=COPYRIGHT_HOLDER_PREDICATE=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\BRAND=</literal></term>
<listitem>
<para>
This translation marker expands to the brand name used on
files names and URLs inside &TCAR;. For example,
<literal>=BRAND=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\LICENSE=</literal></term>
<listitem>
<para>
This translation marker expands to the license information
used in files created by <command>centos-art.sh</command>
script. For example, <literal>=LICENSE=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\LICENSE_URL=</literal></term>
<listitem>
<para>
This translation marker expands to the license URL used in
files created by <command>centos-art.sh</command> script. For
example, <literal>=LICENSE_URL=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\THEME=</literal></term>
<listitem>
<para>
This translation marker expands to the theme portion of path
you are producing through centos-art.sh script. As
consequence, this translation marker should be used in
situations where you are producing theme components only.
This translation marker expands its value by retrieving the
theme part of the path you provide as non-option argument to
<command>centos-art.sh</command> script. For example, if you
provide the path
<filename>trunk/Identity/Images/Themes/Modern/2/Distro/5</filename>,
this translation will expand to the
<literal>Modern/2/</literal> value.
</para>
<para>
In case you need to retrieve the theme name or version
separately one another, then you can use the
<literal>=\THEMENAME=</literal> and
<literal>=\THEMERELEASE=</literal> translation markers,
respectively. When you use these translation markers, forward
slashes are removed from result. So, if you provide the path
<filename>trunk/Identity/Images/Themes/Modern/2/Distro/5</filename>,
<literal>=\THEMENAME=</literal> will expand to
<literal>Modern</literal> and
<literal>=THEMERELEASE=</literal> will expand to
<literal>2</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\RELEASE=</literal></term>
<listitem>
<para>
This translation marker expands to the current release
information of your CentOS distribution. By default this
information is retrieved from
<filename>/etc/redhat-release</filename>. In case the option
<option>--release</option> be passed, the value specified with
it will overwrite the default value and will be this the one
used as reference for this translation marker to retrieve the
release information. So, for example, if you are running a
CentOS-5.8 distribution and no <option>--release</option>
option is passed to <command>centos-art.sh</command> script,
this translation marker expands to <literal>5.8</literal>. On
the other hand, if you are still running a CentOS-5.8
distribution but provide the <option>--release=6.3</option>
option to <command>centos-art.sh</command> script, this
translation marker expands to <literal>6.3</literal> instead.
</para>
<para>
In case you need to retrieve minor and major release numbers
separately one another, then you can use the
<literal>=\MINOR_RELEASE=</literal> and
<literal>=\MAJOR_RELEASE=</literal> translation makers,
respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\ARCH=</literal></term>
<listitem>
<para>
This translation marker expands to the current architecture of
your CentOS Distribution. By default this information is
retrieved from <command>uname -i</command>. In case the option
<option>--arch</option> be passed, the value specified with it
will overwrite the default value and will be the one used as
reference. For example, if the <command>uname -i</command>
outputs the line <computeroutput>i386</computeroutput>, this
translation marker will expand to <literal>i386</literal>. On
the other hand, if you pass the <option>--arch=x86_64</option>
option to <command>centos-art.sh</command> script, this
translation marker will expand to <literal>x86_64</literal>
instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\URL=</literal></term>
<listitem>
<para>
This translation marker expands to the URL which points to
&TCP; home page. For example, <literal>=URL=</literal>. In
case you are using the centos-art.sh script in a different
locale but English (<literal>en_US.UTF-8</literal>), this
translation marker expands as usual but with the language
information appended to the end of the string. For example, if
you are executing the centos-art.shscript for Spanish locale
(e.g., <literal>es_ES.UTF-8</literal>), this translation
marker expands to <literal>=URL=es/</literal>.
</para>
<para>
In case you need to expand other URL related to &TCP; domain,
use translation markers described in <xref
linkend="scripts-bash-funref-expandTMarkers-Url" />. Likewise
=\URL=, translation markers described in <xref
linkend="scripts-bash-funref-expandTMarkers-Url" /> does
append the current language information to the end of the URL
string based on the locale information you are currently
executing the <command>centos-art.sh</command> script.
</para>
<table id="scripts-bash-funref-expandTMarkers-Url">
<title>URL-related translation markers</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Translation Marker</entry>
<entry>Expands To</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>=\URL_WIKI=</literal></entry>
<entry><literal>=URL_WIKI=</literal></entry>
</row>
<row>
<entry><literal>=\URL_LISTS=</literal></entry>
<entry><literal>=URL_LISTS=</literal></entry>
</row>
<row>
<entry><literal>=\URL_FORUMS=</literal></entry>
<entry><literal>=URL_FORUMS=</literal></entry>
</row>
<row>
<entry><literal>=\URL_MIRRORS=</literal></entry>
<entry><literal>=URL_MIRRORS=</literal></entry>
</row>
<row>
<entry><literal>=\URL_DOCS=</literal></entry>
<entry><literal>=URL_DOCS=</literal></entry>
</row>
<row>
<entry><literal>=\URL_PROJECTS=</literal></entry>
<entry><literal>=URL_PROJECTS=</literal></entry>
</row>
<row>
<entry><literal>=\URL_SVN=</literal></entry>
<entry><literal>=URL_SVN=</literal></entry>
</row>
<row>
<entry><literal>=\URL_TRAC=</literal></entry>
<entry><literal>=URL_TRAC=</literal></entry>
</row>
<row>
<entry><literal>=\URL_PLANET=</literal></entry>
<entry><literal>=URL_PLANET=</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\MAIL_DOCS=</literal></term>
<listitem>
<para>
This translation marker expands to CentOS documentation
mailing list address. For example,
<literal>=MAIL_DOCS=</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\LOCALE=</literal></term>
<listitem>
<para>
This translation marker expands to the current locale
information used by <command>centos-art.sh</command> script.
This value is retrieved from the <envar>LANG</envar>
environment variable and should look like
<literal>=LOCALE=</literal>. In case you need to retrieve the
language and country part separately one another, you can use
the <literal>=\LOCALE_LL=</literal> and
<literal>=\LOCALE_CC=</literal>, respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\REPO_TLDIR=</literal></term>
<listitem>
<para>
This translation marker expands to the absolute path to
<filename class="directory">trunk/</filename> directory inside
your workstation. For example,
<literal>/home/al/Projects/CentOS/artwork/trunk</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>=\REPO_HOME=</literal></term>
<term><literal>=\TCAR_WORKDIR=</literal></term>
<listitem>
<para>
This translation marker expands to the absolute path of your
working copy. For example,
<literal>/home/al/Projects/CentOS/artwork</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
See also: <xref linkend="cli_getTemporalFile" />
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_exportFunctions" xreflabel="cli_exportFuncations">cli_exportFunctions</command>
<arg choice="req"><replaceable>EXPORTID</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_exportFunctions</function> function
standardizes the way specific functionalities are exported to
<command>centos-art.sh</command> script execution environment.
The <replaceable>EXPORTID</replaceable> argument points the
specific function initialization file relatively from
<filename>trunk/Scripts/Bash/Functions</filename> directory
on. For example, if we want to export the
<function>render</function> specific functionality, we use the
following construction:
</para>
<programlisting>
cli_exportFunctions "Render/render"
</programlisting>
<para>
In this construction, <literal>Render</literal> with the first
letter in upper case is the name of the directory under
<filename
class="directory">trunk/Scripts/Bash/Functions</filename>
where the specific functionality is stored in, and
<literal>render</literal> with all letters in lower case is
the name of the specific functionality we want to export,
without its extension. This name is also used as suffix to
identify all files related to the specific functionality we
are exporting to <command>centos-art.sh</command> script
execution environment.
</para>
<para>
See also: <xref linkend="cli_unsetFunctions" />
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_getConfigLines" xreflabel="cli_getConfigLines">cli_getConfigLines</command>
<arg choice="req"><replaceable>FILE</replaceable></arg>
<arg choice="req"><replaceable>SECTION</replaceable></arg>
<arg choice="req"><replaceable>OPTION</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_getConfigLines</function> function
standardizes the way configuration lines are retrieved from
configuration files.
</para>
<para>
The <function>cli_getConfigLines</function> function accepts
the following arguments:
</para>
<variablelist>
<varlistentry>
<term><replaceable>FILE</replaceable></term>
<listitem>
<para>
This argument specifies the absolute path to the configuration
file you want to retrieve configuration lines from. For
example,
<quote><filename>${TCAR_WORKDIR}/trunk/Identity/Models/Themes/Default/Distro/5/Anaconda/branding.conf</filename></quote>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>SECTION</replaceable></term>
<listitem>
<para>
This argument specifies the name of the section you want to
retrieve configuration lines from. For example,
<quote>symbols</quote> without brackets.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>OPTION</replaceable></term>
<listitem>
<para>
This argument specifies the name of the option related to the
configuration line you want to retrieve. For example,
<quote>anaconda_header.svgz</quote>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
In order for <function>cli_getConfigLines</function> to work
properly, the configuration files must have a section line
with the form <literal>[sectionname]</literal> which groups
several <literal>option = "value"</literal> lines.
Lines beginning with <literal>#</literal> are ignored and can
be used for comments.
</para>
<example id="cli_getConfigLines-conffile">
<title>Configuration file used to produce Tcar-fs documentation manual</title>
<screenshot>
<screeninfo>Configuration used to produce Tcar-fs documentation manual</screeninfo>
<mediaobject>
<textobject>
<programlisting>
[main]
# Specify documentation backend used by documentation manual.
manual_format = "texinfo"
# Specify title style used by sections inside the manual.
manual_section_style = "directory"
# Specify the order used by sections inside the manual.
manual_section_order = "ordered"
[templates]
# Specify relation between template files and section definition files
# inside the manual.
Chapters/section-functions.texinfo = "^.+-functions-[[:alnum:]]+\.texinfo$"
Chapters/section.texinfo = "^.+\.texinfo$"
</programlisting>
</textobject>
</mediaobject>
</screenshot>
</example>
<para>
The section names and option names used inside configuration
files can be anything. It depends on the use and
interpretation programmed inside
<command>centos-art.sh</command> script for specific purposes
which defines what kind of section and options must exist
inside a configuration file. For example, consider the
configuration files used by <function>render</function>
functionality. They follow the same structure used in
documentation configuration files but the meaning of their
sections and options change to fit the specific needs of
<function>render</function> functionality.
</para>
<example id="cli_getConfigLines-conffile-2">
<title>Configuration file used to produced Anaconda images</title>
<screenshot>
<screeninfo>Configuration used to produced Anaconda images</screeninfo>
<mediaobject>
<textobject>
<programlisting>
[types]
anaconda_header.svgz = "Types/White/48/=\BRAND=-5.png:x48+20+20"
first.svgz = "Types/White/32/=\BRAND=-5.png:x32+30+219"
splash.svgz = "Types/White/48/=\BRAND=-5-msg.png:x48+30+138"
[symbols]
anaconda_header.svgz = "Symbols/48/=\BRAND=.png:x48+732+20"
first.svgz = "Symbols/48/=\BRAND=.png:x48+30+20"
splash.svgz = "Symbols/48/=\BRAND=.png:x48+30+20"
</programlisting>
</textobject>
</mediaobject>
</screenshot>
</example>
<para>
Use the <function>cli_getConfigLines</function> function when
you need to retrieve <literal>option = "value"</literal> lines
from configuration files in a controlled way.
</para>
<para>
See also: <xref linkend="cli_getConfigValue" />
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_getConfigValue" xreflabel="cli_getConfigValue">cli_getConfigValue</command>
<arg choice="req"><replaceable>FILE</replaceable></arg>
<arg choice="req"><replaceable>SECTION</replaceable></arg>
<arg choice="req"><replaceable>OPTION</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_getConfigValue</function> function
standardizes the way option values are retrieved from
configuration files. As convention,
<function>cli_getConfigValue</function> uses the output
produced by <function>cli_getConfigLines</function> as input
to retrieve the option values. As convention, in
<literal>option = "value"</literal> lines, the values
retrieved are always on the right side. The values retrieved
are also output without quotation and translation markers
already expanded.
</para>
<para>
The <function>cli_getConfigValue</function> function accepts
the following arguments:
</para>
<variablelist>
<varlistentry>
<term><replaceable>FILE</replaceable></term>
<listitem>
<para>
This argument specifies the absolute path to the configuration
file you want to retrieve the value from. For example,
<quote><filename>${TCAR_WORKDIR}/trunk/Identity/Models/Themes/Default/Distro/5/Anaconda/branding.conf</filename></quote>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>SECTION</replaceable></term>
<listitem>
<para>
This argument specifies the name of the section related to the
configuration line you want to retrieve the value from. For
example, <quote>symbols</quote> without brackets.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>OPTION</replaceable></term>
<listitem>
<para>
This argument specifies the name of the option you want to
retrieve the value from. For example, in <xref
linkend="cli_getConfigLines-conffile-2" />, the
<quote><literal>anaconda_header.svgz</literal></quote> option will output the
<quote><literal>Symbols/48/=\BRAND=.png:x48+732+20</literal></quote> value
without quotation and translation markers expanded. So if the
value of <envar>TCAR_BRAND</envar> environment variable is
<quote><literal>centos</literal></quote>, the real value you
get will be
<quote><literal>Symbols/48/centos.png:x48+732+20</literal></quote>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Use the <function>cli_getConfigValue</function> function
whenever you want to retrieve values from configuration files
in a controlled way.
</para>
<para>
See also: <xref linkend="cli_getConfigLines" />
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_getFilesList" xreflabel="cli_getFilesList">cli_getFilesList</command>
<arg choice="opt">--pattern</arg>
<arg choice="opt">--mindepth</arg>
<arg choice="opt">--maxdepth</arg>
<arg choice="opt">--type</arg>
<arg choice="opt">--uid</arg>
<arg choice="req" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_getFilesList</function> standardizes the way
list of files are built inside the
<command>centos-art.sh</command> script. This function outputs
a sorted and unique list of files based on the options and
location provided as argument. This function is an interface
to the <command>find</command> command. Don't use
<command>find</command> command directly inside the
centos-art.sh script. Instead, use the
<function>cli_getFilesList</function> function.
</para>
<para>
The <function>cli_getFilesList</function> accepts the
following arguments:
</para>
<variablelist>
<varlistentry>
<term><replaceable>LOCATION</replaceable></term>
<listitem>
<para>
This arguments must be the absolute path to a directory and
specifies where the search of files in any form (e.g.,
directories, links, etc.) will take place in. If
<replaceable>LOCATION</replaceable> isn't a directory, the
script finishes its execution with an error message.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The <function>cli_getFilesList</function> accepts the
following options:
</para>
<variablelist>
<varlistentry>
<term><option>--pattern="<replaceable>REGEX</replaceable>"</option></term>
<listitem>
<para>
This option specifies a posix-egrep type regular expression as
value. This regular expression is applied to path specified in
<replaceable>LOCATION</replaceable> argument. Only file paths
that match this regular expression inside
<replaceable>LOCATION</replaceable> directory will be included
in the final list of files. By default, if this option is not
provided, the
<quote><literal>^/.*[[:alnum:]_/-]+$</literal></quote> regular
expression is used.
</para>
<para>
When you use the <function>cli_getFilesList</function> you
don't need to specified the absolute path of files you want to
look for. This is something
<function>cli_getFilesList</function> already does for you.
When you use this function, the value you pass as regular
expression isn't the final regular expression used. Instead,
the regular expression you pass is used to build the final
regular expression passed to <command>find</command> command.
The final regular expression passed to find is
<quote><literal>^/.*${PATTERN}$</literal></quote>, where
<literal>${PATTERN}</literal> is the value you passed to
<option>--pattern</option> option as
<replaceable>REGEX</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--mindepth="<replaceable>NUMBER</replaceable>"</option></term>
<listitem>
<para>
This option specifies the minimal
<replaceable>NUMBER</replaceable> of levels deep the search
should go under the directory
<replaceable>LOCATION</replaceable> specified. For example, if
you specify <option>--mindepth="2"</option> the search will
start two levels deep considering the path provided as
reference.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--maxdepth="<replaceable>NUMBER</replaceable>"</option></term>
<listitem>
<para>
This option specifies the maximum
<replaceable>NUMBER</replaceable> of levels deep the search
should go under the directory
<replaceable>LOCATION</replaceable> specified. For example, if
you specify <option>--maxdepth="2"</option> the search will
begin in the very same directory path you provided as
<replaceable>LOCATION</replaceable> and stop two levels deep
using it as reference.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--type="<replaceable>STRING</replaceable>"</option></term>
<listitem>
<para>
This option specifies the type of files being searched. This
option accepts the same values the <command>find</command>
<option>-type</option> option does. However, the following
<replaceable>STRING</replaceable> values are the most used
inside the script so far:
</para>
<itemizedlist>
<listitem>
<para>
d — directory.
</para>
</listitem>
<listitem>
<para>
f — regular file.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--uid="<replaceable>NUMBER</replaceable>"</option></term>
<listitem>
<para>
This option specifies the numeric user id of the files you
want to search. Only files that match this numeric user id
will be added to the final list of files.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Use the <function>cli_getFilesList</function> whenever you
need to build list of files for further processing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_synchronizeRepoChanges" xreflabel="cli_synchronizeRepoChanges">cli_synchronizeRepoChanges</command>
<arg choice="req"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_synchronizeRepoChanges</function>
standardizes the way changes are synchronized between the
working copy and the central repository using
<replaceable>LOCATION</replaceable> as reference. This
function is the interface we use inside the
<command>centos-art.sh</command> script to execute the
<function>Svn</function> functionality described in <xref
linkend="scripts-bash-svn" />.
</para>
<para>
Use <function>cli_synchronizeRepoChanges</function> function
inside the <command>centos-art.sh</command> script whenever
you need to synchronize one or more changes at any
<replaceable>LOCATION</replaceable> inside the working copy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_printMessage" xreflabel="cli_printMessage">cli_printMessage</command>
<arg choice="req"><replaceable>MESSAGE</replaceable></arg>
<group choice="opt">
<arg>--as-separator-line</arg>
<arg>--as-banner-line</arg>
<arg>--as-cropping-line</arg>
<arg>--as-tuningup-line</arg>
<arg>--as-checking-line</arg>
<arg>--as-combining-line</arg>
<arg>--as-creating-line</arg>
<arg>--as-reading-line</arg>
<arg>--as-savedas-line</arg>
<arg>--as-linkto-line</arg>
<arg>--as-movedto-line</arg>
<arg>--as-validating-line</arg>
<arg>--as-template-line</arg>
<arg>--as-configuration-line</arg>
<arg>--as-palette-line</arg>
<arg>--as-reponse-line</arg>
<arg>--as-request-line</arg>
<arg>--as-selection-line</arg>
<arg>--as-error-line</arg>
<arg>--as-toknowmore-line</arg>
<arg>--as-yesornorequest-line</arg>
<arg>--as-notrailingnew-line</arg>
<arg>--as-stdout-line</arg>
<arg>--as-stderr-line</arg>
</group>
</cmdsynopsis>
</term>
<listitem>
<para>
The <function>cli_printMessage</function> function
standardizes the way centos-ar.sh scirpt prints messages. By
default, centos-art.sh script prints all messages to the
standard output with the exception of those messages printed
with the <option>--as-stderr-line</option> option, which are
printed to standard error output instead.
</para>
<para>
The <function>cli_printMessage</function> function requires
two arguments. The first argument specifies the
<replaceable>MESSAGE</replaceable> you want to print and the
second argument specifies the FORMAT you'll use to print that
message. Because this function is so used inside the
centos-art.sh script, it is convenient to provide localization
to strings passed as <replaceable>MESSAGE</replaceable> using
<command>gettext</command> contructions when they aren't
paths.
</para>
<para>
The <function>cli_printMessage</function> function accepts the
following formats as second argument:
</para>
<variablelist>
<varlistentry>
<term><option>--as-separator-line</option></term>
<listitem>
<para>
This format takes the first character passed as
<replaceable>MESSAGE</replaceable> and repeats it horizontally
to build a separator line. Use this format whenever you need
to create a logical separation between different actions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-banner-line</option></term>
<listitem>
<para>
This format takes the string passed as
<replaceable>MESSAGE</replaceable> and puts it inside two
horizontal separator lines. Use this format whenever you need
to print header information for following lines.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-cropping-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been cropped.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-tuningup-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable>
generally refers to a file inside the repository. Use this
format whenever you need to imply the fact that certain file
has been tuned-up.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-checking-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been checked or verified
(e.g., through <function>cli_checkFiles</function>
functionality).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-combining-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been combined.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-creating-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-reading-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been read.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-savedas-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been saved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-linkto-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been linked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-movedto-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been moved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-validating-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file has been validated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-template-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file is a template or design
model.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-configuration-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file is a configuration file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-palette-line</option></term>
<listitem>
<para>
This format is for two columns messages where
<replaceable>MESSAGE</replaceable> generally refers to a file
inside the repository. Use this format whenever you need to
imply the fact that certain file is a palette of colors.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-response-line</option></term>
<listitem>
<para>
This format adds <literal>--></literal> at the begining of the
string passed as <replaceable>MESSAGE</replaceable>. Use this
format whenever you need to imply the fact that certain file
is considered part of a response. For example, when you need
to express that a group of files will take ceratin action, you
can use this option to doing so.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-request-line</option></term>
<listitem>
<para>
This format prints <replaceable>MESSAGE</replaceable> without
trailing new line. Use this format whenever you need to imply
a question or yes or no request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-selection-line</option></term>
<listitem>
<para>
This format uses each word in
<replaceable>MESSAGE</replaceable> as item of a selection
list. Use this format whenever you need to select one of the
items provided as <replaceable>MESSAGE</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-error-line</option></term>
<listitem>
<para>
This format prints error messages produced by centos-art.sh
script. It uses the <command>caller</command> built-in command
to display the line number and the filename where such error
was triggered. Later, it prints where to find more information
by using the <option>--as-toknowmore-line</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-toknowmore-line</option></term>
<listitem>
<para>
This format takes a function name as
<replaceable>MESSAGE</replaceable> and prints the command you
can use to find more information about it. When this option is
passed the script finishes its execution immediately. This
option is used in combination with
<option>--as-error-line</option> to finish the script
execution after an error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-yesornorequest-line</option></term>
<listitem>
<para>
This format takes a question as
<replaceable>MESSAGE</replaceable> and reads a yes or no
answer. When answer is negative, the script finishes its
execution immediately. When answer is affirmative, the script
continues its execution normally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-notrailingnew-line</option></term>
<listitem>
<para>
Print <replaceable>MESSAGE</replaceable> without any trailing
newline.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-stdout-line</option></term>
<listitem>
<para>
Print <replaceable>MESSAGE</replaceable> to standard output.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--as-stderr-line</option></term>
<listitem>
<para>
Print <replaceable>MESSAGE</replaceable> to standard error
output.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Use <function>cli_printMessage</function> function whenever
you need to print information inside the
<command>centos-art.sh</command> script.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_unsetFunctions" xreflabel="cli_unsetFunctions">cli_unsetFunctions</command>
<arg choice="req"><replaceable>EXPORTID</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
...
</para>
<para>
See also: <xref linkend="cli_exportFunctions" />
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command id="cli_getTemporalFile" xreflabel="cli_getTemporalFile">cli_getTemporalFile</command>
<arg choice="req"><replaceable>FILENAME</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
...
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>...</term>
<listitem>
<para>
...
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>