.\" 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
.\" ========================================================================
.\"
.IX Title "STAG-FILTER 1p"
.TH STAG-FILTER 1p "2022-06-12" "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"
stag\-filter \- filters a stag file (xml, itext, sxpr) for nodes of interest
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  stag\-filter person \-q name=fred file1.xml
\&
\&  stag\-filter person \*(Aqsub {shift\->get_name =~ /^A*/}\*(Aq file1.xml
\&
\&  stag\-filter \-p My::Foo \-w sxpr record \*(Aqsub{..}\*(Aq file2
.Ve
.SH "USAGE"
.IX Header "USAGE"
.Vb 1
\&  stag\-filter [\-p|parser PARSER] [\-w|writer WRITER] NODE \-q tag=val FILE
\&
\&  stag\-filter [\-p|parser PARSER] [\-w|writer WRITER] NODE SUB FILE
\&
\&  stag\-filter [\-p|parser PARSER] [\-w|writer WRITER]  NODE \-f PERLFILE FILE
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
parsers an input file using the specified parser (which may be a built
in stag parser, such as xml) and filters the resulting stag tree
according to a user-supplied subroutine, writing out only the
nodes/elements that pass the test.
.PP
the parser is event based, so it should be able to handle large files
(although if the node you parse is large, it will take up more memory)
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
.IP "\-p|parser \s-1FORMAT\s0" 4
.IX Item "-p|parser FORMAT"
\&\s-1FORMAT\s0 is one of xml, sxpr or itext, or the name of a perl module
.Sp
xml assumed as default
.IP "\-w|writer \s-1FORMAT\s0" 4
.IX Item "-w|writer FORMAT"
\&\s-1FORMAT\s0 is one of xml, sxpr or itext, or the name of a perl module
.IP "\-c|count" 4
.IX Item "-c|count"
prints the number of nodes that pass the test
.IP "\-filterfile|f" 4
.IX Item "-filterfile|f"
a file containing a perl subroutine (in place of the \s-1SUB\s0 argument)
.IP "\-q|query TAG1=VAL1 \-q|query TAG2=VAL2 ...  \-q|query TAGN=VALN" 4
.IX Item "-q|query TAG1=VAL1 -q|query TAG2=VAL2 ... -q|query TAGN=VALN"
filters based on the field \s-1TAG\s0
.Sp
other operators can be used too \- eg <, <=, etc
.Sp
multiple q arguments can be passed in
.Sp
for more complex operations, pass in your own subroutine, see below
.IP "\s-1SUB\s0" 4
.IX Item "SUB"
a perl subroutine. this subroutine is evaluated evry time \s-1NODE\s0 is
encountered \- the stag object for \s-1NODE\s0 is passed into the subroutine.
.Sp
if the subroutine passes, the node will be passed to the writer for
display
.IP "\s-1NODE\s0" 4
.IX Item "NODE"
the name of the node/element we are filtering on
.IP "\s-1FILE\s0" 4
.IX Item "FILE"
the file to be parser. If no parser option is supplied, this is
assumed to a be a stag compatible syntax (xml, sxpr or itext);
otherwise you should parse in a parser name or a parser module that
throws stag events
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Stag