bkMacros  -  Compose macros plugin for Becky!
version 1.0 RELEASE [03-Nov-2004]

Copyright  2004 by Code-Breaker Software
http://www.code-breaker.com
Send comments to cbrown@code-breaker.com


/// Description

Provides a set of macros that you can use in your templates and signatures. 
'From' macros are retrieved from account settings. 'To' macros are parsed 
from the compose window's 'To' header. The parser can correctly handle a 
variety of address formats, including:

Paul Krugman <krugman@nytimes.com>
Nicholas D. Kristof <nicholas@nytimes.com>
Safire, William <safire@nytimes.com>
Friedman, Thomas L. <friedman@nytimes.com>
The New York Times <editorial@nytimes.com>

The compose window is processed automatically when it is opened. There is also 
a menu option under Tools>bkMacros!, so you can reprocess if you need to.


/// Package

bkMacros.zip contains:
 bkMacros.dll 
 bkMacros.txt (the file your reading)


/// Installation

1. Close Becky! 
2. Copy the bkMacros.dll file to your Becky! plugins folder
   (default is: c:\Becky!\PlugIns\). 
3. Restart Becky!
4. Incorporate bkMacros into your templates!


/// Macros Available (Case-Sensitive):

** General Macros
$SetHeader(To=me@here.now)    -Set a message header. Must be on own line in template
$GetHeader(Subject)           -Get a message header. Must be on own line in template
$Date                         -Inserts the current date
$Time                         -Inserts the current time
$BeckyVer                     -Inserts Becky!'s version number (e.g., 2.11.02)
$bkMacrosVer                  -Inserts bkMacros' version number (e.g. 1.0)
$DelSig                       -Removes all of the message after (and including) the cutmark
                                The default cutmark is '-- ' (dash dash space) on its own line
                                You can also specify a custom cutmark using $DelSig(cutmark).
                                Useful in reply templates.
$Sig(1)                       -Inserts a signature. If you use $DelSig, your Becky-inserted
                                sig will be deleted, so you need to use this macro instead. 
                                Pass no argument for the default sig (same as $Sig(0)). 
                                **Place this macro at the top of your template, otherwise, it 
                                might be deleted by DelSig!**

** Sender Macros - Retrieved from Account settings
$FromName                     -Full name
$FromFName                    -First name
$FromLName                    -Last name
$FromEmail                    -email address
$FromAccount                  -Account name (What is shown in the folder view)
$FromOrg                      -Inserts organization 
                                (you can set this in Tools>Mailbox Setup>Compose>Organization)

** Recipient Macros - Parsed from compose window's To header
$ToName
$ToFName
$ToLName
$ToEmail
$ToABNick                     -Inserts the address book Nickname (matched by 'To'
                                email), if present; otherwise, First name. Useful for
                                informal greetings like 'Hi Joe,'
$ToABValue(X-BECKY-NICKNAME)  -Inserts a value from the addressbook (this example 
                                will insert the nickname)
$ToUserName                   -Inserts the part of the email address before the '@'
$ToDomain                     -Inserts the part of the email address after the '@'

** Selected Message Macros - Retrieved from the message currently selected in Becky!
     (useful when replying to a mailing list message)
$SelFromName                  -Full name of the sender of the selected message
$SelFromFName                 -First name of the sender of the selected message
$SelFromLName                 -Last name of the sender of the selected message
$SelFromEmail                 -email address of the sender of the selected message


/// Example (A good Becky mailing list template):

** Begin template
$Sig(1)
$DelSig(------------------------ Yahoo! Groups Sponsor)
$DelSig
Hi $SelFromFName,

%M
** End template

...and the signature
$Sig argument is zero-based. My Beckymail sig happens to be the second in the list; hence $Sig(1)

** Begin signature
-- 
$FromFName $FromLName
Using Becky! version $BeckyVer
with bkMacros version $bkMacrosVer
** End signature


...might produce the following in the compose window:

Hi Jody,

> Jody's message quoted here
> without the yahoo adds

-- 
Christopher Brown
Using Becky! version 2.11.02
with bkMacros version 1.0 BETA3

/// Liability Disclaimer

Your not allowed to sue me! Called it!


///Credits

-Kick-ass regex support is provided by RegexpStudio.com


/// Known Bugs / Limitations

-The address book macros only search in the default ab, and do not recurse into
others. 
-No unicode support. This might be a possibility in the future. 
-Why 'SelFrom'? Why not 'OSender' (for 'Original Sender', as in TheBat!)? Because the 
Becky plugin api doesn't provide a means of accessing the reference message (short of 
brute-force database searching, which is obviously impractical), but we do have 
access to the selected message. And since this will be the reference message in 
almost all situations in which we are replying (select a message, click reply) its 
not a bad solution. 
-Why does the $Sig macro insert the signature as mere text, not a real Becky Sig 
(with a different color, and changeable from the signature pull-down)? Because Becky
doesn't provide an API function to add a sig, so it has to be done by brute-force, by
appending the text of the sig to the text of the message. So what's the point? This 
Because if you use $DelSig, you would have to re-add your sig 
Becky's signature 


/// Change Log
  + = Added feature
  * = Improved/changed feature
  - = Bug fixed

1.0 [28-Oct-2004] [BETA1] 
First public release

1.0 [29-Oct-2004] [BETA2] 
+ Added macros: $Sig, $BeckyVer, $bkMacrosVer 
* Cleaned up regex on $DelSig.

1.0 [31-Oct-2004] [BETA3] 
+ Added macros: $SelFrom set, $GetHeader, $SetHeader 
+ Fixed version numbers to correctly show Betas.
- Removed macros: $Header

1.0 [02-Nov-2004] [BETA4] 
* FName macros now display value when name is a single word. LName macros display ''
* DelSig macro can now be called multiple times. 
* Significantly improved the matching performance with name parsing. Handles accents, etc.. 

1.0 [03-Nov-2004] [RELEASE]
* Cleaned up regex a bit more
* Now handles names with 4 words. First is FName, 4th (last) is LName.

--
