The configuration parameters of a package are like command options,
which are valid for all commands of a package. There are three sources
of command line options: Options, which are defined by siliconBrain
like --help, which are always and for all commands
available. Options defined for the package, which are valid for all
commands belonging to a package. And finally, command specific
options.
The first group of options, the siliconBrain defined options, don't have to be specified. And they cannot.
The second group, the package general options and the third the
command specific options are specified in exactly the same way. If the
package name is packageName, that the options of the command
packageName are the package general options. This works
independently of whether this command really exists. But in case that
there is a command with the name of the package, then this command is
treated as the main command of the package and all its options
are the package general options.
The specification of options works via so called executable
specifications. Currently they have to be written in c. For
the command myCommand there is the program
myCommand.specification.c. This is a program containing a
main function. If it is called it outputs the option
specification as xml. Because the configuration parameters
are just the options of an eventually virtual command with the name of
the package, packageName.specification.c does contain the
configuration parameter specification. This specification is
indistinguishable from normal options. These sources are automatically
detected by siliconBrain's makefile and compiled into the
correct directory, which btw is temporary/. This
program should accept the option --xml and at least n case this
option is given, should output xml format.
The output is like so:
<command
name="siliconBrain"
release="$siliconBrainRelease: 0.2.3 $"
rcsIdentifier="$Id: siliconBrain.main.texinfo,v 1.55 2004/12/14 23:31:27 joerg Exp $"
saveStamp="$siliconBrainSaveStamp: 2004/08/06 18:39:38, Joerg
Kunze$"
title="siliconBrain main configuration.">
<shortDescription> general datahandling application framework </shortDescription>
<longDescription> Based on some specification a general frame of standard interfaces ins generated </longDescription>
<option name="publishTargetHost" type="value">
<shortDescription> IP address or domain name where package should be put to </shortDescription>
<longDescription> Host to which the complete package is webified. This includes FTP directories for the tar.gz of this package and a directory for the HTML documentation and the syntaxhighlighted sources. </longDescription>
</option>
<option name="publishTargetArchive" type="value" oneCharacterName="a">
<shortDescription> directory on the publishTargetHost, where the tar.gz should be put to. </shortDescription>
<longDescription> this directory should already exist. It is reachable from where the FTP command puts one when logging in. </longDescription>
</option>
<option name="publishTargetWeb" type="value">
<shortDescription> directory on the publishTargetHost, where the HTMLilized sourcetree should be put to. </shortDescription>
<longDescription> this directory should already exist. It is reachable from where the FTP command puts one when logging in. </longDescription>
</option>
</command>
Where type can be value or flag.
The easiest way to implement this is to use siliconBrainLib's Printer:
#define siliconBrainPrintShortNames
#include "siliconBrainLib"
static const char *siliconBrainRelease = "$siliconBrainRelease: 0.2.3 $";
static const char *siliconBrainRcsIdentifier = "$Id: siliconBrain.main.texinfo,v 1.55 2004/12/14 23:31:27 joerg Exp $";
static const char *siliconBrainSaveStamp = "$siliconBrainSaveStamp: 2004/12/14 22:37:42, Joerg Kunze$";
int main( int argc, const char *argv[] ) {
SiliconBrainPrinter siliconBrainPrinter;
siliconBrainPrinterInit( &siliconBrainPrinter, argc, argv );
tag( "command" );
attribute( "name" , "configuration" );
attribute( "release", siliconBrainRelease );
attribute( "rcsIdentifier", siliconBrainRcsIdentifier );
attribute( "saveStamp", siliconBrainSaveStamp );
attribute( "title", "siliconBrain main configuration." );
tag( "shortDescription" );
text( "general datahandling application framework" );
end();
tag( "longDescription" );
text( "Based on some specification a general frame of standard interfaces ins generated" );
end();
tag( "option" );
attribute( "name" , "publishTargetHost" );
attribute( "type" , "value" );
tag( "shortDescription" );
text( "IP address or domain name where package should be put to" );
end();
tag( "longDescription" );
text(
"Host to which the complete package is webified. This includes FTP directories for the tar.gz of this package "
"and a directory for the HTML documentation and the syntaxhighlighted sources."
);
end();
end();
tag( "option" );
attribute( "name" , "publishTargetArchive" );
attribute( "type" , "value" );
tag( "shortDescription" );
text( "directory on the publishTargetHost, where the tar.gz should be put to." );
end();
tag( "longDescription" );
text(
"this directory should already exist. It is reachable from where the FTP command puts one "
"when logging in."
);
end();
end();
tag( "option" );
attribute( "name" , "publishTargetWeb" );
attribute( "type" , "value" );
tag( "shortDescription" );
text( "directory on the publishTargetHost, where the HTMLilized sourcetree should be put to." );
end();
tag( "longDescription" );
text(
"this directory should already exist. It is reachable from where the FTP command puts one "
"when logging in."
);
end();
end();
end();
return 0;
}
In this way the option --xml is handled, the output is pretty
printed indented and colorized if stdout is a tty. With other output
options like --bash other output syntax is possible.
If we take as an example the option publishTargetHost it now
can be given in the command line:
myCommand --publishTargetHost=siliconbrain.com
can be given as an environment variable:
export packageName_publishTargetHost=siliconbrain.com
or in an xml outputting executable configuration:
<packageName>
<!-- publishTargetHost (value) : IP address or domain name where package should be put to -->
<publishTargetHost> siliconbrain.com </publishTargetHost>
<!-- publishTargetArchive (value) : directory on the publishTargetHost, where the tar.gz should be put to. -->
<publishTargetArchive> ftp/anon/pub </publishTargetArchive>
<!-- publishTargetWeb (value) : directory on the publishTargetHost, where the HTMLilized sourcetree should be put to. -->
<publishTargetWeb> www/htdocs </publishTargetWeb>
<!-- help (flag ) : Print a short help message, listing the options. -->
<!-- verbose (flag ) : Let this command talk to you a lot. -->
<!-- version (flag ) : Display version information. -->
<!-- output (value) : File to which output is written. -->
<!-- complete (flag ) : Indicate completeness of specified options. No further lookup in configuration chain. -->
</siliconBrain>
These executable configurations are searched in the directories
specified in the environment variabel
$siliconBrainConfigurationPath, which has the default
.:~:/etc:, where the last entry of length 0 searches for a
configuration via $PATH. The executable configurations have the
name packageName.configuration. They can be written in any
language. Again they can use siliconBrainLib's printer:
#define siliconBrainPrintShortNames
#include "siliconBrainLib"
// static const char *siliconBrainRelease = "\$siliconBrain" "Release: 0.0.7 \$";
// static const char *siliconBrainRcsIdentifier = "\$I" "d: myProject.configuration.main.c,v 1.3 2003/06/07 21:59:58 joerg Exp \$";
// static const char *siliconBrainSaveStamp = "\$siliconBrain" "SaveStamp: 2003/06/17 23:47:40, Joerg Kunze\$";
int main( int argc, const char *argv[] ) {
SiliconBrainPrinter siliconBrainPrinter;
siliconBrainPrinterInit( &siliconBrainPrinter, argc, argv );
tag( "myProject" );
keyBool( "standardFlag", true );
keyBool( "verbose" , true );
key( "oops" , "well, ehm ..." );
end();
return 0;
}
or they uses other means, like the trivial configuration implementation:
#!/bin/bash
cat <<EOF
<siliconBrain>
<!-- publishTargetHost (value) : IP address or domain name where package should be put to -->
<publishTargetHost> siliconbrain.com </publishTargetHost>
<!-- publishTargetArchive (value) : directory on the publishTargetHost, where the tar.gz should be put to. -->
<publishTargetArchive> ftp/anon/pub </publishTargetArchive>
<!-- publishTargetWeb (value) : directory on the publishTargetHost, where the HTMLilized sourcetree should be put to. -->
<publishTargetWeb> www/htdocs </publishTargetWeb>
<!-- complete (flag ) : Indicate completeness of specified options. No further lookup in configuration chain. -->
<complete/>
</siliconBrain>
EOF
In each stage, does the --complete option block any further
lookup. If given in the command line, no environment variables would
be inspected, if given in the environment, no lookup in configurations
would be done.
The program packageName.configurationReader handles all options
like a normal command and outputs the result in xml,
bash or perl syntax.
The result can be pumped into the environment with:
eval "$(packageName.configurationReader -- --bashEnvironment)
With:
eval "$(packageName.configurationReader $* -- --bash)
The configuration can be used inside a bash script.