FORMATLIST documentation and examples

Notes on the FilterPlugin FORMATLIST macro construction and use

FORMATLIST is Foswiki's Swiss army knife for manipulating text. It has many parameters and using it can be sometimes perplexing. I hope you find my notes useful.

Table of contents

Syntax

%FORMATLIST{ "<list>" ... }%

list can be any string or an INCLUDed topic . Double quotes must be escaped.

See the FORMATLIST documentation for details.

FORMATLIST has many parameters and using them can be perplexing. They come in three classes.

used on with single line or split in items	used with items only	used with patterns within items only
tokenize	separator	pattern
split	lastseparator	format
replace	limit	map
header	skip
footer	sort
null	reverse
hideempty	unique
	exclude
	include
	selection
	marker

The internal processing sequence

The behaviour of FORMATLIST is better understood when you know the internal processing sequence. Here is a summary.

Examples

the list

The following list is used as input for all examples below.

• Set theList = d~e~fisherman~~j~fishingrod~c~~a~fish~i~~g~fishbowl~l

replace

Replace fish with shark

d~e~sharkerman~~j~sharkingrod~c~~a~shark~i~~g~sharkbowl~l

---

%STARTSECTION{ "replace" }%
%FORMATLIST{ 
    "%theList%"
    replace="fish=shark"
}%
%ENDSECTION{ "replace" }%

tokenize, replace

Replace fish with shark, but protect fisherman and fishingrod by tokenizing them.

d~e~fisherman~~j~fishingrod~c~~a~shark~i~~g~sharkbowl~l

---

%STARTSECTION{ "tokenize" }%
%FORMATLIST{ 
    "%theList%"
    tokenize="fish(i|e)[^~]*"
    replace="fish=shark"
}%
%ENDSECTION{ "tokenize" }%

sort

Sort sorts the list items in alphabetical order

a~fish~i, d~e~fisherman, g~fishbowl~l, j~fishingrod~c

---

%STARTSECTION{ "sort" }%
%FORMATLIST{ 
    "%theList%"
    split="~~"
    sort="on"
}%
%ENDSECTION{ "sort" }%

replace sort

Sort sorts the list items in alphabetical order, taking into account the replacements. Note that the replacements occur anywhere in the list items. For instance, the a in fisherman is replaced by a z to read fishermzn.

w~fishinxroy~c, x~fishbowl~l, y~e~fishermzn, z~fish~i

---

%STARTSECTION{ "replacesort" }%
%FORMATLIST{ 
    "%theList%"
    split="~~"
    replace="a=z,d=y,g=x,j=w"
    sort="on"
}%
%ENDSECTION{ "replacesort" }%

pattern

Pattern can be used to reformat the list into a table.

fisherman	e	d
c	fishingrod	j
i	fish	a
l	fishbowl	g

---

%STARTSECTION{ "pattern" }%
%FORMATLIST{ 
    "%theList%"
    split="~~"
    pattern="([^~]+)~([^~]+)~([^~]+)"
    format="|$3|$2|$1|"
    separator="$n"
}%
%ENDSECTION{ "pattern" }%

pattern sort

Notice that the sort order is that of the original list, not the formatted list.

i	fish	a
fisherman	e	d
l	fishbowl	g
c	fishingrod	j

---

%STARTSECTION{ "patternsort" }%
%FORMATLIST{ 
    "%theList%"
    split="~~"
    pattern="([^~]+)~([^~]+)~([^~]+)"
    format="|$3|$2|$1|"
    separator="$n"
    sort="on"
}%
%ENDSECTION{ "patternsort" }%

selection marker

Items in the list can be marked providing an appropriate format. There is no need for a pattern parameter. The default (.*) will do.

d~e~fisherman	marking a male
j~fishingrod~c
a~fish~i
g~fishbowl~l

---

%STARTSECTION{ "selectionmarker" }%
%FORMATLIST{ 
    "%theList%"
    split="~~"
    format="|$1|$marker|"
    separator="$n"
    selection="man"
    marker="marking a male"
}%
%ENDSECTION{ "selectionmarker" }%

map

The map parameter is a convenient shortcut, avoiding the more cumbersome $percentIF{ \"$1='a'\" then=\"alpha\" else=\"$1\" }$percent.

fisherman	epsilon	d
c	fishingrod	j
iota	fish	a
l	fishbowl	g

---

%STARTSECTION{ "map" }%
%FORMATLIST{ 
    "%theList%"
    split="~~"
    pattern="([^~]+)~([^~]+)~([^~]+)"
    format="|$map($3)|$map($2)|$1|"
    separator="$n"
    map="a=*alpha*,e=*epsilon*,i=*iota*"
}%
%ENDSECTION{ "map" }%