view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

:   The error message to be returned when a ssi directive fails. By
    default, it is `[an error occurred while processing this directive]`

*html*

:   The html data to be parsed. You do not have to provide that value
    now. You can provide it to [\"parse\"](#parse){.perl-module} as its
    first argument when you call it.

*legacy*

:   Takes a boolean value suchas `1` or `0` to indicate whether the
    Apache2 expression supported accepts legacy style.

    Legacy Apache expression typically allows for perl style variable
    `${REQUEST_URI}` versus the modern style of `%{REQUEST_URI}` and
    just an equal sign to imply a regular expression such as:

            $HTTP_COOKIES = /lang\%22\%3A\%22([a-zA-Z]+\-[a-zA-Z]+)\%22\%7D;?/

    Modern expression equivalent would be:

            %{HTTP_COOKIES} =~ /lang\%22\%3A\%22([a-zA-Z]+\-[a-zA-Z]+)\%22\%7D;?/

    See
    [Regexp::Common::Apache2](https://metacpan.org/pod/Regexp::Common::Apache2){.perl-module}
    for more information.

    See also the property *trunk* to enable experimental expressions.

*remote\_ip*

:   This is used when you want to artificially set the remote ip
    address, i.e. the address of the visitor accessing the page. This is
    used essentially by the SSI directive:

            my $ssi = Apache2::SSI->new( remote_ip => '192.168.2.10' ) ||
                die( Apache2::SSI->error );

            <!--#if expr="-R '192.168.2.0/24' || -R '127.0.0.1/24'" -->
            Remote ip is part of my private network
            <!--#else -->
            Go away!
            <!--#endif -->

*sizefmt*

:   The default way to format a file size. By default, this is `abbrev`,
    which means a human readable format such as `2.5M` for 2.5
    megabytes. Other possible value is `bytes` which would have the
    `fsize` ssi directive return the size in bytes.

    See [Apache2
    documentation](https://httpd.apache.org/docs/current/en/howto/ssi.html){.perl-module}
    for more information on this.

*timefmt*

:   The default way to format a date time. By default, this uses the
    display according to your locale, such as `ja_JP` (for Japan) or
    `en_GB` for the United Kingdoms. The time zone can be specified in
    the format, or it will be set to the local time zone, whatever it
    is.

    See [Apache2
    documentation](https://httpd.apache.org/docs/current/en/howto/ssi.html){.perl-module}
    for more information on this.

*trunk*

:   This takes a boolean value such as `0` or `1` and when enabled this
    allows the support for Apache2 experimental expressions.

    See
    [Regexp::Common::Apache2](https://metacpan.org/pod/Regexp::Common::Apache2){.perl-module}
    for more information.

    Also, see the property *legacy* to enable legacy Apache2
    expressions.

handler
-------

This is a key method expected by mod\_perl. Depending on how this module
is used, it will redirect either to
[\"apache\_filter\_handler\"](#apache_filter_handler){.perl-module} or
to
[\"apache\_response\_handler\"](#apache_response_handler){.perl-module}

ap2perl\_expr
-------------

This method is used to convert Apache2 expressions into perl equivalents
to be then eval\'ed.

It takes an hash reference provided by [\"parse\" in
Apache2::Expression](https://metacpan.org/pod/Apache2::Expression#parse){.perl-module},
an array reference to store the output recursively and an optional hash
reference of parameters.

It parse recursively the structure provided in the hash reference to
provide the perl equivalent for each Apache2 expression component.

It returns the array reference provided used as the content buffer. This
array is used by [\"parse\_expr\"](#parse_expr){.perl-module} and then
joined using a single space to form a string of perl expression to be
eval\'ed.

apache\_filter
--------------

Set or get the
[Apache2::Filter](https://metacpan.org/pod/Apache2::Filter){.perl-module}
object.

When running under Apache mod\_perl this is set automatically from the
special [\"handler\"](#handler){.perl-module} method.

apache\_filter\_handler
-----------------------

README.md  view on Meta::CPAN

Provided with html data and if none is provided will use the data
specified with the method [\"html\"](#html){.perl-module}, this method
will parse the html and process the ssi directives.

It returns the html string with the ssi result.

parse\_config
-------------

Provided with an hash reference of parameters and this sets three of the
object parameters that can also be set during object instantiation:

*echomsg*

:   The value is a message that is sent back to the client if the echo
    element attempts to echo an undefined variable.

    This overrides any default value set for the parameter *echomsg*
    upon object instantiation.

*errmsg*

:   This is the default error message to be used as the result for a
    faulty ssi directive.

    See the [\"echomsg\"](#echomsg){.perl-module} method.

*sizefmt*

:   This is the format to be used to format the files size. Value can be
    either `bytes` or `abbrev`

    See also the [\"sizefmt\"](#sizefmt){.perl-module} method.

*timefmt*

:   This is the format to be used to format the dates and times. The
    value is a date formatting based on [\"strftime\" in
    POSIX](https://metacpan.org/pod/POSIX#strftime){.perl-module}

    See also the [\"timefmt\"](#timefmt){.perl-module} method.

parse\_echo
-----------

Provided with an hash reference of parameter and this process the `echo`
ssi directive and returns its output as a string.

For example:

        Query string passed: <!--#echo var="QUERY_STRING" -->

There are a number of standard environment variable accessible under SSI
on top of other environment variables set. See [\"SSI
Directives\"](#ssi-directives){.perl-module} section below.

parse\_echo\_date\_gmt
----------------------

Returns the current date with time zone set to gmt and based on the
provided format or the format available for the current locale such as
`ja_JP` or `en_GB`.

parse\_echo\_date\_local
------------------------

Returns the current date with time zone set to the local time zone
whatever that may be and on the provided format or the format available
for the current locale such as `ja_JP` or `en_GB`.

Example:

        <!--#echo var="DATE_LOCAL" -->

parse\_echo\_document\_name
---------------------------

Returns the document name. Under Apache, this returns the environment
variable `DOCUMENT_NAME`, if set, or the base name of the value returned
by [\"filename\" in
Apache2::RequestRec](https://metacpan.org/pod/Apache2::RequestRec#filename){.perl-module}

Outside of Apache, this returns the environment variable
`DOCUMENT_NAME`, if set, or the base name of the value for
[\"document\_uri\"](#document_uri){.perl-module}

Example:

        <!--#echo var="DOCUMENT_NAME" -->

If the uri were `/some/where/file.html`, this would return only
`file.html`

parse\_echo\_document\_uri
--------------------------

Returns the value of [\"document\_uri\"](#document_uri){.perl-module}

Example:

        <!--#echo var="DOCUMENT_URI" -->

The document uri would include, if any, any path info and query string.

parse\_echo\_last\_modified
---------------------------

This returns document last modified date. Under Apache, there is a
standard environment variable called `LAST_MODIFIED` (see the section on
[\"SSI Directives\"](#ssi-directives){.perl-module}), and if somehow
absent, it will return instead the formatted last modification datetime
for the file returned with [\"filename\" in
Apache2::RequestRec](https://metacpan.org/pod/Apache2::RequestRec#filename){.perl-module}.
The formatting of that date follows whatever format provided with
[\"timefmt\"](#timefmt){.perl-module} or by default the datetime format
for the current locale (e.g. `ja_JP`).

Outside of Apache, the similar result is achieved by returning the value
of the environment variable `LAST_MODIFIED` if available, or the
formatted datetime of the document uri as set with
[\"document\_uri\"](#document_uri){.perl-module}

Example:

        <!--#echo var="LAST_MODIFIED" -->

parse\_eval\_expr
-----------------

Provided with a string representing an Apache2 expression and this will
parse it, transform it into a perl equivalent and return its value.

It does the parsing using [\"parse\" in
Apache2::Expression](https://metacpan.org/pod/Apache2::Expression#parse){.perl-module}
called from [\"parse\_expr\"](#parse_expr){.perl-module}

If the expression contains regular expression with capture groups, the
value of capture groups will be stored and will be usable in later
expressions, such as:

        <!--#config errmsg="[Include error]" -->
        <!--#if expr="%{HTTP_COOKIE} =~ /lang\%22\%3A\%22([a-zA-Z]+\-[a-zA-Z]+)\%22\%7D;?/"-->
            <!--#set var="CONTENT_LANGUAGE" value="%{tolower:$1}"-->
        <!--#elif expr="-z %{CONTENT_LANGUAGE}"-->
            <!--#set var="CONTENT_LANGUAGE" value="en"-->
        <!--#endif-->
        <!DOCTYPE html>
        <html lang="<!--#echo encoding="none" var="CONTENT_LANGUAGE" -->">

parse\_exec
-----------

Provided with an hash reference of parameters and this process the
`exec` ssi directives.

Example:

        <!--#exec cgi="/uri/path/to/progr.cgi" -->

or

        <!--#exec cmd="/some/system/file/path.sh" -->

parse\_expr
-----------

It takes a string representing an Apache2 expression and calls
[\"parse\" in
Apache2::Expression](https://metacpan.org/pod/Apache2::Expression#parse){.perl-module}
to break it down, and then calls
[\"ap2perl\_expr\"](#ap2perl_expr){.perl-module} to transform it into a
perl expression that is then eval\'ed by
[\"parse\_eval\_expr\"](#parse_eval_expr){.perl-module}.

It returns the perl representation of the Apache2 expression.