Expressions

Author:Dirk Tilger Contact:dirk at MIRIUP.DE Author:Umberto Nicoletti Contact:umberto.nicoletti at gmail.com Revision:$Revision: 8295 $ Date:$Date: 2008-12-26 21:08:04 -0800 (Fri, 26 Dec 2008) $ Last Updated:2007/07/09

Contents

• Expressions
  • Introduction
  • Expression Types
  • “MapServer expressions”

Introduction

As of version 4.6.1, expressions are used in two places. They’re used to filter layers for specific records in the dataset and they’re used in CLASS EXPRESSIONs to specify to which items this CLASS does apply to.

Expression Types

Expression are used to match attribute values with certain logical checks. There are three different types of expressions you can use with MapServer:

• String comparisons: A single attribute is compared with a string value.
• Regular expressions: A single attribute is matched with a regular expression.
• Logical “MapServer expressions”: One or more attributes are compared using logical expressions.

String comparison

String comparison means as the name suggests that attribute values are checked if they are equal to some value. String comparison are the simplest form of MapServer expressions and the fastest option.

To use a string comparison for filtering a LAYER, both FILTERITEM and FILTER must be set. FILTERITEM is set to the attribute name. FILTER is set to the value for comparison. The same rule applies to CLASSITEM and EXPRESSION in the CLASS object.

Example for a simple string comparison filter

FILTER "2005"
FILTERITEM "year"

would match all records that have the attribute “year” set to “2005”. The rendered map would appear as if the dataset would only contain those items that have the “year” set to “2005”.

Similarly, a classification for the items matched above would be done by setting the CLASSITEM in the layer and the EXPRESSION in the class

LAYER
    NAME "example"
    CLASSITEM "year"
    ...
    CLASS
        NAME "year-2005"
        EXPRESSION "2005"
        ...
    END
END

For a reason explained later on the values for both CLASSITEM and FILTERITEM should start neither with an ‘/’ nor with a ‘(‘ character.

Regular expression comparison

Regular expressions are a standard text pattern matching mechanism from the UNIX world. The functionality of regular expression matching is provided by the operating system on UNIX systems and therefore slightly operating system dependent. However their minimum set of features are those defined by the POSIX standard. The documentation of the particular regular expression library is usually in the “regex” manual page (“man regex”).

Regular expression with MapServer work similarly to string comparison, but allow more complex operation. They are slower than pure string comparisons, but might be still faster than logical expression. As with the string comparison use regular expressions, a FILTERITEM or a CLASSITEM has to defined, respectively.

A regular expression typically consists of characters with special meanings and characters that are interpreted as they are. Alphanumeric characters (A-Z, a-z and 0-9) are taken as they are. Characters with special means are:

• . will match a single character
• [ and ] are used for grouping. For example [A-Z] would match the characters A,B,C,...,X,Y,Z.
• {, }, and * are used to specify how often something should match.
• ^ matches the beginning, $ matches the end of the value.
• The backslash \ is used to take away the special meaning. For example $ would match the dollar sign.

The following LAYER configuration would have all records rendered on the map that have “hotel” in the attribute named “placename”

LAYER
    NAME "regexp-example"
    FILTERITEM "placename"
    FILTER /hotel/
    ...
END

Note

The regular expression is case-sensitive, thus records having “Hotel” in them would not have matched.

Example: Match records that have a value for the current century (as of 2005 ;) in the attribute “year”

FILTERITEM "year"
FILTER /^20[0-9][0-9]/

Example: Match all the records that are either purely numerical or empty

FILTER /^[0-9]*$/

Note

If you experience frequently segmentation faults when working with MapServer and regular expressions, it might be that your current working environment is linked against more than one regular expression library. This can happen when MapServer is linked with components that bring their own copy, like the Apache httpd or PHP. In these cases the author has made best experiences with making all those components using the regular expression library of the operating system (i.e. the one in libc). That involved editing the build files of some of the components, however.

“MapServer expressions”

MapServer expressions are the most complex and depending how they are written can become quite slow. They can match any of the attributes and thus allow filtering and classification depending on more than one attribute. Besides pure logical operations there are also expressions allow also certain arithmetic, string- and time operations.

To be able to use a MapServer expression for a FILTER or EXPRESSION value, the expression has to be finally of a logical value.

Logical expressions

Syntactically, a logical expression is everything encapsulated in round brackets. Logical expressions take logical values as their input and return logical values. A logical expression is either ‘true’ or ‘false’.

• ( ( ... ) AND ( ... ) ) ( ( ... ) && ( ... ) ) ... will become true when both of the two logical expressions in the innermost brackets are true.
• ( ( ... ) OR ( ... ) ) ( ( ... ) || ( ... ) ) ... will become true when at least one of the two logical expressions in the innermost brackets is true.
• NOT ( ... ) ! ( ... ) ... will become true, when the logical expression in the brackets becomes false.

String operations that result in a logical value

Syntactically, a sting is something encapsulated in double-quotes.

• ( “String1” eq “String2” ) ( “String1” == “String2” ) ( “String1” = “String2” ) ... will become true when both strings are equal. This operation is identical to the MapServer string comparison described earlier.
• ( “String1” != “String2” ) ( “String1” ne “String2” ) ... will become true when both strings are not equal.
• ( “String1” < “String2” ) ( “String1” lt “String2” ) ... will become true when “String1” is lexicographically smaller than “String2”
• ( “String1” > “String2” ) ( “String1” gt “String2” ) ... will become true when “String1” is lexicographically larger than “String2”.
• ( “String1” <= “String2” ) ( “String1” le “String2” ) ... will become true when “String1” is not lexicographically larger than “String2”
• ( “String1” >= “String2” ) ( “String1” ge “String2” ) ... will become true when “String1” is not lexicographically smaller than “String2”.
• ( “String1” IN “token1,token2,...,tokenN” ) ... will become true when “String1” is in equal one of the given tokens.

Note

The separator for those tokens is the comma. That means that you must not add unnecessary white space to the list and that you cannot compare to tokens that have a comma in it.

• ( “String1” =~ /regexp/ ) ... will become true, when “String1” matches the regular expression “regexp”. This operation is identical to the regular expression matching described earlier.

String operations that return string values

There is only one operation for strings that returns a string value:

• “String1” + “String2 ... will return “String1String2”, thus the two string concatenated to each other.

Arithmetic expressions returning logical values

The basic element for the arithmetic operation is the number. There are some purely arithmetic operations that are returning numbers as their value. They will be covered in the next section.

• ( n1 eq n2 ) ( n1 == n2 ) ( n1 = n2 ) ... will become true when both numbers are equal.
• ( n1 != n2 ) ( n1 ne n2 ) ... will become true when both numbers are not equal.
• ( n1 < n2 ) ( n1 lt n2 ) ... will become true when n1 is smaller than n2
• ( n1 > n2 ) ( n1 gt n2 ) ... will become true when n1 is larger than n2.
• ( n1 <= n2 ) ( n1 le n2 ) ... will become true when n1 is smaller or equal n2
• ( n1 >= n2 ) ( n1 ge n2 ) ... will become true when n1 is larger or equal n2.
• ( n1 IN “number1,number2,...,numberN” ) ... will become true when n1 is equal to one of the given numbers.

Arithmetic expression returning a number

As stated in the previous section, MapServer can do purely numerical operations with numbers.

• n1 + n2 ... will become the sum of n1 and n2
• n1 - n2 ... will become n2 subtracted from n1
• n1 * n2 ... will become n1 multiplicated with n2
• n1 / n2> ... will become n1 divided by n2
• -n1 ... will become n1 with negated sign
• n1 ^ n2 ... will become n1 by a power of n2
• length ( “String1” ) ... will become the number of characters of “String1”

Note

When the numerical operations above are used like logical operations, the following rule applies: values equal to zero will be taken as ‘false’ and everything else will be ‘true’. That means the expression

::

( 6 + 5 ) ...

would evaluate as true, but

( 5 - 5 )
...

would evaluate as false.

Temporal expressions

MapServer uses an internal time type to do comparison. To convert a keys value into this time type it will check the list below from the top down if the specified time matches and if so, it will do the conversion.

• YYYY-MM-DDTHH:MM:SSZ (‘Z’ and ‘T’ being the characters itself)</i>
• YYYY-MM-DDTHH:MM:SS (‘T’ being the character itself)</i>
• YYYY-MM-DD HH:MM:SS
• YYYY-MM-DDTHH:MM (‘T’ being the character itself)</i>
• YYYY-MM-DD HH:MM
• YYYY-MM-DDTHH (‘T’ being the character itself)</i>
• YYYY-MM-DD HH
• YYYY-MM-DD
• YYYY-MM
• YYYY
• THH:MM:SSZ (‘Z’ and ‘T’ being the characters itself)</i>
• THH:MM:SS

For temporal values obtained this way, the following operations are supported:

• ( n1 eq n2 ) ( n1 == n2 ) ( n1 = n2 ) ... will become true when both times are equal.
• ( t1 != t2 ) ( t1 ne t2 ) ... will become true when both times are not equal.
• ( t1 < t2 ) ( t1 lt t2 ) ... will become true when t1 is earlier than t2
• ( t1 > t2 ) ( t1 gt t2 ) ... will become true when t1 is later than t2.
• ( t1 <= t2 ) ( t1 le t2 ) ... will become true when t1 is earlier or same t2
• ( n1 >= n2 ) ( n1 ge n2 ) ... will become true when t1 is later or same t2.

How the attributes are referenced

To make a meaningful use of the expressions above, we need to get the attribute values into the expressions. That is done by enclosing the attribute key into square brackets, like this: [KEY]. Then before the expression is evaluated every occurrence of “[KEY]” will be replaced by the value for attribute “KEY”.

Example: how a simple string comparison would be evaluated. The filter is set to:

FILTER ( "[BUILDING_NAME]" == "National Museum" )

There is a attribute “BUILDING_NAME” and its value is “National Government Building”. Thus the expression actually evaluated is...

"National Government Building" == "National Museum" )

...and as such should be false.

Some layers do not really come with metadata. For raster layers for example special attributes have been defined that can be used for classification:

• [PIXEL] ... will become the pixel value as number
• [RED], [GREEN], [BLUE] ... will become the color value for the red, green and blue component in the pixel value, respectively.

Quotes escaping in strings

Note

Quotes escaping is not supported in MapServer versions lower than 5.0.

Starting with MapServer 5.0, if your dataset contains double-quotes, you can use a C-like escape sequence in the expression string. For example if your key “NAME” has the value ‘National “hero” statue’ you could write the FILTER expression as follows:

FILTER ( "[NAME]" == "National \"hero\" statue" )
...

to escape a single quote use the following sequence instead:

FILTER ( "[NAME]" == "National \'hero\' statue" )