pax_grep

; Summary
: Replace all occurrences of a regular expression with replacements.
; Version
: 0.2.3 (updated 14 June 2018)

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()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

from — Required

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$'"

to — Required

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"

delimiter — Optional

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 Cycle Design Co. or find @johnstephens on Twitter here.

Changelog

; Version 0.2.3
: 2018-06-14: Clean up code style and fix plugin help navigation.
; 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.