4.3.3 Field datatypes

Each field description has to contain a datatype declaration which describes what data are to be store in the field. The general format for such a declaration is

datatype  [ options ... ]

The available datatypes are:

text  [ matching { "regexp" [ "regexp" ... ] } ]

The text datatype is the most commonly used type; it is a one-line text string.

If the matching qualifier is present, the data in the field must match at least one of the specified regexps. This provides an easy and flexible way to limit what text is allowed in a field. If no matching qualifier is present, no restriction is placed on what values may appear in the field.

multitext  [ { default "string" } ]

The field can contain multiple lines of text.

If the default option is present, the field will default to the specified string if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

enum  {

  values {

    "string" [ "string" ... ]

  }

  [ default "string" ]

}

Defines an enumerated field, where the values in the PR field must match an entry from a list of specified values. The list of allowed values is given with the values option. The values option is required for an enumerated field.

If a default option is present, it is used to determine the initial value of the field if no entry for the field appears in an initial OR (or if the value in the initial PR is not one of the acceptable values). However, the value in the default statement is not required to be one of the accepted values; this can be used to allow the field to be initially empty, for example.

If no default option is specified, the default value for the field is the first value in the values section.

multienum  {

  values {

    "string" [ "string" ... ]

  }

  [ separators "string" ]

  [ default "string" ]

}

The multienum datatype is similar to the enum datatype, except that the field can contain multiple values, separated by one or more characters from the separators list. If no separators option is present, the default separators are space (‘ ’) and colon (‘:’).

The values in the default string for this field type should be separated by one of the defined separators. An example clarifies this. If we have a field named ingredients where the default values should be ‘sugar’, ‘flour’ and ‘baking powder’ and the separator is a colon ‘:’, the following sets these defaults:

default "sugar:flour:baking powder"

enumerated-in-file {

  path "filename"

  fields {

    "name" [ "name" ... ]

  } key "name"

  [ allow-any-value ]

}

The enumerated-in-file type is used to describe an enumerated field with an associated administrative file which lists the legal values for the field, and may optionally contain additional fields that can be examined by query clients or used for other internal purposes. It is similar to the enum datatype, except that the list of legal values is stored in a separate file. An example of this kind of field is the built-in Category field with its associeted ‘categories’ administrative file.

filename is the name of a file in the ‘gnats-adm’ administrative directory for the database.

The format of the administrative file should be simple ASCII. Subfields within the file are separated with colons (‘:’). Lines beginning with a hash sign (‘#’) are ignored as comments. Records within the file are separated with newlines.

The field option is used to name the subfields in the administrative file. There must be at least one subfield, which is used to list the legal values for the field. If the administrative file is empty (or does not contain any non-empty non-comment lines), the PR field must be empty.

The key option is used to designate which field in the administrative file should be used to list the legal values for the PR field. The value must match one of the field names in the field option.

If the allow-any-value option is present, the value of the PR field is not required to appear in the administrative file — any value will be accepted.

Note that there is no default keyword for enumerated-in-file. These fields get their default value from the first entry in the associated administrative file.

multi-enumerated-in-file {

  path "filename"

  fields {

    "name" [ "name" ... ]

  } key "name"

  [ default "string" ]

  [ allow-any-value ]

  [ separators "string" ]

}

multi-enumerated-in-file is to multienum what enumerated-in-file is to enum. Its options have the same meaning as their counterparts in the multienum and enumerated-in-file fields.

NOTE: Keywords may appear in any sequence, with one exception – the separators keyword, if present, has to come last. This rule only applies to fields of type multi-enumerated-in-file.

date

The date datatype is used to hold dates. Date fields must either be empty or contain a correctly formatted date.

No defaults or other options are available. The field is left empty if no value for the field is given in the initial PR.

integer  [ { default "integer" } ]

Integer fields are used to hold numbers. They must either be empty or contain a value composed entirely of digits, with an optional leading sign.

If the default option is present, the field will have the value of integer if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.