FilterPlugin < TWiki

<!--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
-->
---+!! <nop>%TOPIC%
%TOC%
This plugin allows to substitute and extract information from content by
using regular expressions.

---++ Syntax Rules

---+++ SUBST
*Syntax*: =%<nop>SUBST{topic="..." ...}%= 

insert a topic by processing its content.

   * =topic="..."=: name of the topic text to be processed 
   * =pattern="..."=: pattern to be extracted or substituted 
   * =format="..."=: format expression or pattern substitute 
   * =header="..."=: header string prepended to output
   * =footer="..."=: footer string appended to output
   * =limit="&lt;n>"= maximum number of occurences to extract or substitute counted from the 
     start of the text (defaults to =100000= aka all hits) 
   * =skip="&lt;n>"= skip the first n occurences
   * =exclude="...": skip occurences that match this regular expression
   * =expand="on,off"=: toggle expansion of TWiki markup before filtering
     (defaults to =on=) 

---+++ STARTSUBST, STOPSUBST
*Syntax*:
<verbatim>
%STARTSUBST{...}% 
... 
%STOPSUBST%
</verbatim>

substitute text given inline. see [[#SUBST][SUBST]].

---+++ EXTRACT
*Syntax*:=%<nop>EXTRACT{topic="..."  ...}%= 

extract text from a topic. see [[#SUBST][SUBST]].

---+++ STARTEXTRACT, STOPEXTRACT
*Syntax*:
<verbatim>
%STARTEXTRACT{...}% 
... 
%STOPEXTRACT%
</verbatim>

extract content given inline. see [[#SUBST][SUBST]].


---+++ FORMATLIST
*Syntax*: =%<nop>FORMATLIST{"&lt;list>" ...}%

formats a list of items. The &lt;list> argument is separated into items by using
a split expression; each item is matched agains a pattern and then formatted
using a format string while being separated by a separator string; the result is
prepended with a header and appended with a footer in case the list is not empty.
	* &lt;list>: the list 
	* split="...": the split expression (default ",")
	* pattern="...": pattern applied to each item (default "\s(.*)\s")
	* format="...": the format string for each item (default "$1")
	* header="...": header string
	* footer="...": footer string
	* separator="...": string to be inserted between list items
	* limit="...": max number of items to be taken out of the list (default "-1")
        * skip="...": number of list items to skip, not adding them to the result
	* sort="on,off,alpha,num" order of the formatted items (default "off")
	* reverse="on,off": reverse the sortion of the list
	* unique="on,off": remove dupplicates from the list
	* exclude="...": remove list items that match this regular expression
The pattern string shall group matching substrings in the list item to which you can refer to by 
using $1, $2, ... in the format string. Any format string (=format=, =header=, =footer=) may
contain variables =$percnt$=, =$nop=, =$dollar= and =$n=. The variable
=$index= referse to the position number within the list being formatted; using =$count= in the
footer or header argument refers to the total number of list elements.


---++ Examples

---+++ Secure Html
%STARTSUBST{pattern="<(a href=\"javascript:.*?)>(.*?)</a>" format="&lt;$1&gt;$2&lt;/a&gt;"}%
<a href="javascript:window.alert('Pop me up');">Pop me up</a>
%STOPSUBST%

---+++ Format Comments
| *Date* | *Author* | *Headline* |
%EXTRACT{topic="%TOPIC%" expand="off" pattern=".div class=\"text\">.*?[\r\n]+(.*?)[\r\n]+(?:.*?[\r\n]+)+?-- (.*?) on (.*?)[\r\n]+" format="| $3 | $2 | $1 ... |$n"}%

%STARTINCLUDE%
<div class="text"><div class="comment">
This is a first comment.
This is a first comment.
This is a first comment.
</div><div class="posted">
-- TWiki:Main.MichaelDaum on 22 Aug 2005
</div></div>

<div class="text"><div class="comment">
This is a second comment.
</div><div class="posted">
-- TWiki:Main.MichaelDaum on 22 Aug 2005
</div></div>
%STOPINCLUDE%




---++ Plugin Installation Instructions

	* [[http://twiki.org/p/pub/Plugins/%TOPIC%/%TOPIC%.zip][Download]] the ZIP file
	* Unzip it in your twiki installation directory. Content: 
	  | *File:* | *Description:* |
	  | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
	  | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
	* (Dakar) Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.

---++ Plugin Info
<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Substitute and extract information from content by using regular expressions
-->

|  Plugin Author: | TWiki:Main.MichaelDaum |
|  Copyright &copy;: | 2005-2007, MichaelDaum http://wikiring.com |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | v1.21 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  02 May 2007: | using registerTagHandler() as far as possible; \
                  enhanced parameters to EXCTRACT and SUBST |
|  05 Feb 2007: | fixed escapes in format strings; \
                  added better default value for max number of hits to prevent deep recursions \
                  on bad regexpressions |
|  22 Jan 2007: | fixed SUBST, added skip parameter to FORMATLIST |
|  18 Dec 2006: | using registerTagHandler for FORMATLIST |
|  13 Oct 2006: | fixed =limit= parameter in FORMATLIST |
|  31 Aug 2006: | added NO_PREFS_IN_TOPIC |
|  15 Aug 2006: | added =use strict;= and fixed revealed errors |
|  14 Feb 2006: | moved in FORMATLIST from the TWiki:Plugins/NatSkinPlugin;\
                  added escape variables to format strings |
|  06 Dec 2005: | fixed SUBST not to cut off the rest of the text |
|  09 Nov 2005: | fixed deep recursion using =expand="on"= |
|  22 Aug 2005: | Initial version; added =expand= toggle |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.024 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |
|  Appraisal: | TWiki:Plugins/%TOPIC%Appraisal |

-- TWiki:Main.MichaelDaum - 02 May 2007
This topic: TWiki > FilterPlugin
History: r0 - 11 Mar 2007 - 07:52:01 - TWikiContributor
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.FilterPlugin