Feature based zephyr

In old style .zwgc.desc files, in order to add functionality to it, you had to more or less cut and paste code or write it from scratch. This is not efficient for sharing code, managing updates, and overall ease of use.

Feature based zephyr attempts to allow the user to specify what they want zephyr to do in terms of general behavior.

The concept of features

Basically, a feature is a set of behaviors that zion will perform on some or all zephyrs. For example, one commonly desired feature is mail notification. Another is zephyr logging. With feature based zephyr, the user just registers these features in their .zion.desc.pl file, and the appropriate thing happens.

For example, say a user wants normal zephyr formatting with mail notification and with zephyr logging. Under the old system, they would comment out, or copy the mail notification code, and then find and copy some zephyr logging code. With the new system, however, the user only needs the following .zion.desc.pl file:

unshift(@INC, "/afs/sipb/project/zion/perl/features/");
require Feature;

&Feature::Register("MailNotification", "ZephyrLogging", "Default");
&Feature::HandleZephyr;

This will cause the automatic inclusion of the appropriate code.

Finding out what features are available

One of the default features is the FeatureInfo feature. You will get this feature if you register either the Default feature or the FeatureInfo feature (the former registers the latter for you).

If you have this feature, you can send yourself a zephyr with the opcode FEATURE and the contents ALL, and it will give a list and brief description of all the features available in your .zion.desc.pl path. Fromt he command line:

zwrite $USER -O FEATURE -m ALL

In order to get full documentation for a particular feature, change the word ALL above to the name of the feature you want documentation for.

Using Zephyr Features

In order to use a feature, simply add it as an argument to Feature::Register(). In order to use features from other directories, insert a line of the form:

unshift(@INC, "/path/to/features/directory/here/");

That's it. :-)

Writing Zephyr Feature Files

The basic idea of Features is that as each zephyr gets processed, a series of functions are run in a predetermined order. In order to write a Feature, you need to define a Load function, and probably some others. The simplest Feature is probably the "IgnorePings" feature, which I'll use as a first example.

# First of all, all Feature's must begin with a line that tells perl
# the feature name
package IgnorePings;

# All Feature's must define a load function.  The Load function will
# call Feature::FuncReg and tell zion to run these functions at a
# particular point during the zephyr handling
sub Load {
	# This says at 'insertion point' 20, run the exit_if_ping function
	# See Feature.pm for details on the meaning of the various
	# 'insertion points'
        &Feature::FuncReg(\&exit_if_ping, 20);
	# Also note, the ampersand before exit_if_ping is escaped
	# This is because you are passing a function reference, a perl5 thing
}

# This is the function that we registered.
# It checks the opcode of the zephyr (stored in the variable $main::opcode)
# and exits if it is "PING"
sub exit_if_ping {
        exit if ($main::opcode eq "PING");
}

# Features can be self documenting, if you use the FeatureInfo Feature, part
# of the Default Feature set
# This implies the use of the Description and Documentation functions
sub Description {
        "Cause pings not to be processed";
}

sub Documentation {
	"There is nothing worth documenting about the IgnorePings Feature";
}

# Perl files that are included have to return a true value, so put a 1
# at the end of your files
1;

There will be more detailed examples soon.

For now, read the source code. Some good examples:

`$main::displayed`

This is a special variable which you can expect to be set once a zephyr has been displayed. This helps prevent a zephyr from being displayed multiple times. For example, the MailNotification Feature may display mail notification zephyrs for you, and you don't want the DefaultFormat Feature to do it as well.

So, any Feature that is going to display a zephyr should confirm that $main::displayed is not yet set, and after it has been displayed, should set it to 1.

1/27/98
Sometime soon (maybe :-) I'll ask people who have written features to let me know so I can have a list on this page, and maybe even incorporate some of them in the standard set.

Someone should write a good, generic, configurable logger.

I know amu has written a VT Feature and one for use with kretch's kzwrite. I've written a nice ZAway feature, a Punt feature, and the beginnings of MIMEZephyr.