path: root/fml/doc/en/tutorial/internals/config.cf.sgml

<!--
   $FML: config.cf.sgml,v 1.4 2005/09/28 11:05:50 fukachan Exp $
   $jaFML: config.cf.sgml,v 1.11 2003/06/20 22:23:14 fukachan Exp $
-->

<chapter id="internal.config.cf">
	<title>
	Configuration File: config.cf
	</title>


<!-- ======================================= -->
<sect1 id="config.cf">
	<title>
	ML Specific Configuration File: config.cf
	</title>

<para>
You can customize each ML differently.
&fml4; and &fmldevel; are same in this point.
</para>

<para>
In the case of &fml4;, there is a config.ph in ML home directory,
$DIR (e.g. /var/spool/ml). This "config.ph" file is a perl script.
</para>

<para>
There is one configuration file (config.cf) in &fmldevel;, too.
But the format is different. The format is like this:
<screen>
variable = value
</screen>
.
It is similar to postfix or .ini files.
</para>

<para>
It is similar to a perl module. You can write perl codes after =cut line.
</para>


<sect2>
	<title>
	Problems in &fml4;
	</title>

<para>
The configuration file of &fml4;, config.ph, is a perl script.
Perl script is good for human editing but 
it is not suitable for configuration tools.
It implies it is difficult to prepare configuration tools for config.ph.
So, in &fml4; two files, cf and config.ph are used.
<footnote>
<para>
It is similar to the conversion from .mc to .cf in sendmail.
</para>
</footnote>
</para>

<para>
The use of cf is suitable for configuration tools but introduces
another difficulty such as inconsistency between cf and config.ph
since human may edit config.ph but forgets editing cf. So, &fmldevel;
introduces only one configuration file.
It is a new format which is similar to Postfix main.cf.
</para>

</sect2>

</sect1>


<!-- ======================================= -->
<sect1 id="config.cf.format">
	<title>
	config.cf Format
	</title>

<para>
The format of "config.cf" is "variable = value syntax".
If plural values are required, space or "\n\s" is a separator.
<screen>
variable = value

valiable = value1 value2 value3

variable = value1
           value2
           value3
</screen>
The syntax of files with the suffix .cf e.g.
	<link linkend="main.cf">
	/etc/fml/main.cf
	</link>
	, default_config.cf,
is same.
</para>

<para>
$variable at the right hand is expanded. 
For example,
<screen>
a = value1
b = $a/value2
</screen>
is expanded to
<screen>
a = value1
b = value1/value2
</screen>
.
</para>


<para>
The variable expansion is done at the last. 
So, the following definitions
<screen>
a = value1
b = $a/value2/$c
c = value3
a = value4
</screen>
are expaned to
<screen>
b = valu4/value2/value3
</screen>
since the last $a overwrites the previous one.
</para>

</sect1>


<!-- ======================================= -->
<sect1 id="config.cf.format.extension">
	<title>
	Extension To Postfix Style
	</title>

<para>
<screen>
variable += value
variable -= value
</screen>
is used for adding or removing the specific value.
</para>

<para>
<screen>
x  = a b c d
x -= b
</screen>
becoms
<screen>
x = a c d
</screen>
.
</para>

<para>
Another case,
<screen>
x  = a b c d
x += e
</screen>
becomes
<screen>
x = a b c d e
</screen>
.
</para>

</sect1>


<!-- ======================================= -->
<sect1 id="config.cf.overload">
	<title>
	Overload Variables In config.cf
	</title>

<para>
Overloading of .cf files is possible.
It overwrites variables.
</para>

<para>
It enables separation of configuration files e.g.
the default file,
the host specific file,
the domain specific file,
and 
ML specific file.
</para>

<para>
&fml8; reads these files sequentially. At the last, &fml8; expands
variables when variable reading is requested.
</para>

</sect1>

<!-- ======================================= -->
<sect1>
	<title>
	Modifying/Adding Variables 
	After All Configuration Files Have Been Loaded.
	</title>

<para>
The variable expansion is always done.
If some value with $ is added to some variable, 
the next reading operation 
   <footnote>
   <para>
   tie() operation of perl
   </para>
   </footnote>
causes variable expansion.
</para>

<para>
For example, set
<screen>
$config->{ key } = '$ml_home_dir/value';
</screen>
here. 
The next read operation e.g.
<screen>
$config->{ another_key }
</screen>
(where the key is any) evaluates the variable expansion.
</para>


<sect2>
	<title>
	Internal Of Variable Expansion
	</title>

<para>
%_fml_config hash holds pairs of key and value.
The format is $dir/$file in this hash, it is not expanded.
get() returns the value of %_fml_config_result.
The value in this hash is after the variable expansion.
The variable is expanded in calling get() method.
</para>

</sect2>

</sect1>


<sect1 id="list.variables.by.alphabeticalorder">
	<title>
	Variable List (Alphabetical Order)
	</title>

&var.table.list.variables;

</sect1>


<sect1 id="list.variables.by.class">
	<title>
	Variable List (Class Based)
	</title>

&var.table.class.variables;

</sect1>


<sect1 id="recipes.internal.config.cf">
	<title>
	Recipes
	</title>

<qandaset>

<qandaentry>

<question>
<para>
What functions are proper used in config.cf file ?
</para>
</question>

<answer>
<para>
Use methods of $curproc (in hooks). 
</para>
</answer>

</qandaentry>

</qandaset>


</sect1>


</chapter>