This example expression checks to see if a request meets certain criteria,
for example if it is an internal request. If it does not meet the criteria,
the server redirects the request to a request denied URL.

The expression contains the following components:

Literals – "^/private/(.*)$" and "^https?://example.com/"

Variables – $internal, $uri,
and $referer

Operators – not, and, =~, and !~

Expression Results as Booleans

In some circumstances, for example, after evaluating an If or ElseIf expression, the server must treat the result of an expression
as a Boolean. The server uses the following rules when converting a numeric
value to a Boolean:

Numeric 0 (zero) evaluates to false

All other numeric values evaluate to true

The server uses the following rules when converting a string to a Boolean:

Zero-length strings evaluate to false

The string 0 (zero) evaluates to false

All other strings evaluate to true

Expression Literals

Expression literals are divided into string and numeric literals.

String Literals

A string literal is bracketed by either single quotes (')
or double quotes ("). When single quotes bracket a
string literal, the value of the literal is the value within the quotes. When
double quotes are used, any references to variables or expressions within
the quotes are interpolated. For more information, see String Interpolation.

The following expression examples show the use of single and double
quotes.

To include an uninterpolated $ character in a double
quote string, use the $$ or \$ escape
sequences.

When a double quote character appears within a literal bracketed by
double quotes, it must be prefixed with a backslash. When a single backslash
(\) character appears within a literal bracketed by double
quotes, it must be prefixed with a backslash. When a single quote character
appears within a literal bracketed by single quotes, it must be prefixed with
a backslash.

The following examples show valid and invalid literals:

# The following are examples of valid literals
'this string literal is bracketed by single quotes'
"this string literal is bracketed by double quotes"
"the backslash, \\, escapes characters in double quote string literals"
'it\'s easy to use strings literals'
# The following are examples of invalid literals
'it's important to escape quote characters'
"any \ characters in double quote string literals must be escaped"

Numeric Literals

A numeric literal can consist of decimal digits and an optional decimal
point, a leading zero followed by octal digits, or a leading 0x prefix
followed by hexadecimal digits. Hexadecimal and octal numbers are automatically
converted to decimal form.

Expression Variables

Any $variable can be used as a variable in an expression.
To mirror the Client tag syntax, the $ prefix
is optional for predefined variable names in expressions. For example, the
following three portions of obj.conf are all semantically
equivalent:

Any variable names you define must use the $ prefix.
For example, the following expression is invalid even if somecustomvariable is defined in a server.xmlvariable element:

<If somecustomvariable = "foo">
...
</If>

To make this expression valid, add the dollar sign prefix:

<If $somecustomvariable = "foo">
...
</If>

Expression Operators

The following table lists the operators that are used in expressions.

Table A–2 List of Expression Operators

Operator Symbol

Operator Name

!

C-style logical not

=

Wildcard pattern match

=~

Regular expression match

!~

Regular expression mismatch

+

Addition or unary plus

-

Subtraction or unary minus

.

String concatenation

defined

Value is defined

-d

Directory exists

-e

File or directory exists

-f

File exists

-l

Symbolic link exists

-r

File is readable

-s

File size

-U

URI maps to accessible file or directory

<

Numeric less than

<=

Numeric less than or equal to

>

Numeric greater than

>=

Numeric greater than or equal to

lt

String less than

le

String less than or equal to

gt

String greater than

ge

String greater than or equal to

==

Numeric equal

!=

Numeric not equal

eq

String equal

ne

String not equal

^

C-style exclusive or

&&

C-style logical and

||

C-style logical or

not

Logical not

and

Logical and

or

Logical or

xor

Logical exclusive or

The following table lists the precedence of operators within expressions
from highest to lowest precedence.

Table A–3 Operator Precedence

Symbol

Operands

Associativity

Description

( ), [ ]

0

Left to right

Parentheses

!, unary +, unary -

1

Right to left

Sign operators

=, =~, !~

2

Non-associative

Pattern matching operators

+, -, .

2

Non-associative

Additive operators

defined, -d, -f, -l, -r, -s, -U

1

Right to left

Named operators

<, lt, <=, le, >, gt, >=,ge

2

Non-associative

Relational operators

==, eq, !=, ne

2

Non-associative

Equality operators

^

2

Left to right

C-style exclusive or operator

&&

2

Left to right

C-style logical and operator

||

2

Left to right

C-style logical or operator

not

1

Right to left

Logical not operator

and

2

Left to right

Logical and operator

or, xor

2

Left to right

Logical or operators

The numeric operators (<, <=, >, >=, ==, and !=)
are intended to operate on numbers and not strings. To facilitate comparing
numbers, dates, and timestamps, the numeric operators ignore any white space,
colons, slashes, and commas in their arguments. Dashes after the first digit
are also ignored.

Note –

It is generally incorrect to use the numeric operators on non-numeric
values.

For example, the following expression evaluates to true:

# The following expression evaluates to true because both
# "foo" and "bar" are numerically equivalent to 0
("foo" == "bar")

Expression Functions

Expression functions manipulate data for use in expressions. Expression
functions are different from SAFs. While SAFs perform the actual work associated
with an HTTP request, expression functions are used to select which SAFs run
and what parameters to pass to the SAFs.

Some expression functions require one or more arguments. An expression
function's argument list is bracketed by parentheses (())
and the individual arguments are separated by commas (,).

The individual expression functions are listed in the following sections:

Syntax

Arguments

See Also

external

The external function passes a value to an external
rewriting program and returns the result.

Each invocation of external results in a single newline-terminated
line being written to the external rewriting program's stdin.
For each line of input, the program must produce a single line of output.
When developing an external rewriting program, it is important to avoid buffering stdout. In Perl, for example, $| = 1; should
be used to disable buffering. Because the server expects the external rewriting
program to produce one line of output for each line of input, the server can
hang if the external rewriting program buffers its output.

Syntax

external(program, value)

Arguments

The expression function has the following arguments.

Table A–8 external Arguments

Argument

Description

program

The program argument is the file name of
an external rewriting program. Because program is
executed using the operating system's default shell (/bin/sh on Unix/Linux) or the command interpreter (CMD.EXE on Windows), program should be an absolute path or the name of a program
in the operating system's PATH. The server starts the external
rewriting program on demand. A given server process never executes more than
one instance of the program at a time.

Note –

The server may start multiple instances of a given external rewriting
program when the server is running in multiprocess mode.

value

The value passed to the rewrite program.

Example

The following is an example of an external rewriting program rewrite.pl, used to change the prefix /home/ to /u/:

#!/usr/bin/perl
$| = 1;
while (<STDIN>) {
s|^/home/|/u/|;
print $_;
}

In this example, the external expression function
used to invoke rewrite.pl is as follows:

NameTrans fn="rewrite" path="$(external('rewrite.pl', $path))"

httpdate

The httpdate function returns an RFC 1123 date/time
stamp for use in HTTP header fields such as Expires.

Syntax

httpdate(time)

Arguments

The following table describes the argument for the expression function.

Table A–9 httpdate Argument

Argument

Description

time

The time value

Example

The following obj.conf code could be used to set
an Expires header that indicates a response is not cached
for more than one day:

See Also

length

The length function returns the length of its argument,
that is, a number representing the length of the string.

Syntax

length(string)

Arguments

The following table describes the argument for the expression function.

Table A–11 length Argument

Argument

Description

string

The string for which the expression function computes the length.

Example

The following obj.conf code can be used to send a 404 Not found error to clients that request URIs longer than 255
bytes:

<If length($uri) > 255)>
PathCheck fn="deny-existence"
</If>

lookup

The lookup function inspects a text file for a name-value
pair with name name and returns the corresponding
value. The name-value pairs in the file are separated by white space.

If the file does not contain a name-value pair with the specified name,
this function returns the value of defaultvalue, if
specified, or returns an empty string.

Syntax

lookup(filename, name, defaultvalue)

Arguments

The expression function has the following arguments:

Table A–12 lookup Arguments

Argument

Description

filename

filename is the name of a text file that
contains one name-value pair per line. filename can
be an absolute path or a path relative to the server's config directory.
Names and values are separated by white space. Lines beginning with # are
ignored.

name

The name of the name-value pair for which the function looks in the
text file.

defaultvalue

The value returned by the function if filename exists
but does not contain a name-value pair with a name matching the value of name. If defaultvalue is not specified,
it defaults to an empty string.

Example

The following example shows a text file called urimap.conf that
could be used with the lookup function to map shortcut
URIs to URIs:

Syntax

Arguments

See Also

uuid

The uuid function returns a UUID as a string. No
two calls to uuid return the same UUID. Because they are
guaranteed to be unique, UUIDs are useful for constructing client-specific
cookie values.

Syntax

uuid()

Regular Expressions

The If and ElseIf expressions
may evaluate regular expressions using the =~ and !~ regular
expression matching operators. These regular expressions use the Perl-compatible
syntax implemented by Perl-compatible Regular Expressions (PCRE).

By default, regular expressions are case sensitive. The (?i) option
flag can be added to the beginning of a regular expression to request case
insensitivity. For example:

When an If or ElseIf expression contains a regular expression, regular expression backreferences
can appear within arguments in the container body. Regular expression backreferences
are of the form $n where n is an integer between 1 and 9 corresponding to the capturing
subpattern of the regular expression.

In the above example, two subpatterns are used in the If expression,
so $1 and $2 can be used as backreferences.
In the example, the value of the first capturing subpattern is used within
a NameTrans fn="rewrite" parameter. The value of the second
capturing subpattern is ignored.

An If or ElseIf expression can
contain backreferences to earlier regular expressions in that same If or ElseIf expression.