.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Catmandu::Importer::Text 3pm"
.TH Catmandu::Importer::Text 3pm "2023-03-03" "perl v5.36.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"
Catmandu::Importer::Text \- Package that imports textual data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # From the command line
\&
\&    # separate fields by whitespace sequences just like awk
\&    catmandu convert Text \-\-split \*(Aq\es+\*(Aq
\&
\&    # import all lines starting with \*(Aq#\*(Aq, omitting this character
\&    catmandu convert Text \-\-pattern \*(Aq^#(.*)\*(Aq
\&
\&    # In a Perl script
\&
\&    use Catmandu;
\&
\&    my $importer = Catmandu\->importer(\*(AqText\*(Aq , file => "/foo/bar.txt" );
\&
\&    # print all lines with line number
\&    $importer\->each(sub {
\&        my $item = $_[0];
\&        printf "%d: %s" , $item\->{_id} , $item\->{text};
\&    });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package reads textual input line by line. Each line is
imported as item with line number in field \f(CW\*(C`_id\*(C'\fR and text content in field
\&\f(CW\*(C`text\*(C'\fR. Line separators are not included. Lines can further be split by
character or pattern and a regular expression can be specified to only import
selected lines and to translate pattern groups to fields.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.IP "file" 4
.IX Item "file"
Read input from a local file given by its path. Alternatively a scalar
reference can be passed to read from a string.
.IP "fh" 4
.IX Item "fh"
Read input from an IO::Handle. If not specified, Catmandu::Util::io is used to
create the input stream from the \f(CW\*(C`file\*(C'\fR argument or by using \s-1STDIN.\s0
.IP "encoding" 4
.IX Item "encoding"
Binmode of the input stream \f(CW\*(C`fh\*(C'\fR. Set to \f(CW\*(C`:utf8\*(C'\fR by default.
.IP "fix" 4
.IX Item "fix"
An \s-1ARRAY\s0 of one or more fixes or file scripts to be applied to imported items.
.IP "split" 4
.IX Item "split"
Single Character or regular expression (as string with a least two characters),
to split each line.  Resulting parts are imported in field \f(CW\*(C`text\*(C'\fR as array.
.IP "pattern" 4
.IX Item "pattern"
Regular expression, given as string, to only import matching lines.
Whitespaces in patterns are ignored or must be escaped if patterns consists of
multiple lines. If the pattern contains capturing groups, captured values are
imported in field \f(CW\*(C`match\*(C'\fR instead of \f(CW\*(C`text\*(C'\fR.
.Sp
For instance dates in \f(CW\*(C`YYYY\-MM\-DD\*(C'\fR format can be imported as named fields with
.Sp
.Vb 1
\&   (?<year>\ed\ed\ed\ed)\-(?<month>\ed\ed)\-(?<day>\ed\ed)
.Ve
.Sp
or as array with
.Sp
.Vb 3
\&   (\ed\ed\ed\ed)\-  # year
\&   (\ed\ed)\-      # month
\&   (\ed\ed)       # day
.Ve
.SH "METHODS"
.IX Header "METHODS"
Every Catmandu::Importer is a Catmandu::Iterable with all its methods
inherited.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catmandu::Exporter::Text
.PP
Catmandu::Fix::parse_text
.PP
Unix tools awk <https://en.wikipedia.org/wiki/AWK> and
sed <https://en.wikipedia.org/wiki/Sed>