PmWiki | Cookbook / Grep

Summary: Use regular expressions to control what to include from a page

Version: 2010-06-17

Prerequisites: PmWiki 2.2.x

Status: beta

Maintainer: Eemeli Aro

Users: +1 (View / Edit)

Categories: Includes, Markup

Discussion: Grep-Talk

Download: grep.php Δ

Description

(:grep:) is a wrapper for (:include:) that lets you search and replace using regular expressions within the included text. Internally, it's a wrapper for the PHP functions preg_replace and preg_match_all.

For example, given a page with a list of news items:

[[#news]]
* 14.6.2011: Item one
* 3.12.2010: Item two
* 24.5.2010: Item three
* 17.5.2010: Item four
[[#newsend]]

14.6.2011: Item one
3.12.2010: Item two
24.5.2010: Item three
17.5.2010: Item four

The following directive would allow you to highlight the items with future dates:

(:grep #news pat='(\d\d?)\.(\d\d?)\.(\d{4})' repl="{:if date ..$3-$2-$1:}'''$0'''{:else:}$0{:ifend:}":)

Note: As the recipe isn't enabled
on pmwiki.org, this example is fake.

14.6.2011: Item one
3.12.2010: Item two
24.5.2010: Item three
17.5.2010: Item four

To install

download grep.php Δ to your cookbook directory
add the following line to your configuration file:

include_once("$FarmD/cookbook/grep.php");

Using the (:grep:) directive

At its most basic, (:grep:) requires a subject (the source text), a pattern (what to look for) and a replacement (what to output for each match):

(:grep Group.Page#section pat=pattern repl=replacement:)

subject may also refer to a section on the current page with (:grep #section ...:). This may be useful for formatting data from the page itself that is hidden using (:if false:). If left empty, the subject will default to the current page, in which case match=1 will also be set to prevent recursion (see below).

pat=pattern should be a valid PHP regexp pattern without delimiters or modifiers, while repl=replacement should be the text with which to replace each found match.

As the example above shows, any (:directives:) in the pattern or replacement will work, if curly brackets are substituted for normal ones: {:directive:}. This is required to correct the order of operations when turning markup into HTML.

All other parameters are optional:

(:grep ... mod=abc match=1 limit=123:)

`mod=`	Pattern modifiers; a string of characters from the set `imsuxADSUXJ`. Note that PREG_REPLACE_EVAL ('`e`') is not allowed. If not set, the default is to enable PCRE_MULTILINE (`mod=m`).
`match=1`	If set, only the matching strings are output. If `repl` is not set, these are separated using a newline.
`limit=`	The upper limit for replacements.

(:grep:) also accepts all of the same parameters as (:include:):

(:grep FullName#fromanchor#toanchor ... lines=123 self=0 basepage=abc variable=value:)

Notes

I wrote this recipe today for the exact purpose mentioned in the example: to highlight future event dates in a list of news items. It might have been easier to write some custom code for it, but this way the code is more robust and someone else might find it useful one day.

Release notes

2010-06-17 Δ — bugfix: empty lines resulted in visible <:vspace> in output due to using PVSE() instead of PVS()
2010-06-14 Δ — first public release

Contributors

Eemeli Aro

Comments

See discussion at Grep-Talk

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.

Grep