Becky! Advanced Template Plug-In version 1.0.0 beta 4

Author: Takeshi Ogue
Web   : http://pages.prodigy.net/tak09/index.htm
Mail  : tak09@prodigy.net

Becky! Advanced Template Plug-In lets you customize your favorite
Becky!'s template libraries.  It gives you access to the information
in the reference mail, as well as access to some system resources, and
lets you output in any format you like.

The interpreter script that Advanced Template Plug-In supports is
called Poor-Pascal for Application (PPA) which is developed by Project
PPA (P3A).  PPA is Pascal-Like localized script.  It supports basic
functionality of Pascal and some add-on functions/procedures.  Those
functions/procedures may act somewhat different from Pascal/Delphi, in
fact, it only supports integer and string variables.

Advanced Template (ATML) has some local rules in addition PPA's local
rules. The first line must contain "begin_atml."  It must be commented
out because there is no such call in ATML.  Here are some examples of
ATML scripts:

---------
// begin_atml
// change greetings according to the sender

if Pos('.jp',refFrom) > 0 then // if 'From' field contains '.jp'
  println('Konnichi-wa!')    // which is usually from Japan
else
  println('Howdy!');
---------

Here's another

---------
// BEGIN_ATML
// change greetings according to the current time

if StrToInt(Hour) < 12 then
  println('Good morning!')
else if StrToInt(Hour) < 18 then
  println('Good afternoon!')
else
  println('Good evening!');
---------

Like Pascal, ATML supports multiple statements enclosed with 'begin'
and 'end.'  Following variable declaration, you need to enclose the
body of the function with 'begin' and 'end'.

---------
// Begin_atml
// Sample of using variables and multiple statements
var
  a: Integer;
  s: String;
begin
  for a := 1 to 10 do
  begin
    s := IntToStr(a) + ' ' + IntToStr(a*a);
    println(s);
  end;
end;
---------

Again, ATML and PPA is Pascal-Like language so you cannot print or
assign an integer without converting it to a string, by using
IntToStr() function.  And as you can see, ATML is case inSenSitivE.


Here are some limitations of ATML.

- first line must contain 'begin_atml'
- there are no real or floating variables
- all functions and procedures cannot omit arguments
  i.e) adding blank line is "println('')"
- since PPA is a new project (actually P3A was just established in
  August of this year- 2000) it may contain some unknown bugs
- String comparison is not supported.  Use 'CompareStr(StrA, StrB)'
  function.

There are some constants that are defined in ATML (not in original PPA).

* refFrom - contains 'From:' field (if composing mail has reference)
* refDate - contains 'Date:' field (if composing mail has reference)
* refTo   - contains 'To:' field (if composing mail has reference)
* refSub  - contains 'Subject:' field (if composing mail has reference)
* refLines- contains number of lines original message has
* Now     - contains current time (this is not a function)
* Hour    - contains current hour in 'hh' format
* Minute  - contains current minute in 'nn' format
* Today   - contains current date (this is not a function)
* Date    - contains current date in 'dd' format
* Month   - contains current month in 'mm' format (digits)
* Year    - contains current year in 'yyyy' format
* DoW     - contains cuurent day of the week in 'ddd' format
* Ver     - contains Becky!'s version
* Beta    - contains Becky!'s beta version

The format of 'Now' and 'Today' follows Windows' short time system
format. You have to restart Becky!2 in order to change date/time
format once you've changed the settings.

These are all string constants.  If you want to compare them as
Integer, you have to use StrToInt() function.  See examples above.



*******************

Followings are the built-in ATML functions/procedures.

  procedure Attach(S: String);
    Attach a file to mail.

  procedure println(S: String);
    Print string to mail body.

  procedure SetHeader(Header,Value: String);
    Set specified header.

  procedure OriginalMessage(S: String);
   Print original message with quote symbol string.

  procedure ReadFromFile(FilePath: String);
    Read text file and print them out.
    Please refer FileExists function.

  procedure Message(I1,I2:Integer;S:String);
    Print original message from line I1 to Line I2 with quote symbol.

  procedure SetSignature(S: String);
    Set signature.

  procedure ShowMessage(S: String);
    Show simple message box.

  function GetHeader(S: String): String;
    Return specified header from reference mail.
    i.e) println(getheader('X-Mailer'));

  function Rand(I: Integer): Integer;
    Return randomized number from range of (0 < I).

  function  StringAt(I:Integer):String;
    Return string at Ith line.

  function  FileExists(FilePath: String): Integer;
    If file exists function return -1 (True).  If not, return value is
    0 (False).  Please use ReadFromFile function with this function to
    prevent from error.


*******************

Followings are the brief language reference of Poor-Pascal for
Application.

Variables
  As I stated above, PPA supports Integers and Strings only.  PPA
  computes Integers as Int64 internally so if you need floating
  computations, you may be able to multiply 100 or 1000 in order to
  compute those and divide by 100 or 1000 later.  Arrays are not
  supported in PPA.

Constants
  There are three constants PPA supports.  True(-1), False(0), and
  Nil(Null).

Reserved words
  There are several words which are reserved by PPA and ATML.  The user
  cannot declare them as variables.  If so, the program will return
  errors.
  These reserved words are:

  and    begin  case    div     do
  downto else   end     for     if
  mod    not    of      or      repeat
  shl    shr    string  then    to
  until  var    while   xor

  and ATML defined constants (see above).

String comparison is not supported, however string concatenation is
supported.
  i.e) ABC := 'ABC' + '123';

Comments
  Comments must begin with '//' there are no {} or (**) or anything
  of the sort... so give it up!

Other supported statements
  if
  repeat
  while
  for
  case

  these statements act almost perfectly like Pascal/Delphi.  Please
  read any Pascal or Delphi language reference book if you need to
  know how to use them.

Operators
  ()    Shows which statement execute first

  not   Negate following statement

  *     Multiplication
  div   Division
  mod   Remainder
  and   Logical and
  shl   Logical shift left
  shr   Logical shift right

  +     Addition
  -     Subtraction
  or    Logical or
  xor   Exclusive or

  :=    Assignment
  =     Equal to
  <>    Not equal to
  <     Less than
  >     Greater than
  <=    Less than or equal to
  >=    Greater than or equal to

PPA built-in string functions

  function CompareStr(S1, S2: String): Integer;
    Compare two strings.  Returns 0 if these are the same, if S1 > S2
    then it returns integer larger than 0, otherwise returns smaller
    than 0.

  function Copy(SFString; Index, Count: Integer): String;
    Returns selected strings.
    i.e) Copy('abcdef',2,3) returns 'bcd'

  function Delete(S:String; Index, Count: Integer): String;
    Returns strings which the selection is deleted.
    If 'Count' is too big, it deletes until the end of the string.
    i.e) Delete('abcdef',2,3) returns 'aef'

  function Insert(Source: String; S: String; Index: Integer): String;
    Returns strings which the specified string is inserted.
    i.e) Insert('It is a good day!', ' very ', 8) returns 'It is a
    very good day!'

  function Length(S: String): Integer;
    Return the length of specified string.

  function LowerCase(S: String): String;
    Make string lowercased.

  function Pos(Substr: String; S: String): Integer;
    Returns the index where the substring begins.  It returns 0 if no
    substring is found.
    *** String is CASE SENSITIVE in Pos() function ***

  function Trim(S: String): String;
    Returns the string which blankspaces and operators at the
    beginning and the end of the string are removed.

  function TrimLeft(S: String): String;
    Act like Trim() except it won't trim blankspaces and operators at
    the end of string.

  function TrimRight(S: String): String;
    Act like Trim() except it won't trim blankspaces and operators at
    the beginning of string.

  function UpperCase(S: String): String;
    Make string UPPERCASED

PPA built-in integer functions

  function IntToStr(Value: Integer): string;
    Convert integer to string

  function StrToInt(S: string): Integer;
    Convert string to Integer.  If string is not convertable, it
    returns 0.

PPA built-in message/dialog routine

  function InputBox(ACaption, APrompt, ADefault: String): String;
    Popup window for user input.
    i.e) InputBox('Please type your gender', 'Male/Female?','Unknown')

  function MessageBox(Text, Caption: String; Flags: Integer): Integer;
    Popup window for user notification.  Caption field is a option.
    Please refer Win32 API help for 'Flags' parameter.  See 'TextType'
    section.

PPA built-in system routine

  function Exec(Path, CmdLine: String; Wait: Integer): Integer;
    Execute program.  Add command line parameters to 'CmdLine'.
    Set 0 for 'Wait' if you do not wish to wait until the end of
    executed program.  Set -1 if you wish to wait.  This function
    returns False(0) when execution failed or terminated by errors.

  function Shell(Path, CmdLine: String): Integer;
    Open a file specified at 'Path' field.  Add CmdLine option when
    you want to execute .exe file.  This function returns error value
    if any.  Please refer to Win32 API help.  See ShellExecute()
    section.

  procedure Sleep(Millisecond: Integer);
    Stop process for certain amount of time.

PPA built-in procedures

  procedure Break
    Stop forCwhile, or repeat statement and resume from next
    statement.

  procedure Continue;
    Flows to next forCwhile, or repeat loops.  Calling 'Continue'
    from other statement results in undefined act.

  procedure Exit;
    Exit from current procedure.

Other PPA built-in functions/procedures

  function IsDefine(S: String): Integer;
    Returns True(-1) if keyword is defined by application.
    *** ATML 1.0a does not define any keyword. ***
