STT(5)

NAME
stt - standard text template

DESCRIPTION
This describes the format of standard text templates to be used by stt(1). Form files have a simple ASCII format reminiscent of some ancient job control language. All lines not starting with two slashes are simply ignored unless they appear in a multi-line textual value. Each format element looks like

//KEYWORD values

or like

//KEYWORD
 ... values
 ... /*

The second variant is used for multi-line values, such as the text to be sent.

Template layout

stt processes a form file, and, according to its context, generates an intermediate perl5 program. That program can be split into several logical parts: 1. Perl5 code to initialize data structures and to include necessary modules to the early begining of the generated program - //CODEINIT block. 2. Common variables declaration - //VAR 3. Perl5 code, that can handle declared variables, and bring its own new ones... - //CODE (or, //DERIV for older versions) 4. A conditional variables declaration, that expands variables if a corresponding condition is TRUE. With the version 1.00 form document, //OTEXT command is used to implement this. With greater versions it's recommended to use //OTEXTCOND instead. 5. Declaration of the main template variable - //TEMPLATE. 6. Final message processing, when form is completely expanded, but not yet transmited to the mailing function - //CODEFINAL block. See also "Special variables". 7. Sending a message, and, if it was sent successfuly (mailer returned 0), postprocess the perl5 code that was given in //POSTSENT block, otherwise - the one in the //POSTNOTSENT. You should keep this layout in mind, when making your own form template.

Format elements

//VERSION <n.nn> [MD5-checksum]

    Is used for specifying the form version, and also it can be used for keeping a form's MD5-checksum. <n.nn>
        is the template version number, for example, 1.00.
    In case an MD5-checksum is also present, stt will refuse to run, if the stored checksum and the current one are not equal. If this happens, the only way to fix the problem is to call one of the members of the privileged group (see stt(1)).
//TITLE <short-descr>

    Is used to describe the form when listing (all) forms. <short-descr>
        is a one-line description of what the form does. It is used with the --list (-l) and --grep (-g) options of stt.
//DESCR
<text>
/*

    Is used to give a full description of the entire template.
//DEFAULT <-c>

    Is used to set special defaults for this form: -c causes stt to default to creating a new message instead of replying to the current MH message. This can be overridden by the -r command line option.
//VAR <name> <reply-deriv> <default>

    is used to describe the variables used in the form. Each variable that appears in the form should be declared here first (also see //VARMULTI). The variables can be referenced in the form text (see below). <name> is the variable name which should consist of at least two lowercase characters. These names are actually perl5(1) variables legal names. <reply-deriv> specifies how the variable can be derived from the message being replied to. The values of <reply-deriv> can be either lowercase RFC822 header names or one of the following special variables: from
        The address of the sender, taken from the "From:" field.
    from-addr
        The mailbox component of the "from" address.
    from-name
        The comment component of the "from" address. This usually contains the real name of the originator.
    reply-to
        The address, to which the reply should be sent to, taken from the "Reply-To:" field.
    reply-to-addr
        The mailbox component of the "reply-to" address.
    reply-to-name
        The comment component of the "reply-to" address. This usually contains the real name of the sender.
    repl
        The address to reply to, as specified by RFC822. This is one of the addresses taken from the "Reply-To", "From", "Return-Path" or "Sender" fields, in descending order of preference. Note that we consciously do not handle multiple addresses in either header.
    repl-addr
        The mailbox component of the "repl" address.
    repl-name
        The comment component of the "repl" address.
    rfc822-header
        A complete set of all message headers in one line.
    body
        The body of the message. Message bodies can be extremely large, especially with MIME encoded messages like FAXes. In many cases it is advisable to limit the amount of body data copied into the vatriable. See "Modifiers" below for details.
    Modifiers , seperated by slashes (/) can be appended to the names in <reply-deriv>. Currently the following modifiers are defined: <nnn>B
        limits the amount of data copied into the variable to <nnn> bytes.
    <nnn>L
        limits the number of the lines that will go to the variable. This is most useful to limit the size of variables containing parts of the message body.
    <default>
        is the default value for this variable if it cannot be derived from the message being replied to or from the command line.
    The special value "BUILTIN" can be used for the following variables. Except the fact that there is a builtin default value, such variables are in every aspect normal variables. Builtin names are: hostname
        assigns the fully qualified domain name of the host on which stt is run.
    logname
        assigns the login name of the stt user.
    username
        tries to assign real login name of the current user, which can be changed after su. It takes the first available one, checking environment variables USERNAME and USER. If both of them are not set, then current login name is used instead.
    myname
        assigns the real name of the stt user from the GCOS field in passwd(5).
    signame
        assigns the value of the environment variable SIGNAME which is intended to be set to the real name of the person using stt even from another login account.

    In case there is no default value an empty string ("") should be used.
//VARMULTI <name> <reply-deriv>
<text>
/*

    This is an extended version of //VAR command, that provides the possibility to define variables that contain several lines. <name> and <reply-deriv> have the same meaning as in //VAR, but the default value should be taken starting from the new line to the closing sign.
//PRO <name> <prompt-string>

    specifies the string used when stt(1) needs to prompt for a variable's value. <prompt-string> should describe the variable in a concise way.
//SELECT <name>
<text>
/*

    That format assosiates <name> with the set of choices, from which final value of that variable will be chosen. It uses corresponding to that variable prompt, declared in //PRO section. Items are given in a nice numbered menu form, and user should choose one of the numbers, that corresponds to the appropriate item.
//ARGS <name> ...

    specifies which variables are to be derived from the command line by stt(1). The command line arguments will be assigned to the variables in the order they are mentioned here. Command line arguments take precedence over values derived from the message being replied to.
//ASK <name> ...

    Specifies which variables' values will be obtained by prompting the user if they are not defined in any other way. Prompting will occur in the order specified here.
//DERIV
<perl5 code>
/*

    Note: This format is deprecated, and left only for compatability reasons. Please use //CODE instead. Specifies how variables will be derived from others using perl5(1) statements. The variables declared with //VAR and optional texts defined with //OTEXTCOND are available. Any new variables should be declared in the lexical scope (with my()). It is possible to use the function prompt(promptstring, default) to prompt the user for input. The function returns the user input or the default if the user enters nothing. Apply with care!
//CODE
<perl5 code>
/*

    Specifies how variables will be derived from others using perl5(1) statements. That statements will be directly inserted into the resulting template code, after variables (//VAR) and functions (//OTEXTCOND) declaration. At this stage it is possible to modify template's variables and introduce new ones. Any new variables should be declared in the lexical scope (with my()). It is possible to use "built-in functions" to bring some additional functionality into the code. Apply with care!
//CODEINIT
<perl5 code>
/*

    This format almost has same restrictions and requirements, as //CODE format has, but the code will appeare at the early begining of the generated program, before any declarations. It's purpose mostly to put "use module;" statements into the generated code. Apply with care!
//CODEFINAL
<perl5 code>
/*

    This one has the same functionality and restrictions, as other //CODE's have, and will be inserted after evaluation of the //TEMPLATE variable, but before actual sending of it's text. It can be used to modify some parts of obtained template text before giving it to the user. It is very rare case and was introduced only to complete sequence of code hooks. Apply with care!
//POSTSENT
<perl5 code>
/*

    Specifies perl5 code to be executed upon successful sending of the message. This can be used to do any postprocessing like logging. The variables declared with //VAR and optional texts defined with //OTEXTCOND are available. Any new variables should be declared lexical. It is possible to use the function prompt(promptstring, default) to prompt the user for input. The function returns the user input or the default if the user enters nothing. Apply with care!
//POSTNOTSENT
<perl5 code>
/*

    Specifies perl5 code to be executed if the message was NOT sent for any reason. The variables declared with //VAR and optional texts defined with //OTEXTCOND are available. Any new variables should be declared lexical. It is possible to use the function prompt(promptstring, default) to prompt the user for input. The function returns the user input or the default if the user enters nothing. Apply with care!
//TEMPLATE
<text>
/*
    This is the main text of the form to be sent including the rfc-822 header. Variables including optional text blocks can be interpolated here by prefixing them with $. It is perfectly OK to use double quotes etc...
//REM <text>

     Allows to comment one line of the <text>.
//OTEXT <name> <condition>
<text>
/*
    Note: This format is deprecated, and left only for compatability reasons. Please use //OTEXTCOND instead. This is an optional text block, that will be assigned to the variable <name> if the perl5(1) expression <condition> evaluates to TRUE. Variables that appeared in //VAR part can be interpolated here by prefixing their names with $. If <condition> includes pattern matches the corresponding standard perl5 variables $1, $2, etc, are available. It is perfectly OK to use double quotes etc...
//OTEXTCOND <name>
<perl5 code>
/*
    This is a block of the code, which, when it evaluates to true, leaves variable <name> in the current scope. Otherwise that variable <name> will be assigned the empty string "". Variables that were declared by //VAR or //VARMULTI, can be interpolated inside the block by prefixing their names with $. This is the preffered way to setup conditional texts.

Built-in functions
There are three built-in functions accessible from the form template, and they can be used in code parts of the template. prompt (message, default[, validator_ref]) This is the function that implements the //PRO command, and allows to ask for additional input from the user. message is the prompt that will be shown to the user. default is the default value that will appear in the square brackets in the prompt string and that will be returned if no input was provided. Optinal validator_ref parameter is a reference to the function, that will validate user input. In this case, prompt will cycle untill validator returns true. choice (message, choices_ref, default) This function implements the same functionality which //SELECT has and gives a nice menu of choices, from which you should select one of the items. message is the prompt that will be shown to the user. choices_ref is a reference to an array of items, that shall be shown and choosen from that menu. default is the default value that will appear in the square brackets in the prompt string. giveup (message) Is the function that terminates the running program, giving passed message as an error message. mopper (message) The function that gives a warning message to the user with the line number, there problem is occured.

Special variables
There is at least one variable, that predefined in stt and you shouldn't use the same name for yours. Its name is __FINAL_MESSAGE__. It's also possible to direct access it within the tempalte, notably, from the //CODEFINAL section to modify it.

EXAMPLE
An example template follows below:
# Use version 2.00 extensions to the stt
#
//VERSION 2.00
# short title string, used in listings
#
//TITLE assign network numbers
# Full description of the template
#
//DESCR
This text is used to inform the requester which network numbers
have been assigned to them. It assumes that the corresponding
updates to the database have been done.
/*
# Create message new message
#
//DEFAULT -c
# definition of all variables
#
#     name      reply-deriv             default
#
//VAR toname    "from-name"             ""
//VAR toaddr    "from-addr"             ""
//VAR cc        "cc"                    ""
//VAR fbody     "body/20L"              ""
//VAR signame   ""                      "BUILTIN"
//VAR netnum    ""                      ""
//VAR class     ""                      "C"
//VAR benice    ""                      "y"
//VAR netinfo   ""                      ""
//VARMULTI nice ""
and have a nice day!
/*
# prompt strings (descriptions) of the variables
#
//PRO toname    "name of recipient"
//PRO toaddr    "mail address of recipient"
//PRO netnum    "assigned network number(s)"
//PRO class     "class of assigned network number(s)"
//PRO benice    "be nice (y/n)"
//PRO netinfo   "database info about assigned nets"
# variables to be taken from the command line (in this sequence)
#
//ARGS  toname  toaddr  netnum  class  benice
# variables to be prompted (in this sequence)
#
//ASK   toname  toaddr  netnum  class  benice
# derivations of variables
#
//CODE
$netinfo = `whois $netnum`;
if ($fbody) {
	$fbody =~ s/^/> /gm;
	$fbody = "Your original message started as follows:\n\n" . $fbody;
}
/*
# the template text itself
#
//TEMPLATE
To: "$toname" <$toaddr>
Cc: $cc
From: RIPE NCC Hostmaster <hostmaster@ripe.net>
Subject: Internet Network Number $netnum Assigned
Reply-To: <hostmaster@ripe.net>
X-Organization: RIPE Network Coordination Centre
X-Phone: +31 20 535 4444
X-Fax:   +31 20 535 4445
Dear $toname and colleagues,
This is to inform you that the class $class IP network numbers $netnum
have been issued by the RIPE NCC today. The RIPE database shows the
following information:
$netinfo
Please update your records accordingly.
Any changes in the information should be sent to <auto-dbm@ripe.net>.
$fbody
If you have any questions regarding this matter, please do not hesitate
to contact <hostmaster@ripe.net>.
Thank you for your cooperation $nice
---------
$signame
RIPE NCC
/*
//OTEXTCOND nice
return "yes" if($benice =~ /^[yY]/);
/*
//POSTSENT
print STDERR "Message was sent regarding $netnum.\n";
/*
//POSTNOTSENT
print STDERR "Message was not sent!\n";
/*

SEE ALSO
stt(1), mh(1), passwd(5), perl5(1)

AUTHOR
Daniel Karrenberg <daniel@ripe.net>
Timur Bakeyev <timur@ripe.net>