Fork: 0
tundra / tconfpy
Browse code
Wrote section on the .literal directive.
master
1 parent 72c0e7b commit 04070ba68ce4da20ac161f58ac0ff1a0b7da6ad3
@tundra tundra authored on 17 Apr 2004
Patch
Unified Split
Showing 1 changed file
View
99
■■■■■
 tconfpy.3
 
 
.SS The \'.literal\. Directive
 
By default, \*(TC only permits statements it "recognizes" in the
configuration file. Anything else is flagged as an unrecognized
statement or "syntax error". However, it is possible to "embed"
arbitrary text in a configuration file and have \*(TC pass it back
to the calling program without comment by using the \'.literal\'
directive. It works like this:
 
.nf
.literal
This is literal text that will be passed back.
.endliteral
.fi
 
This tells \*(TC to ignore everything between \'.literal\' and \'.endliteral\'
and just pass it back to the calling program (in \'retval.Literals\' - see
previous section on the \*(TC API).
 
What good is this? It is a nifty way to embedd plain text or even
programs written in other languages within a configuration file and
pass them back to the calling program. This is especially handy
when used in combination with \*(TC conditional features:
 
.nf
.if [.OSTYPE] == posix
.literal
We're Running On A Unix-Like System
.endliteral
 
.else
.literal
We're Not Running On A Unix-Like System
.endliteral
 
.endif
.fi
 
 
In other words, we can use \*(TC as a "preprocessor" for other text or
computer languages. Obviously, the program has to be written to understand
whatever is returned as literal text.
 
By default, \*(TC leaves text within the literal block completely untouched.
It simply returns it as it finds it in the literal block. However, the
programmer can invoke \*(TC with an option (\'LiteralVars=True\') that
allows
.B variable substitution within literal blocks.
This allows you to combine the results of your configuration into the
literal text that is returned to the calling program. Here is how it
works:
 
.nf
 
.ifall $USER
Greeting = Hello [$USER]. Welcome to [.MACHINENAME]!
.else
Greeting = Hello Random User. Welcome To Random Machine!
.endif
 
 
# Now embed the greeting in a C program
.literal
 
[HASH]include <stdio.h>
 
main()
{
printf("[Greeting]");
}
.endliteral
.fi
 
If the calling program sets \'LiteralVars=True\', the literal block
will return a C program that prints the greeting defined at the top of
this example. If they use the default \'LiteralVars=False\', the C
program would print "[Greeting]". (Well ... it should do that, but if
variable substitution is not enabled, the \'[HASH]\' reference will
not be resolved and the C program returned will be incorrect.)
 
In other words, it is possible to have your literal blocks make
reference to other configuration variables (and Predefined or
Environment Variables). This makes it convenient to
combine both configuration information for the program,
.B and
other, arbitrary textual information that the program may need,
all in a single configuration file.
 
If you fail to provide a terminating \'.endliteral\', the program will
treat everthing as literal until it reaches the end of the
configuration file. This will generate an appropriate warning, but
will work as you might expect. Everything from the \'.literal\'
directive forward will be treated literally. As a matter of good
style, you should always insert an explicit \'.endliteral\', even if
it is at the end of file.
 
Placing an \'.endliteral\' in the configuration file without a
preceding \'.literal\' will also generate a warning message, and the
statement will be ignored.
 
 
.SH ADVANCED TOPICS
 
.SS Guaranteeing A Correct Base Configuration