The Complete Filter Script Template

Top Previous Next

Note: The InputFile and OutputFile sections are not required for most scripts. For more information, please see The Filter Script.

<Name>

(Parameter), static input filename

</Name>

True, (False) - deletes the Input File, even if <Abort> is used

</Delete>

</InputFile>

<OutputFile> - not used if the .dll version of the filter is running the script

<Name>

(InputFile), static output filename

</Name>

</OutputFile>

<Debug>

True, (False)

</Active>

</Console>

<File>

True, (False)

</Active>

<Name>

debug log filename

</Name>

True, (False) - appends to existing file instead of recreating it

</Append>

</File>

True, (False)

</LogInputFile>

True, (False)

</LogOutputFile>

</Debug>

<Filter>*

optional comment text that will be shown in debug output

</Comment>

If you are using the <Goto> tag for looping, then the filter you want

to jump back to must have a name

</FilterName>

<Lookup> - if the Lookup section is included, no other sections are processed (i.e. <MatchFound> and <MatchNotFound> are not run

(All), Recipient, Sender, Message, Temp1-10

</Variable>

True, (False)

</CaseSensitive>

True, (False) - If False, leading and trailing spaces are ignored (otherwise they need to match exactly)

</SpaceSensitive>

<List>

A list of comma separated values - one per line

or a filename that contains the list

If the text in the <Variable> text matches the first value of a pair in the list,

the second value in the pair is substituted for it

Multiple values can be included in the first value by separating them with | symbols

Values can be quoted - if so use two quotes in a row ("") to include

a single quote in the value's text

If no match is found, and the last pair in the list have a * for it's first

value, then this will be used as a default value

Comments: any line of text with a pound sign (#) as the very first character

(no leading spaces or tabs) will be considered a comment, and ignored.

</List>

</Lookup>

<Type>

(Literal), RegEx, GreaterThan, LessThan - for GreaterThan and LessThan, <Variable> is GreatherThan/LessThan <Text> </Type>

(All), Recipient, Sender, Message, Temp1-10, Flag

</Variable>

<Text>*

search text, True, False

must be quoted to retain beginning and/or ending whitespace

</Text>

</Search>

<MatchFound> - if you don't include a <Search> section,

<Replace> - multiple Replace sections are allowed

<Type>

(Literal), RegEx, And, Or - And/Or sets Flag equal to Flag And/Or <Text>

</Type>

(All), Recipient, Sender, Message, Temp1-10, Flag

</Variable>

<Scope>

(Match), Entire - replace only the matched text, or the entire variable's contents

</Scope>

True, (False) - replaces all matches in the variable

</ReplaceAll>

<Text>*

replacement text, True, False

must be quoted to retain beginning and/or ending whitespace

</Text>

</Replace>

<Name>*

if match found, filename to save to - most macros are valid

</Name>

(All), Recipient, Sender, Message, Temp1-10

</Variable>

</WriteFile>

<Run>

<Command>*

run this command (no spaces in folders or filenames)

</Command>

<Async>

(True), False - if true, the filter continues immediately, if false it waits for

the program it started to finish

</Async>

<Show> - true give the program a window to run in, false hides the program

True, (False)

</Show>

</Run>

<SettingsFile>*

path and name of new filter settings file

</SettingsFile>

(), All, Recipient, Sender, Message, Temp1-10

name of the variable that holds the text to be sent to the filter

* if Variable is used (and not empty), the InputFile value is ignored

</Variable>

path and name of input file - ignored if Variable section is set

</InputFile>

path and name of debug file

</DebugFile>

True, (False)

</AppendDebug>

True, False - if pgfilter.dll is running, then default value is True, otherwise it is False

</UseDll>

</RunFilter>

<Name>*

if match found, filename to read - most macros are valid

</Name>

(All), Recipient, Sender, Message, Temp1-10

</Variable>

True, (False) - delete the file after reading it

</Delete>

</ReadFile>

<Goto>

Name of filter to jump to - *** be careful not to make infinite loops

</Goto>

<Abort>

True, (False) - exit without writing to the Output File (which is the Input File by default)

</Abort>

(True), False - whether or not to continue processing the next filter block

</Continue>

<MatchNotFound> - this section is always run if there is no <Search> section

<Replace> - multiple Replace sections are allowed

<Type>

(Literal), And, Or - And/Or sets Flag to Flag And/Or replacement Text

</Type>

(All), Recipient, Sender, Message, Temp1-10, Flag

</Variable>

<Text>*

replacement text, True, False

must be quoted to retain beginning and/or ending whitespace

</Text>

</Replace>

<Name>*

if match found, filename to save to - most macros are valid

</Name>

(All), Recipient, Sender, Message, Temp1-10

</Variable>

</WriteFile>

<Run>

<Command>*

run this command (no spaces in folders or filenames)

</Command>

<Async>

(True), False - if true, the filter continues immediately, if false it waits for

the program it started to finish

</Async>

<Show> - true give the program a window to run in, false hides the program

True, (False)

</Show>

</Run>

<SettingsFile>*

path and name of new filter settings file

</SettingsFile>

(), All, Recipient, Sender, Message, Temp1-10

name of the variable that holds the text to be sent to the filter

* if Variable is used (and not empty), the InputFile value is ignored

</Variable>

path and name of input file - ignored if Variable section is set

</InputFile>

path and name of debug file

</DebugFile>

True, (False)

</AppendDebug>

True, False - if pgfilter.dll is running, then default value is True, otherwise it is False

</UseDll>

</RunFilter>

<Name>*

if match found, filename to read - most macros are valid

</Name>

(All), Recipient, Sender, Message, Temp1-10

</Variable>

True, (False) - delete the file after reading it

</Delete>

</ReadFile>

<Goto>

Name of filter to jump back to - be careful not to make infinite loops

</Goto>

<Abort>

True, (False) - exit without writing to the Output File (which is the Input File by default)

</Abort>

(True), False - whether or not to continue processing the next filter block

</Continue>

</Filter>

<Filter>...

Notes:

Sections with * are required

Values in () are default values if section is not present

The first commandline parameter is the name of the InputFile to be processed

If an <InputFile><Name> section is used, its value overrides the commandline parameter value

The default settings file name is pgfilter.xml

The settings file name can be set by using settingsfile= as a parameter on

the commandline. The input file name would then be the next parameter

The debug file name can be set by using debugfile= as a parameter on

the commandline. The input file name would then be the next parameter

By default, when writing debug info to a file, the file is recreated each time

Using the commandline parameter debugappend=true will append to the file instead

*** WARNING *** don't leave debugappend set for long periods, because the file

will keep growing forever

OutputFile, ReadFile, WriteFile support variables (in addition to the normal ones):

%InputFilePathAndName%

%InputFilePath%

%InputFileName%

%InputFileNameBase%

%InputFileNameExtension%

%FilterIndex%

Section values for Recipient, Sender, Message, and All really just mean:

Recipient: first line of text,

Sender: second line of text,

Message: third and remaining lines of text

All: the entire contents of the file

Literal search text special characters:

~ as first character means the start of the variable's contents

~ as last character means the end of variable's contents

? matches a single character

* matches anything (including nothing)

\ following 3 digits are a decimal character value

the ~, ?, *, and \ characters must use \ with decimal equivalent to be used literally

RegEx replacement:

Backreferences are allowed in replacement text (i.e. \1 \2 \3 ...)

\r, \n, and \### (3 digits) literals are supported for inserting CR, LF, and ASCII

Literal search text variables

%Recipient% - the current value for Recipient

%Sender% - the current value for Sender

%Message% - the current value for Message

%All% - the current value for All of the text

%Temp1-10% - the current value for that Temp variable

\ following 3 digits are a decimal character value

Literal replacement text variables:

%Recipient% - the current value for Recipient

%Sender% - the current value for Sender

%Message% - the current value for Message

%All% - the current value for All of the text

%Match% - the actual text that matched the search text (Literal or RegEx match types)

%Group1-10% - RegEx group backreferences obtained from a RegEx search

%Temp1-10% - the current value for that Temp variable

%InputFileName% - the name of the input file being processed

%Year%, %Month%, %Day%, %MHour%, %Hour%, %Minute%, %Second%, %MSecond%, %AMPM%

%Unique% - unique number - guaranteed unique to the computer - pretty unique otherwise

\ following 3 digits are a decimal character value

Functions:

Format is %FunctionName(input-value)% - it will be replaced with the function's output value

%DateTimeToUnixTime()%

The default value of the Temp1-10 variables are an empty string

The default value of the Flag variable is false

Comments: The <Comment> section can be used in each <Filter> and it will b output

in the debug log, or any line of text with a pound sign (#) as the very first

character (no leading spaces or tabs) will be considered a comment, and ignored,

and also not logged

The Recipient, Sender, Message and ALL variables are dynamically linked together. So, for

example, if you change the Sender, the first line of All will also be updated. Changing

All will update the Recipient, Sender and Message parts

When the order of things matter:

<Filter> block are executed in the order they appear (unless <Goto> is used)

In a <Filter> block:

<Search> (if it exists) runs first and determines if the <MatchFound> or <MatchNotFound> block is run

<Replace> <WriteFile> <Run> <RunFilter> <ReadFile> <GoTo> <Abort> <Continue> run in that order

There can be multiple <Replace> <WriteFile> <Run> <RunFilter> <ReadFile> blocks and they will run

in the order they appear - i.e. all <Replace> blocks will run, then all <WriteFile> blocks, etc.

RegEx uses a Pearl compatible implementation syntax

good reference: http://www.regular-expressions.info/tutorialcnt.html

Breaking changes

<Section></Section> is renamed to <Variable></Variable>

In the <Replace> section the <All></All> tag has been renamed to <ReplaceAll></ReplaceAll>

In the <Replace> <Scope> section the value: 'Section' is renamed to 'Entire'

All exiting <Replace> section have to be surrounded with <MatchFound></MatchFound> tags

Recipient, Sender, Message and All are new dynamically linked together

Bare Filter Template - for easier cuttting/pasting

* in sections with multiple value options, the first in the list is the default value

<Name>

Parameter

</Name>

False, True

</Delete>

</InputFile>

<Name>

InputFile

</Name>

</OutputFile>

<Debug>

False, True

</Active>

</Console>

<File>

False, True

</Active>

<Name>

</Name>

False, True

</Append>

</File>

False, True

</LogInputFile>

False, True

</LogOutputFile>

</Debug>

</Comment>

</FilterName>

All, Recipient, Sender, Message, Temp1-10

</Variable>

False, True

</CaseSensitive>

False, True

</SpaceSensitive>

<List>

</List>

</Lookup>

<Type>

Literal, RegEx, GreaterThan, LessThan

</Type>

All, Recipient, Sender, Message, Temp1-10, Flag

</Variable>

<Text>

</Text>

</Search>

<Type>

Literal, RegEx, And, Or

</Type>

All, Recipient, Sender, Message, Temp1-10, Flag

</Variable>

<Scope>

Match, Entire

</Scope>

False, True

</ReplaceAll>

<Text>

</Text>

</Replace>

<Name>

</Name>

All, Recipient, Sender, Message, Temp1-10, Flag

</Variable>

</WriteFile>

<Run>

</Command>

<Async>

True, False

</Async>

<Show>

False, True

</Show>

</Run>

</SettingsFile>

, All, Recipient, Sender, Message, Temp1-10

</Variable>

</InputFile>

</DebugFile>

False, True

</AppendDebug>

True, False

</UseDll>

</RunFilter>

<Name>

</Name>

All, Recipient, Sender, Message, Temp1-10, Flag

</Variable>

False, True

</Delete>

</ReadFile>

<Goto>

</Goto>

<Abort>

False, True

</Abort>

True, False

</Continue>

<Type>

Literal, And, Or

</Type>

All, Recipient, Sender, Message, Temp1-10, Flag

</Variable>

<Text>

</Text>

</Replace>

<Name>

</Name>

All

</Variable>

</WriteFile>

<Run>

</Command>

<Async>

True, False

</Async>

<Show>

False, True

</Show>

</Run>

</SettingsFile>

, All, Recipient, Sender, Message, Temp1-10

</Variable>

</InputFile>

</DebugFile>

False, True

</AppendDebug>

True, False

</UseDll>

</RunFilter>

<Name>

</Name>

All, Recipient, Sender, Message, Temp1-10, Flag

</Variable>

False, True

</Delete>

</ReadFile>

<Goto>

</Goto>

<Abort>

False, True

</Abort>

True, False

</Continue>

</Filter>