This document describes the grammar used by the Parse::RecDescent parser to turn text-based items submitted via the command-line interface into items that can be stored in the Verdad database.
Here's a sample item to look at:
item jra
is = ( tellme-person unicycle-rider )
shoe-size = "9 1/2"
favourite-drink = ( beer "root beer" "Mt. Dew" )
An item starts with the keyword ``item'' and then has an item name. After that is a tag/value list. Tags and values must be separated by equal signs. When specifying an inheritance policy other than the default, use ``+='' or ``~='' instead of simply equals.
Values can be either lists or single values. All values are stored as lists internally, but when a list of one is presented to the user, Verdad typically formats it as a single value.
Tags are allowed to show up multiple times, in which case the values are added to a list in the order they are parsed. This is a convenience feature for backwards compatibility that might not always be supported.
Values can be unquoted if they consist of letters, numbers, dot, underscore and dash (i.e. things like hostnames, dotted-quad IP addresses, etc). Otherwise, they should be quoted with double quotes. You can also quote really hard-to-quote things with the Perl qq operator. That would look like this:
item weird-item
tag = qq/The following line has a single quote in it:
"
/
An item can have no tags. In this case, it is safest to format it like this:
item empty-item
(
)
In fact, any item can have parentheses surrounding the tag/value list, but it's only strictly required in for empty items which are not at the end of the input to the parser. Play it safe; always use parentheses around empty items.
For the purposes of parsing an item, there's nothing special about the is tag, which is used to indicate inheritance between items. As far as Verdad's parser is concerned, it's just another tag. In fact, the is values are also stored as normal values. It's only when you fetch a ``complete item'' that the inheritance system kicks in.
The following tag names are used in special ways by Verdad.
Both ``is'' and ``include'' specify an inheritance relationship to another item. For more information about how and why Verdad implements inheritance, see the document specifically related to it.
The contents of the comment tag are pulled out and displayed separately in some views of the item, specifically in the HTML-based user interface. The tag does not do anything special (other than contributing to the UI), and is created and edited just like any other tag.
Jeff R. Allen <jra@nella.org>