KP template files are used to allow Knowbot Program definitions to be built without including information on a specific instantiation of the KP; specific instantiations can be created by "launching" a template file. These files can currently be launched only by the rs utility.
A template file is stored as a simple text file consisting of
header lines, comments, and blank lines, freely interspersed.
Header lines have the form key:value
; they follow
some of the rules of RFC 822. Headers are categorized into two
groups: template headers and KP metadata headers. Tools which
use KP template files are free to use information in both header
groups, but should only include headers from the metadata group
as metadata submitted as part of the KP. Entries from the
template group should only be used by tools which handle
template files, but the use may include generating KP metadata.
Headers from the template group are distinguished by starting with
the string "kp-template--
"; headers from the metadata
group cannot begin with this string.
The metadata group should be used to generate metadata for
the KP as needed, preferably without changing the settings.
Some entries of particular interest to tools may be the
knowbot-class
and main-module
headers;
the rs
tool provides graphical controls which affects the values
of these fields. Metadata entries which are not explicitly
edited by tools should be passed along unmodified. This may
take the form of metadata entries in a KP or headers in the
metadata group in a KP template file, or any other appropriate
treatment.
Comment lines begin with the hash character ("#
",
also known as the pound symbol). The comment begins with the hash
character and extends to the end of the line. Text in the comment
should be ignored and has no semantic meaning for tools which process
KP template files. Tools are not required to retain comments, though
it is advisable to do so when possible.
Blank lines in KP template files are ignored.
Headers with names beginning with the leading string
"kp-template--
" belong to the template group, and
should only be used by tools which use or manipulate KP template
files. There are a number of header names which are standardized
here, but others may be defined as needed.
Standard template group headers are defined for a few specific
bits of interesting information. These headers begin with the
required starting string and have names which do not include
the string "--
" (two consecutive hyphens). The further
use of two consecutive hyphens within the template group is reserved
for tool-specific headers.
The specific headers defined in this document are listed below.
kp-template--kernel:
kp-template--modules-base:
kp-template--modules:
kp-template--module-name:
name
, where
name
is one of the names in the
value of the kp-template--modules:
header.
This allows filenames to be different from module names. The
file name given here should be relative to the directory named
by kp-template--modules-base:
when the
template file is saved. The name should be resolved relative
to the location of the template file if the file exists,
otherwise the name should be attempted relative to the
directory named by
kp-template--modules-base:
.
kp-template--stream-stdin:
kp-template--stream-stderr:
kp-template--stream-stdout:
kos-console
-- I/O for the stream
should occur on the console of the KOS running the KP at
any given time.
launcher
-- I/O for the stream should
occur using the default mechanism used by the tool which
launched the KP.
null
-- I/O for the stream should be
handled by the "null" device (/dev/null
under UNIX or NUL
under
Windows NT).
Headers which are specific to a particular tool or set of tools
should have the same basic format as the standard headers but with an
extension of the required starting string. Each tool or tool set
should have a "tool ID" which can be used to form the extension; the
tool ID should be one or more hyphen-separated words. The
distinguishing starting string for tool-specific headers should be the
required starting string followed by the tool ID and two hyphens. For
example, if the tool ID is "foo-bar
" the tool-specific
starting string would be "kp-template--foo-bar--
".
There are no restrictions on the header names used for metadata
other than on the use of the string "kp-template--
" as
the leading portion of the name. The metadata headers may include
those with special meaning for the KOE, such as
"main-module
", with the caveat that tools may
explicitly set some or all such special headers directly when
appropriate.