.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Regexp::Log 3pm"
.TH Regexp::Log 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Regexp::Log \- A base class for log files regexp builders
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    my $foo = Regexp::Log::Foo\->new(
\&        format  => \*(Aqcustom %a %b %c/%d\*(Aq,
\&        capture => [qw( host code )],
\&    );
\&
\&    # the format() and capture() methods can be used to set or get
\&    $foo\->format(\*(Aqcustom %g %e %a %w/%s %c\*(Aq);
\&    $foo\->capture(qw( host code ));
\&
\&    # this is necessary to know in which order
\&    # we will receive the captured fields from the regexp
\&    my @fields = $foo\->capture;
\&
\&    # the all\-powerful capturing regexp :\-)
\&    my $re = $foo\->regexp;
\&
\&    while (<>) {
\&        my %data;
\&        @data{@fields} = /$re/;    # no need for /o, it\*(Aqs a compiled regexp
\&
\&        # now munge the fields
\&        ...
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Regexp::Log is a base class for a variety of modules that generate
regular expressions for performing the usual data munging tasks on
log files that cannot be simply \fBsplit()\fR.
.PP
The goal of this module family is to compute regular expressions
based on the configuration string of the log.
.PP
Please note that there is \fInothing useful\fR you can do with Regexp::Log!
Use one of its derived classes!
.SH "METHODS"
.IX Header "METHODS"
The following methods are available, and form the general \s-1API\s0 for the
derived classes.
.PP
Please note that all the accessors return the new value, if used to set.
.ie n .IP "new( %args )" 4
.el .IP "new( \f(CW%args\fR )" 4
.IX Item "new( %args )"
Return a new Regexp::Log object. A list of key-value pairs can be given
to initialise the object.
.Sp
The default arguments are:
.Sp
.Vb 6
\& format      \- the format of the log line
\& capture     \- the name of the fields to capture with the regexp
\&               (given as an array ref)
\& comments    \- leave the (?#=name) ... (?#!name) comments in the regexp
\& anchor_line \- include begin (^) and end ($) anchor in the regexp
\& modifiers   \- include the modifiers into regexp
.Ve
.Sp
Other arguments (and the corresponding accessors) can be defined in derived
classes.
.ie n .IP "format( $formatstring )" 4
.el .IP "format( \f(CW$formatstring\fR )" 4
.IX Item "format( $formatstring )"
This accessor sets or gets the format string used as a template
to generate the log-matching regexp. This is usually the configuration
line of the log-generating software.
.ie n .IP "capture( @fields )" 4
.el .IP "capture( \f(CW@fields\fR )" 4
.IX Item "capture( @fields )"
Add the elements of \f(CW@fields\fR to the list of fields that the regular
expression should capture (if possible).
.Sp
The method returns the list of actually captured fields, \fBin the same
order as the regular expression captures\fR.
.Sp
The special tags \f(CW\*(C`:none\*(C'\fR and \f(CW\*(C`:all\*(C'\fR can be used to capture none or all
of the fields. \f(CW\*(C`:none\*(C'\fR can also be used to reset a capture list, as shown
in the following example:
.Sp
.Vb 1
\&    my $log = Regexp::Log::Foo\->new( format => $format );
\&
\&    # create a regexp that will capture gmttime and host
\&    $log\->capture(qw( gmttime host ));
\&    my $re1 = $log\->regexp;    # captures gmttime and host
\&
\&    # add username to the list of captured fields
\&    $log\->capture(qw( username ));
\&    my $re2 = $log\->regexp;    # captures gmttime, host and username
\&
\&    # start afresh and capture username and uri
\&    $log\->capture(qw( :none username uri ));
\&    my $re3 = $log\->regexp;    # captures username and uri
.Ve
.Sp
When used to set, this method returns the \fInew\fR list of captured fields,
in capture order.
.IP "regexp( )" 4
.IX Item "regexp( )"
Return a computed regular expression, computed from the data given to 
the Regexp::Log object, and ready to be used in a script.
.IP "regex( )" 4
.IX Item "regex( )"
\&\fBregex()\fR is an alias for the \fBregexp()\fR method.
.IP "fields( )" 4
.IX Item "fields( )"
This method return the list of all the fields that can be captured.
.Sp
For complex subclasses making a lot of modifications in \fB_preprocess()\fR and
\&\fB_postprocess()\fR, the result may not be accurate.
.Sp
The result of \fBfields()\fR is therefore given for information only.
.ie n .IP "comments( $bool )" 4
.el .IP "comments( \f(CW$bool\fR )" 4
.IX Item "comments( $bool )"
Accessor for the \f(CW\*(C`comments\*(C'\fR attribute.
.Sp
Comments are removed by default.
.ie n .IP "modifiers( $modifiers )" 4
.el .IP "modifiers( \f(CW$modifiers\fR )" 4
.IX Item "modifiers( $modifiers )"
Sets the modifiers that govern how the pattern behaves (for
versions of Perl up to 5.9 or so, these are \f(CW\*(C`imsx\*(C'\fR). By
default no flags are enabled.
.ie n .IP "anchor_line( $bool )" 4
.el .IP "anchor_line( \f(CW$bool\fR )" 4
.IX Item "anchor_line( $bool )"
The resulting pattern will be have the \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR
line boundary assertions at the beginning and end
of the pattern, respectively, when the value is true. Set
to 0 to disable.
.ie n .IP "debug( $bool );" 4
.el .IP "debug( \f(CW$bool\fR );" 4
.IX Item "debug( $bool );"
Get/set regexp debug mode.
.Sp
If \f(CW\*(C`debug\*(C'\fR is set, each time a field (or subfield) is matched, its name
(followed by a space) is printed on \s-1STDERR. A\s0 newline is printed at the
beginning of the search. This lets you see where the regexp backtracks,
and watch all its attempts to match something. Useful but usually \fIvery\fR
verbose.
.Sp
This is mainly useful when writing a new Regexp::Log subclass.
.SH "SUBCLASSES"
.IX Header "SUBCLASSES"
This section explains how to create new subclasses of Regexp::Log.
.SS "Package template"
.IX Subsection "Package template"
To implement a Regexp::Log::Foo class, you need to create a package
that defines the appropriate class variables, as in the following
example (this is the complete code for Regexp::Log::Foo!):
.PP
.Vb 1
\&    package Regexp::Log::Foo;
\&
\&    use base qw( Regexp::Log );
\&    use vars qw( $VERSION %DEFAULT %FORMAT %REGEXP );
\&
\&    $VERSION = 0.01;
\&
\&    # default values
\&    %DEFAULT = (
\&        format  => \*(Aq%d %c %b\*(Aq,
\&        capture => [ \*(Aqc\*(Aq ],
\&    );
\&
\&    # predefined format strings
\&    %FORMAT = ( \*(Aq:default\*(Aq => \*(Aq%a %b %c\*(Aq, );
\&
\&    # the regexps that match the various fields
\&    # this is the difficult part
\&    %REGEXP = (
\&        \*(Aq%a\*(Aq => \*(Aq(?#=a)\ed+(?#!a)\*(Aq,
\&        \*(Aq%b\*(Aq => \*(Aq(?#=b)th(?:is|at)(?#!b)\*(Aq,
\&        \*(Aq%c\*(Aq => \*(Aq(?#=c)(?#=cs)\ew+(?#!cs)/(?#=cn)\ed+(?#!cn)(?#!c)\*(Aq,
\&        \*(Aq%d\*(Aq => \*(Aq(?#=d)(?:foo|bar|baz)(?#!d)\*(Aq,
\&    );
\&
\&    # Note that the three hashes (%DEFAULT, %FORMAT and %REGEXP)
\&    # MUST be defined, even if they are empty.
\&
\&    # the _regexp field is an internal field used as a template
\&    # by the regexp()
\&
\&    # the _preprocess method is used to modify the format string
\&    # before the fields are expanded to their regexp value
\&    sub _preprocess {
\&        my $self = shift;
\&
\&        # multiple consecutive spaces in the format are compressed
\&        # to a single space
\&        $self\->{_regexp} =~ s/ +/ /g;
\&    }
\&
\&    # the _postprocess method is used to modify the format string
\&    # after the fields are expanded to their regexp value
\&
\&    1;
.Ve
.PP
Please note that the \fB_preprocess()\fR and \fB_postprocess()\fR method should
only modify the \f(CW\*(C`_regexp\*(C'\fR attribute.
.PP
The comments are removed after \fB_postprocess()\fR is run, if \f(CW\*(C`comments\*(C'\fR
is set to a false value.
.SS "Some explanations on the regexp format"
.IX Subsection "Some explanations on the regexp format"
You may have noticed the presence of \f(CW\*(C`(?#...)\*(C'\fR regexp comments in the
previous example. These are used by Regexp::Log to identify the different
parts of the log line and compute a regular expression that can capture
them.
.PP
These comments work just like \s-1HTML\s0 tags: \f(CW\*(C`(?#=bar)\*(C'\fR marks the beginning
of a field named \fIbar\fR, and \f(CW\*(C`(?#!bar)\*(C'\fR marks the end of the field.
.PP
You'll also notice that \f(CW%c\fR is split in two subfields: \f(CW\*(C`cs\*(C'\fR and
\&\f(CW\*(C`cn\*(C'\fR, which have their own tags.
.PP
Consider the following example script:
.PP
.Vb 6
\&    my $log = Regexp::Log::Foo\->new(
\&        format => \*(Aq:default\*(Aq,
\&        capture => [ qw( c cn ) ],
\&    );
\&    my $re = $log\->regexp;
\&    my @fields = $log\->capture();
\&
\&    while(<>) {
\&        my @data;
\&        @data{@fields} = (/$re/g);
\&
\&        # some more code
\&    }
.Ve
.PP
The \f(CW%data\fR hash will have two keys: \f(CW\*(C`c\*(C'\fR and \f(CW\*(C`cn\*(C'\fR, even though \f(CW\*(C`c\*(C'\fR
already holds the information in \f(CW\*(C`cn\*(C'\fR. This gives log mungers a lot
of flexibility in what they can get from their log lines, with no added
work. Lazyness is a virtue.
.PP
\&\fBImportant notes:\fR
.IP "\(bu" 4
Since Regexp::Log handles all the capturing parentheses
by itself, there must not be any capturing parentheses in any regexp template
of a derived class. If there are capturing parentheses in the values of
\&\f(CW%REGEXP\fR, named captures \fIwill not work\fR.
.IP "\(bu" 4
All the regexp comments that let the Regexp::Log classes find the named
captures must be stored in \f(CW%REGEXP\fR values. Even if you are using a
complex process to create the final regexp (have a look at
Regexp::Log::BlueCoat source code), you \fImust\fR put the special regexp
comments in \f(CW%REGEXP\fR.
.SS "Changing the subclasse default behaviour"
.IX Subsection "Changing the subclasse default behaviour"
If a subclass that is available from \s-1CPAN\s0 is buggy or incomplete, or
does not exactly fit your log files, it's very easy to add to a
Regexp::Log subclass from within your scripts.
.PP
Imagine that the \f(CW%d\fR element of our Regexp::Log::Foo module is
incomplete, because it does not match the string \f(CW\*(C`fu\*(C'\fR that appears
occasionaly (maybe the Regexp::Log::Foo developper didn't know?).
Or that you patched the Foo software so that your own version creates
non-standard log files.
.PP
After emailing the patch to the author, you can temporarily fix your
script by adding the following line:
.PP
.Vb 1
\&    $Regexp::Log::Foo::REGEXP{\*(Aq%d\*(Aq} = \*(Aq(?#=d)(?:fu|foo|bar|baz)(?#!d)\*(Aq
.Ve
.PP
That is to say, by replacing the \f(CW%d\fR entry in the subclass' \f(CW%REGEXP\fR
hash.
.SH "BUGS"
.IX Header "BUGS"
Probably. Most of them should be in the derived classes, though.
.PP
The \fIt/20debug.t\fR test file fails with Perl 5.6.0 and 5.6.1. I have
no idea why, but it may be linked to the use of the \f(CW\*(C`(?{ ... })\*(C'\fR regexp
construct in the debugging code.
.SH "AUTHOR"
.IX Header "AUTHOR"
Philippe 'BooK' Bruhat <book@cpan.org>.
.SH "LICENCE"
.IX Header "LICENCE"
This module is free software; you can redistribute it or modify it under
the same terms as Perl itself.