Filtering output:

Often there is a need to filter some content while it is being output to
the target. Example, text documents sent to the browser or html sent to 
the console or encoding strings in urls.

Filtering is needed to convert text strings on the fly as they are output.
Caravan has a facility to filter the output using the filter statement.
The filtering mechanism in caravan is a powerful and efficient way to 
convert data. The programmer can create custom filters and use them as 
needed.

The filter statements:

All filter statements begin with the keyword 'filter'.

1.Filter "string"="replacementString"
  This is the basic filter statement which causes all ocurrences of "string"
  to be replaced with "replacementstring" in all outputs and assignments
  following this statement. The other filter directives modify the filter action.
  Both the left hand side and right hand side can be variables or constant strings.

  Example:
// define the filter to convert Carriage Return for HTML output
  filter "\r\n"="<br>"
  filter "\r"="<br>"
  filter "\n"="<br>"
  "hello world\r\n"
  "hello world\n"
  "hello world\r"
//  All above strings will be output as "Hello world<br>"

  Interesting thing to note is that the filtering action selects the longest match 
  first for conversion -- "\r\n" is not converted to "<br><br>" though "\r" and "\n"
  both are converted to "<br>" separately.

  Special cases:

   When a filter statement specifies the same string on the right and left hand side
   of the equal sign, the previous definition if any is cancelled for the spercified
   string.
  Example:
  Filter "\r\n"="<br>"
  Filter "\r\n"="\r\n";// removes filtering of "\r\n"
  Filter "<"=""
  Filter ">"=""
  "<hello world\r\n>" ;// is output as "hello world\r\n"

    

2.filter "<filtername>";
 specifies the name of the filter. A filter of this name is created if it does not exist.
 Basically caravan saves the filtering information if a name is specified. A named filter
 created in this way is globally available and can be reused. The syntax of the statement
 is :
 filter "filtername";// filter name is any string.
  
 Note : it is not neccessary to assign a name to use filtering.
 Example:
  Filter "cr"
  filter "\r\n"="<br>"
  filter "\r"="<br>"
  filter "\n"="<br>"


3.filter on
  Switches on filtering;
4.filter off
  Switches off filtering;
5.filter assign;// filter also assignments
  Actvates filter during assignments.
  If a filter is in use the string assignments also get filtered.

  Example:
  filter "1"="one"
  var  x
  x(val)="1";// x(val) is actually  "one"
6.filter output;// filter only outputs -- opposite of 'filter assign'
  Filter action is only for output -- this is default. 
7.filter ignorecase
  Filter ignores case
  Example:
  filter "caravan"="Caravan"
  "caravan,CaraVan,CARAVAN" will be output as "Caravan,Caravan,Caravan"  

8.filter url
  Filters as urlencoded string


filter url is a special filter -- here the next string is output 
as url encoded string and the filter automatically reverts to
previous filter. All characters except "a-z","A-Z","0-9" and ".()-_"
are converted to their url encoded form. For example, SPACE ' '
is converted to "%20".




Example
filter url
var x
x(value)="this is a test"
x(value);// outputs x(value) as "this%20is%20a%20test"
//now filter has reverted to text
x(value);// outputs x(value) as "this is a test"


When the right hand side is a null string "" the specified string is not output.

User defined filters:
------------------

One can also create custom filters by specifying a name.


example : create a new filter which will always output "caravan" as "<b>CARAVAN</b>"

<caravan>
filter myfilter;

filter "caravan"="<b>CARAVAN</b>";

</caravan>


You can now reuse this filter in any caravan script by setting filter to 'myfilter'

<caravan>
filter "myfilter"
file myfile="c:\caravan\caravan.txt"
myfile(file);// output the contents of caravan.txt converting "caravan" to "<b>CARAVAN</b>
             // on the fly.
.....;//
.....;//
</caravan>

Note:There no limitation on the number of conversions per filter.

Since the user defined filters are resources that can be reused, it is best to create them
once and reuse them whenever needed. This can be done by creating a caravan script file
-- a file containing the caravan code with .html extension and placed in the templates path --
with all the user defined filters and running it once automatically using the schedule statement.

<caravan>
schedule=(minute=all&count=1);// runs once at startup
filter userfilter1; //definitions for userfilter1
.....
.....
filter userfilterN;// definitions for userfilterN
.....
.....
</caravan>


This method is the most efficient way to create and use custom filters.

Note: Older versions used the keyword "mode" instead of "filter" which is still
      valid though less intuitive.