Chapter 5 Overview of Configuration Syntax
5.1 Introduction
You control the behaviour of Canthology by editing entries in its configuration file. I will explain the meaning of the entries in the Chapter 7. But first (in this chapter), I will provide an overview of the syntax used in the configuration file. This overview will be sufficient to get you started using Canthology. Later on, you might want to read Appendix B to get complete details of the syntax.
By the way, the configuration syntax used by Canthology is called Config4* (pronounced “config for star”). This syntax is not specific to Canthology, so you may see it being used in some other software applications.
5.2 Syntax
Figure 5.1 provides a simple example of a Config4* configuration file.
1 # this is a comment 2 name = "Fred"; 3 greeting = "hello, " + name; 4 some_names = ["Fred", "Mary", "John"]; 5 more_names = ["Sue", "Ann", "Kevin"]; 6 all_names = some_names + more_names; 7 application.defaults { 8 timeout = "2 minutes"; 9 log { 10 dir = "C:\foo\logs"; 11 level = "0"; 12 } 13 } 14 one_application { 15 @copyFrom "application.defaults"; 16 log.level = "1"; 17 } 18 another_application { 19 @copyFrom "application.defaults"; 20 timeout = "30 seconds"; 21 }
Comments, like the one shown in line 1, start with # and continue until the end of the line. Most of the lines in a configuration file contain assignment statements. These are of the form name=value, where the value can be a string (line 2) or a list of strings (line 4). You can use the + operator to concatenate both strings (line 3) and lists (line 6). Assignment statements are terminated with a semicolon.
String values are usually written as a sequence of character enclosed within double quotes, for example, "Fred". Within such a string, % acts as an escape character. For example, %n denotes a newline character, and %" denotes a double quote.1
A configuration file can contain named scopes (lines 7, 9, 14, and 18 in Figure 5.1). Scopes can be nested (line 9) and re-opened. The scoping operator is what some people call a full stop, and others call a period or a dot. For example, the name log.level refers to a variable called level inside a scope called log. You do not have to explicitly open a scope to define a variable or a nested scope within it. For example, line 7 opens the server.defaults scope without opening the outer server scope. Likewise, line 16 defines log.level without explicitly opening the log scope.
5.3 Copying Default Values
All keywords (for example, @include and @copyFrom) start with the @ symbol: this ensures there can never be a clash between the name of a keyword and the name that you might wish to use for a configuration variable or scope.
The @copyFrom statement (lines 15 and 19 in Figure 5.1) copies the entire contents (name=value pairs and nested scopes) of the specified scope into the current scope. This provides a simple, yet effective, reuse mechanism. It is not an error to assign a new value to an existing variable. This makes it possible to override default values obtained via a @copyFrom statement.
5.4 Including Other Files
An @include statement (not shown in Figure 5.1) includes the contents of another configuration file into the current one. For example:
@include "/tmp/foo.cfg";
5.5 Accessing Environment Variables
You can access environmental information in a configuration
file. For example, you can use
getenv("CANTHOLOGY_HOME") to access an environment
variable called CANTHOLOGY_HOME.
install_dir = getenv("CANTHOLOGY_HOME");