Home - Forum - Code - Articles - Links - Files
Metadata is data about something rather than data contained in it. Fuzzball 6 has added a few directives you can use to store metadata about your MUF programs. Let's look at them.
Programs have certain attributes, such as authors and versions, that are usually in the program's header comment in whatever format the author cares to use. Being in various human-readable formats makes it hard for software to use the settings: if a program had to parse every header comment format, it would be very complicated and still not catch even most cases. Fuzzball 5 offered standard properties for some of these data, but they have to be set in a program upload script along with your program's flags and the like.
Fuzzball 6 adds support for directly setting these properties in the program body through several preprocessor directives. When the MUF compiler sees these directives, it sets the appropriate properties. The settings can then be used by any programs that use those standard properties, and with the ease of setting the data, more software will make use of them. @register will show the versions and library versions if present, and software such as Akari's automatic MUF repository can track authors and versions without human intervention, with the presence of the directives.
You should use these directives in any MUF program you write or publish.
Fuzzball 6's metadata directives are:
| Directive | Contents | Property |
|---|---|---|
$author |
The author of the program. | _author |
$version |
The normal program version number. | _version |
$lib-version |
The library version number. | _lib-version |
$note |
A general note. Usually a description. | _note |
All these are available in man on your neighborhood Fuzzball 6 MUCK. These and other directives are listed in man defdets.
$author$author sets the program's _author property. In general, you should use a format like you address email, such as $author Natasha O'Brien <mufden@mufden.fuzzball.org>. This includes the author's contact information, and someone requiring permission to copy your program or report a bug will need that. Separate multiple authors with a comma, just like in email: $author Natasha O'Brien <mufden@mufden.fuzzball.org>, Revar Desmera <revar@belfry.com>.
While the property can be any format, Akari's MUF repository requires the first space-delimited word be the user name of the managing user. This is OK if you go by your first name enough to use it as your repository user name (being Natasha is fine with me), but if you want to use your full name, you would have to replace the space between your names with an underscore (Natasha_O'Brien). That would be the name you request from Akari as your user name as well as the name in your $author directive ($author Natasha_O'Brien <mufden@mufden.org>).
$versionPrograms are living documents. They have bugs fixed and features added, and so go through a definite revision cycle. As you change your program, you can increment the $version. As mentioned above, @register will display the version associated with a program. Akari's repository keeps copies of all submitted versions, and won't let you replace one version with a previous one.
Fortunately Akari and man agree on how to express versions: floating point numbers. You might use $version 1.0 in your first version, then after you add a few changes, bump it to $version 1.001. Note that, because versions are normal floating point numbers, you can only have one decimal point: 1.0.1 isn't a valid version, so use 1.01 instead. Also, you can't increment from 1.9 to 1.10: that's equal to 1.1, which is less than 1.9! That's why the standard fbmuf programs use $version 1.001 instead of $version 1.1, and you probably should too.
If your program requires the presence of another program, you can use the conditional compilation directives $ifver and $ifnver to either require a certain version (with $abort, say) or to switch to alternate code that works without that program. The version will have to be greater than or equal to the one you specify. For example, if in cmd-foo.muf you wrote:
$ifnver $cmd/quux 2.0
$abort Requires cmd-quux 2.0 or greater
$endif
then if cmd-quux 2.003 is installed, cmd-foo's compilation would not abort.
$lib-versionIf your program is an $includeable library, you should use $lib-version in addition to $version. Your $lib-version represents the version of the library's API: the set of public defs your library exports, for other programs to call. Only if you change your API--add or remove a call, or change the arguments to one--should you add to $lib-version.
For example, suppose you have a $lib/foo with a certain set of calls. One day you find a bug in your implementation, one that's completely internal to the library. Fixing the bug won't require any changes whatsoever to a program $includeing the library. Adding this fix would imply a new $version, but not a new $lib-version.
$noteThis sets the program's _note property. I asked Revar what it's for:
I honestly am not sure. Some folks like me use
$notefor license info (GPL, etc), and other folks use it for various other things. I adopted it from the set of things ProtoMuck added.As far as I'm concerned, it's just a miscellaneous note. What any specific muck uses it for it up to them.
Akari says it's mostly for brief program descriptions, as you'd find in your MUCK's program lister. I would like to promote this use, although yes, a $desc directive would be better. For now I suggest using $note as a brief program description; you can automatically replace it with $desc if such a directive comes into being, then use $note for whatever you like.
These directives are here to make your coding life easier by allowing the creation of better metadata tools, such as Akari's MUF repository, and making it easier to use the tools that are already out there, like @register. Use them in good health.