View source

Some parameter arguments take regular expressions as values.  For example, the '''filter''' and '''exclude''' arguments for the '''filelist''' and '''imagelist''' parameter types.  This is enormously powerful, but it requires you to know at least a little regular expression syntax to be able to use it effectively.

Described here are some examples of simple regular expressions that you might want to use in the context of template parameters.  A complete reference to regular expression syntax is beyond the scope of this book, but can be found online at http://www.php.net/manual/en/book.pcre.php

=== Simple filter string ===
Suppose you want to use the '''filelist''' parameter type to list the files in a given directory.  There are many files in the directory but you only want those with a '.php' extension to be listed.  Then you would use this argument in the <tt><param></tt> element
<source lang="xml">
filter = “\.php”
</source>

The first thing to note is the leading backslash character.  This is needed because the “.” character has a special meaning in regular expressions and that is not what is intended here.  The backslash character tells the regular expression parser to treat the next character (which is the “.”) as just an ordinary character and not to give it the special meaning that it normally does.

The effect of this filter string is to only include those files that have the characters “.”, “p”, “h” and “p”, in that order, anywhere in the file name.

=== Anchoring to the end of the string ===
In the above example, if there is a file called ''configuration.php-dist'' then it would be included in the list because “.php” occurs in the middle of the string.  Perhaps you don't want that, in which case you can use this instead
<source lang="xml">
filter = “\.php$”
</source>

The “$” tells the regular expression parser that the string “.php” must occur at the end of the file name.  So ''configuration.php'' will be included, but ''configuration.php-dist'' will not.

=== Anchoring to the start of the string ===
Suppose you want to list those files which start with the string “joomla” then you would use
<source lang="xml">
filter = “^joomla”
</source>

The “^” tells the regular expression parser that the string following must occur at the start of the file name.

=== Anchoring to both ends of the string ===
Suppose you want to list all those files whose names begin with “joomla” and end with “.php”, but you don't care about what is in between.  Then you can use
<source lang="xml">
filter = “^joomla(.*)\.php$”
</source>

Here you will recognise the “^” character as anchoring the start of the string, and the “$” as anchoring the end of the string.  The “(.*)” indicates that any number of characters, including no characters at all, are acceptable in that position.  Breaking this down a little, the “.” will match any single character; the “*” indicates that the preceding character (in this case the “.”) can occur any number of times, including zero; and the brackets serve to separate the substring from the rest of the string.

=== Case sensitivity ===
It is important to note that regular expression strings are case sensitive.  Suppose you have some file names that begin with “Joomla” instead of “joomla”.  These would not be included if you used the string in the previous example.  To allow for the first character of the file name to be either upper or lower case you can use
<source lang="xml">
filter = “^[Jj]oomla”
</source>

Here the “[Jj]” indicates that either “J” or “j” should be matched.  The brackets (“[]”) indicate a “character class” and should contain list of characters that are to be matched.  If you want to include all filenames beginning with the letters “s”, “t”, “u” or “v” then you could use
<source lang="xml">
filter = “^[stuv]”
</source>

Actually you can shorten this a little by using a range specification
<source lang="xml">
filter = “^[s-v]”
</source>

If you want to make this case insensitive then use
<source lang="xml">
filter = “^[s-vS-V]”
</source>

=== Filtering a list of extensions ===
Suppose you want to filter your list of files so that only those files with specific extensions are included.  For a single extension you can just use
<source lang="xml">
filter = “\.php$”
</source>

But what if you want to filter several different extensions?  For example, to only include file names ending in “.php”, “.html” or “.txt” you can use
<source lang="xml">
filter = “\.php$|\.html$|\.txt$”
</source>

The “|” character indicates an alternative, so “this|that” will match with “this” or “that”.

You might notice that the '''imagelist''' parameter type is exactly the same as the '''filelist''' parameter type with this filter string
<source lang="xml">
filter = “\.png$|\.gif$|\.jpg$|\.bmp$|\.ico$”
</source>
[[Category:Templates]]