SpaceScript» Packages Back »

See It In Action View an email package in action on live EDGAR data. View Example »

Explicit Packages

       The two packages that can be explicitly imported for use in SpaceScript at this time are email and strings. These packages are often used together to create and send email based on contents of blocks data. The strings package is used for string operations such as concatenation and substitution.

The Email Package

       This section presents a brief description of the SpaceScript email package. This package is based on the Tcl MIME package written by Marshall T. Rose. Please refer to that documentation for additional information.

       To use the email package a SpaceScript user must first include, in a SpaceScript section of their template, the line:

"import email;"

This line causes SpaceScript to load the email functions for use by the template. All email function calls must be made after the import statement.

The most frequent usage of the email package will have the following steps:

• Call email.init() to create a new email.
• Make multiple calls to email.setHeader() to set the subject line, addresses, etc.
• Call email.send() to send the email to the recipients.
• Call email.fin() to close the email.

Sending an email does not close the email since you may want to send it to multiple recipients with each message having some slightly modified personalized information.

Suppose we execute a query and care only about the first result. In fact, we want to send the company name of the first document to an email address that is passed as a hidden option on the query form. The SpaceScript template file would include the section:

An E-mail Example

<?SPACESCRIPT?>   import email;   email.init("eHandle","text/plain","","","","","", iw.ss.token(end001,   This email message is the result of automated processing of an Edgar query   using Invisible Worlds' SpaceScript language.   We are looking forward to seeing you at http://invisible.net !   ,end001));   customer=getOption("user.publish.email.sendto");   cname=formatName(getValue(getElement(getBlock(0),"conformed.name",0)),"");   email.setHeader("eHandle","To",email.formAddress("Our Valued Customer",customer),"write");   email.setHeader("eHandle","From",email.formAddress("Edgar","web@invisible.net"),"write");   email.setHeader("eHandle","Subject",addRange("The Conformed Name Was: ",cname),"write");   email.send("eHandle");   email.fin("eHandle","all");   <?/SPACESCRIPT?>

       We shall explain the email.init() call and its parameters in a moment. First, a few comments on the above example.

       This example passes the recipient of this email to SpaceScript via the option user.publish.email.sendto, which is set up via a type-in entry on the query form. The template then accesses it via the SpaceScript getOption() function. Any option you wish an end user to provide can be sent to your SpaceScript template via this mechanism.

       After initialization of an email message we set the contents of the "To", "From", and "Subject" lines in the header, with the subject line containing the conformed.name data from the first block. After the header information has been set we then send and finish the email.

       One further note before the detailed definition of functions and arguments is that every email function except email.formAddress() must be passed a string as the first argument that is used to "name" the email object. This allows you to create multiple emails simultaneously by giving them different names. The first argument in every email function call must be an email name. The email.init() call will initialize the email and assign the name to it. The email.fin() call will remove the name and associated data. A name can be reused after it has been removed by making an additional call to email.init().

E-Mail Package Functions
Function		Arguments		Description
email.init		(1) msgName (2) canonical (3) toAddr (4) fromAddr (5) ccList (6) bccList (7) subjectLine (8) partContent		The msgName will be assigned to the email that is created. This name must not already be in use as an email message name. Use the name in subsequent email function calls to operate on this email. The canonical argument indicates the MIME type. The toAddr, fromAddr, ccList, bccList, and subjectLine arguments are as they should appear in the email message.
email.getProperty		(1) msgName (2) [propName]		Returns a property value or all property names and values. The msgName is the name of the email on which this call should operate. An existing name must be used. The propName argument is an optional argument. If a valid property name is supplied, then the value of that property is returned. If "*" is supplied as the argument, then all properties are returned in a list of name, value pairs. The default value for propName is "*", that is, all property values. Valid propName arguments are: content : the content type or subtype encoding : the content transfer encoding params : a list of content-type parameters parts : a list of subordinate names size : the approximate size of the content * : returns name, value pairs for all properties
email.getHeader		(1) msgName (2) [keyName]		Returns the value of a header or all header names and values. The msgName is the name of the email to operate on. The optional argument keyName is the name of the header item to return. Valid keyName values include: to, from, cc, bcc, and subject. The default value for keyName is "*", that is, all header values.
email.setHeader		(1) msgName (2) keyName (3) value (4) [mode]		Sets the value for the specified header item. The msgName is the name of the email to operate on. The keyName is as described for getHeader(). The value must be a valid value for the associated keyName. The optional argument mode may be one of {write, append, delete} and describes the operation to perform. The default value for mode is "append". If delete is used, then the value argument is ignored.
email.formAddress		(1)name (2)addr		Creates a nicely formatted email address from a person's name and email address. Any string, such as "My dear friend Bob", can be used for the name. NOTE: this function does not have msgName as the first argument.
email.send		(1) msgName (2) [options]		The msgName is the name of the email to send. The optional argument options can be any string of options acceptable to the Tcl MIME smtp::sendmessage procedure. The default for options is the null string, "".
email.initAdvanced		(1) msgName (2) args		The msgName is the name of the email to send. This function allows advanced users, or users familiar with the Tcl MIME package, to supply their own argument string to that package's initialize procedure. The msgName will be assigned to the email that is created. The args argument should be a string that is compatible with the options as specified to the MIME package initialize procedure.

       The following example contains inline comments, so that you understand what is going on by just reading the code:

Another E-mail Example

<?SPACESCRIPT tokenizer="iw.ss.token"?>   import strings;     // here we import the local strings package   quote=iw.ss.token(s,",s);     // just for ease of use...   first="Marco";   middle="R.";   last="Gazzetta";   full=addRange(addRange(first,middle),last);     // full and glued will be different, because   glued=strings.add(first,middle,last);     // addRange separates with spaces, and                                                                      // strings.add doesn't   sep=strings.join(first,middle,last,"||");     // will look like: John||S.||Doe   part=strings.range(full,"5","8");     // will return ' R.'   len=strings.length(full);   char=strings.index(full,"5");   format=strings.format(iw.ss.token(END,First: %s; Middle: %s; Last: %s <BR>Weird number: %02x,END)   , first, middle, last,"23");     // %02x will be formatted as 'hexadecimal' number   pub("Testing string functions<BR>");   if (strings.match(full,strings.add(first,"*"))) {     // full will match first* !       pub("strings matched<BR>");   } else {       pub("strings didn't match<BR>");   }   types="alnum alpha digit control double integer lower upper";   strings="1 Daniel {x 1} r5";   for (s=0; s<getCount(strings); s++) {       for (t=0; t<getCount(types); t++) {           string=getIndex(strings,s);           type=getIndex(types,t);           is=strings.is(type,string);           if (is) {               not = "";           } else {               not = " not";           }           pub(strings.add(quote,string,quote," is",not," of type ",type,"<BR>"));       }       pub(strings.add("And ",first,"'s last name with the first letter of the string would be:<BR>"));       pub(strings.add(strings.convert("upper",strings.index(string,"0")),strings.range(last,"1","end"),"<BR>"));   }   pub(strings.add("|",strings.trim("   space   "),"|<BR>"));   pub(full);   pub("<BR>");   pub(glued);   pub("<BR>");   pub(sep);   pub("<BR>");   pub(part);   pub("<BR>");   pub(len);   pub("<BR>");   pub(char);   pub("<BR>");   pub(format);   pub("<BR>");   <?/SPACESCRIPT?>

The Strings Package

       This section presents a brief description of the SpaceScript strings package. This package is based on the string manipulation functionality available in Tcl and enables a SpaceScript user to manipulate and operate on character strings. To use the strings package a SpaceScript user must include the SpaceScript line:
"import strings;"

String Package Functions
Function		Arguments		Description
string.add		(1) args		This function concatenates the supplied arguments into a single string. There may be any number of argument strings. No characters will be added between the arguments.
strings.join		(1) args		This function concatenates all arguments except the last into a single string. The last argument will be inserted between each of the argument strings.
strings.range		(1) string (2) first (3) last		This function returns a substring of string. The substring returned is from character first to last, each of which must be an integer. The first character of a string is at index 0.
strings.length		(1) string		Returns the integer number of characters in string.
strings.index		(1) string (2) index		Returns the character of string at index. The first character of string has index 0.
strings.format		(1) formatStr (2) args		This function works similarly to the C printf function. The formatStr argument provides the formatting instructions for the arguments supplied in the args argument.
strings.match		(1) string (2) pattern
strings.is		(1) string (2) type		This function returns one of the integer values 0 or 1, with 0 for "false" and 1 for "true". The value returned is based on whether the argument string is of type type. The argument type can be any one of alnum, alpha, ascii, control, boolean, digit, double, false, graph, integer, lower, print, punct, space, true, upper, wordchar, or xdigit.
strings.replace		(1) string (2) first (3) last (4) newStr		Returns a new string created by replacing the characters of string at indices first through last with newStr.
strings.convert		(1) string (2) case		Return a new string created by converting string to one of the valid values of case. Valid values for case are lower, upper, or title. Converting a string via title will convert all characters to lowercase except the first, which is converted to uppercase.
strings.trim		(1) string (2) side		Return string with any whitespace on side removed. The argument side may be one of left, right, or both.

 Copyright © 2000 Invisible Worlds. All Rights Reserved.

contact | about | site map | home