NAME

       Catmandu::Importer::Text - Package that imports textual data

SYNOPSIS

           # From the command line

           # separate fields by whitespace sequences just like awk
           catmandu convert Text --split '\s+'

           # import all lines starting with '#', omitting this character
           catmandu convert Text --pattern '^#(.*)'

           # In a Perl script

           use Catmandu;

           my $importer = Catmandu->importer('Text' , file => "/foo/bar.txt" );

           # print all lines with line number
           $importer->each(sub {
               my $item = $_[0];
               printf "%d: %s" , $item->{_id} , $item->{text};
           });

DESCRIPTION

       This package reads textual input line by line. Each line is imported as item with line
       number in field "_id" and text content in field "text". 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.

CONFIGURATION

       file
           Read input from a local file given by its path. Alternatively a scalar reference can
           be passed to read from a string.

       fh  Read input from an IO::Handle. If not specified, Catmandu::Util::io is used to create
           the input stream from the "file" argument or by using STDIN.

       encoding
           Binmode of the input stream "fh". Set to ":utf8" by default.

       fix An ARRAY of one or more fixes or file scripts to be applied to imported items.

       split
           Single Character or regular expression (as string with a least two characters), to
           split each line.  Resulting parts are imported in field "text" as array.

       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 "match"
           instead of "text".

           For instance dates in "YYYY-MM-DD" format can be imported as named fields with

              (?<year>\d\d\d\d)-(?<month>\d\d)-(?<day>\d\d)

           or as array with

              (\d\d\d\d)-  # year
              (\d\d)-      # month
              (\d\d)       # day

METHODS

       Every Catmandu::Importer is a Catmandu::Iterable with all its methods inherited.

SEE ALSO

       Catmandu::Exporter::Text

       Catmandu::Fix::parse_text

       Unix tools awk <https://en.wikipedia.org/wiki/AWK> and sed
       <https://en.wikipedia.org/wiki/Sed>