Programming watch points in catalog.cfg

### Index Up

## Programming watch points in catalog.cfg

You can set up almost any configuration variable to be tied to a subroutine if you have the Tie::Watch module installed. It uses a notation like the << HERE document, but <`&HERE` is the notation. See `MiniVend Programming` for details.

Here is a simple case:

        MailOrderTo orders@minivend.com

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

When the order is mailed out, if the user has a variable called `special_handling` set in their session (from UserDB, perhaps) then the order will be sent to 'vip@minivend.com'. (Note the single quotes to prevent problems with the @ sign.) Otherwise, they will get sent to the previously defined value of `orders@minivend.com`.

If the configuration value being watched is a SCALAR, the subroutine gets the following call:

        &{$subref}(SELF, PREVIOUS_VALUE)

The subroutine should simply return the proper value.

SELF is a reference to the Tie::Watch object (read its documentation for what all it can do) and PREVIOUS_VALUE is the previously set value for the directive. (If you set it after you set up the watch, it will simply have the effect of destroying the watch and having unpredictable effects. In the future, you may be able to set up a ``Store'' routine that can subsequently set values).

If the configuration value being watched is an ARRAY, the subroutine gets the following call:

        &{$subref}(SELF, INDEX, PREVIOUS_VALUE)

INDEX is the index of the array element being accessed. Setting up watch points on array values is not recommended -- most MiniVend subroutines call arrays in their list context, and no access method is provided for that.

If the configuration value being watched is a HASH, the subroutine gets the following call:

        &{$subref}(SELF, KEY, PREVIOUS_VALUE)

KEY is the index into the hash. An example of HASH type MiniVend configuration values

NOTE: The following is not recommended for performance reasons -- the Variable is a commonly used thing and should not bear the extra overhead -- but it illustrates the power quite nicely:

        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->{name}";
                }
            }
            else {
                return $orig->{$key};
            }
        }
        EOV

The first time __TESTIT__ is called for a particular user, it will return the string ``Tie::Watch works! -- name='' along with their name set in the session (if that exists). Any other variables will receive the value that they were set to previously. Once the TESTIT key has been accessed for that user, the watch is dropped upon the next access.

### Index Up