Configuration directives are normally specified with the directive name as the first word on the line, with its value or values following. Capitalization of the directive name is not significant, but it helps readability and consistency. Additionally, any leading and trailing whitespace is removed ("stripped") before processing. Here's a simple example:

DirectiveName value

Besides specifying directive values inline, one can conveniently use the following syntax to obtain value from external files:

DirectiveName <include_filename

	Note
	Note that this syntax can be used anywhere on a line, such as in Variable MYSTUFF <file. You can use this to achieve the best performance with Variables.

Files included from interchange.cfg are relative to ICROOT. Files included from catalog.cfg are relative to specific catalog's CATROOT.

So-called "here document" syntax is supported as well. You can use it to spread directive values over several lines, with the usual Perl <<MARKER syntax (but unlike Perl, Interchange syntax uses no semicolon to terminate the marker). The closing marker must be the only thing on the line. No leading or trailing characters are allowed, not even whitespace. Here is a hypothetical directive using a here document:

DirectiveName <<EOD
    setting1 setting2
    setting3
EOD

The above is equivalent to:

DirectiveName setting1 setting2 setting3

Other configuration files can also be included from the current one. For example, common settings can be defined in a single file:

include common.cfg

Or all files loaded from a directory:

include usertag/*

It may come to you as a surprise, to learn that any configuration directive can be "tied" to a Perl subroutine (if the Tie::Watch Perl module is installed). This allows for a kind of triggers, watch points, or numerous other interesting applications.

Similar to "here documents" ("<<"), subroutine watches are defined using the "<&" notation. Consider the following example:

MailOrderTo orders@myhost.mydomain.local
MailOrderTo <&EOF
sub {
	my($self, $default) = @_;
	if($Values->{special_handling}) {
		return 'vip@myhost.mydomain.local';
	}
	else {
		return $default;
	}
}
EOF

When Interchange tries to retrieve the value of the MailOrderTo configuration directive (usually to e-mail out an order), our subroutine watch is called. In turn, it returns a special value (a separate e-mail address) for customers having value "special_handling" defined in their session. For the rest, it simply returns the default value.

Now that you've grasped the basics, there's more to the story. From the above example, you see our watch subroutine was called in style of &{$subref}(SELF, PREVIOUS_VALUE). "SELF", meaning what it usually means in Perl code, is a reference to the appropriate Tie::Watch object. "PREVIOUS_VALUE" is simply the previously set value for a directive (usually its default). Those are the standard two arguments we receive in a subroutine watch if the configuration directive was of type SCALAR (defined to accept one string or text value).

	Note
	Subroutine watches must be defined after the configuration directives have been set to their values. Setting values after subroutine watches will simply destroy them (the watches) and have unpredictable effects.

If the configuration directive being watched was a list (type ARRAY), the subroutine would be called in pattern &{$subref}(SELF, INDEX, PREVIOUS_VALUE). ("INDEX" would be an array index of the item accessed). Setting watch points on arrays that you don't control completely is not recommended. (Namely, most Interchange subroutines call arrays in their list context, and no access method is provided for that).

Finally, if the configuration directive watched was a hash (type HASH), the subroutine would be called in pattern &{$subref}(SELF, KEY, PREVIOUS_VALUE). ("KEY" would be a name of the hash value accessed). In the following example, we tie the Variable configuration directive. This is not recommended for performance reasons — Variable directive is called very often and should not bear any extra overhead). But it illustrates the power of this operation:

Variable TESTIT Unwatch worked.

Variable <&EOV
sub {
  my ($self, $key, $orig) = @_;

  if($key eq 'TESTIT') {
    # only the first time
    if($Scratch->{$key}++) {
      $self->Unwatch();
      return $orig->{TESTIT};
    }
    else {
      return "Tie::Watch works! -- name=$Values->{fname}";
    }
  }
  else {
    return $orig->{$key};
  }
}
EOV

The first time is called for an individual user, it would return the string "Tie::Watch works! -- name=NAME" along with their first name (if they provided one at some point). On a second access (again, for an individual user), the watch would be dynamically dropped and the default value of the variable TESTIT returned. All other variables would operate as usual.