Search & replace with regular expressions

Find and replace patterns with stuff.

pax_grep is a find-and-replace plugin for the Textpattern CMS

Summary
Replace all occurrences of a regular expression with replacements.
Version
0.2.2 (updated 5 Dec 2016)

Table of contents

  1. Overview
  2. Installing and uninstalling
  3. Usage and syntax
  4. Attributes
    1. from
    2. to
    3. delimiter
  5. Examples
  6. License
  7. Author contact
  8. Changelog

Overview

This plugin allows you to find occurrences of a regular expression pattern and replace them with something else. It’s almost identical to it’s awesome parent plugin rah_replace by Jukka Svahn, but pax_grep uses PHP’s preg_replace() function, packaged in a compact and easy-to-use Textpattern tag.

Installing and uninstalling

In Textpattern, navigate to the “Plugins” tab under “Admin”, and paste the code into the “Install plugin” pane. Install and enable the plugin.

To uninstall, simply delete the plugin from the “Plugins” tab.

Usage and syntax

pax_grep takes a regular expression and searches content for matching patterns. Then it replaces matches with the string(s) you supply. This works just like rah_replace, except it supports regular expression searches. If you don’t need to search and replace based on a regular expression, you should use rah_replace instead.

pax_grep s a container tag with three attributes.

<txp:pax_grep ↩
    from="/search pattern/" ↩
    to="replacement text" ↩
    delimiter="|">
    Content
</txp:pax_grep>

Attributes

fromRequired

Give this attribute the value of a pattern or patterns you wish to search for. A pattern should be delimited with single quotes or some other character not used in the pattern. Separate multiple patterns by commas (use the delimiter attribute to specify and alternate separator).

Default
from=""
Example
from="'^foo','bar$'"

toRequired

This attribute holds the replacement value(s) for each pattern in the from attribute. No delimiters are needed, but multiple values must be separated by commas (use the delimiter attribute to specify and alternate separator). Each from value will be replaced with the corresponding to value.

Default
to=""
Example
to="fox,bat"

delimiterOptional

So you don’t like using commas to separate your search patterns or replacement values? Sometimes, you need to use a comma in the search pattern, and you need a different separator to break search patterns and replacement values. Use this attribute to specify an alternate separator.

Default
delimiter=","
Example
delimiter=" | "

Examples

Example 1: Get words out of Textpattern’s request_uri.

This example outputs the current request URI, and uses a regular expression to drop the leading slash and transform many delimiter characters into spaces. You might use code like this on a 404 error page to populate a search field with information from a mistyped URL.

<txp:pax_grep
    from="'^\/','\/','%20','\-','\+','\?=','\_'" ↩
    to=", , , , , , ">
    <txp:page_url type="request_uri"/>
</txp:pax_grep>

Example 2: Strip Textile-generated p elements from Textpattern’s excerpt output

Sometimes you might want to show the excerpt of a Textpattern article without mucking around with a bunch of paragraph tags. Here’s how.

<txp:pax_grep from="/<\/?p>/,/\t/" to="">
    <txp:excerpt/>
</txp:pax_grep>

Licence

This plugin is licenced under GPL, Version 2.

Author contact

John Stephens is known as “johnstephens” on the Textpattern support forum and on Twitter. You can reach me at Design Opus or find @johnstephens on Twitter here.

Changelog

Version 0.2.2
2016-12-05: Support the tag registry in Textpattern 4.6.0+.
Version 0.2.1
2012-04-26: Expand and revise plugin help.
Version 0.2
2010-10-01: Add an optional delimiter attribute, so you can use commas in your search pattern. Thanks, Jan.
Version 0.1.1
2009-01-25: Change plugin name from opus_grep to pax_grep in compliance with de facto standard of three-letter prefix for plugins.
Version 0.1
2009-01-23: Branch from rah_replace by Jukka Svahn— use preg_replace() instead of str_replace() to allow regex search patterns.